Testing for performance

Use field data to find problems, lab data to debug them, and field data again to verify fixes landed.

Performance testing isn't a single tool or single moment. It combines:

• Field data: What real users experience, captured through RUM.
• Lab data: Controlled synthetic measurements for debugging and regression detection.

Use field data to identify what to fix. Use lab data to confirm your fixes work. See Lab vs. field data for a detailed explanation of the difference.

Anchor to Field dataField data

Anchor to Shopify Web Performance DashboardShopify Web Performance Dashboard

The Shopify Web Performance Dashboard provides Real User Monitoring (RUM) data collected directly from your store visitors. It reports Core Web Vitals (LCP, INP, and CLS) broken down by page type, device category, and geographic region.

Access the dashboard from your Shopify admin. Data is collected from Chrome users who have opted into sharing performance metrics.

Key uses:

• Establish a performance baseline for your store.
• Detect regressions after deployments or app installations.
• Identify which page types or device segments have the worst metrics.
• Verify that optimizations improved the real user experience.

For Hydrogen storefronts, analytics integration is required to send data to the dashboard. See Performance best practices for Hydrogen storefronts for setup details.

Anchor to Performance data in the GraphQL Admin APIPerformance data in the GraphQL Admin API

You can query your store's performance data programmatically with two root fields:

• performanceMetrics: Returns RUM metrics as JSON, one entry per device type. It accepts aggregationLevel, deviceTypes, maxDays, and storefrontId. There's no page-type dimension.
• performanceEvents: Returns events that affect storefront performance, such as app installs and theme publications. It accepts maxDays.

Both fields require access to themes and reports. They're useful for building custom dashboards, triggering alerts on regressions, or correlating metric changes with app and theme events.

Anchor to Chrome User Experience Report (CrUX)Chrome User Experience Report (CrUX)

CrUX provides public RUM data from Chrome users aggregated by origin. It's the data source behind PageSpeed Insights and Google Search Console's Core Web Vitals report. Tools like TREO Site Speed provide a convenient interface for exploring CrUX data for any publicly accessible domain.

CrUX requires sufficient traffic to populate. Low-traffic pages might not have enough data for reliable measurements.

Anchor to Lab testingLab testing

Anchor to When to use Lighthouse vs. RUMWhen to use Lighthouse vs. RUM

Use RUM (field data) when:

• You want to know what real users are experiencing.
• You need to establish a baseline before and after a change.
• You're making strategic decisions about what to optimize.
• You're verifying that a change improved performance.

Use Lighthouse (lab data) when:

• You want to debug a specific performance issue.
• You need repeatable, comparable measurements during development.
• You want to run automated checks in CI/CD before merging.
• RUM data is insufficient, for example, on a new store, a low-traffic store, or a development store.

Anchor to Running the Shopify benchmarkRunning the Shopify benchmark

Shopify evaluates Theme Store submissions against a benchmark shop to produce consistent, comparable performance scores. You can run the same benchmark to evaluate your own theme.

The benchmark uses a development store pre-loaded with standardized test products. This isolates theme performance from store-specific content variables.

Anchor to Step 1: Create a development storeStep 1: Create a development store

Create a new development store in your Shopify Partner account. The store must be separate from any production store.

Anchor to Step 2: Import test productsStep 2: Import test products

Import the standardized test product catalog using the CSV file at:

Test product CSV

In your Shopify admin, navigate to Products > Import and upload the CSV file. This populates the store with the same product data used in Shopify's official evaluations.

Anchor to Step 3: Get a preview linkStep 3: Get a preview link

In your development store, beside Online Store, click the eye icon to preview your store. In the preview bar, click the link icon to copy the preview link. This gives you a shopifypreview.com URL that performance testing tools like Lighthouse can access without a store password.

Anchor to Step 4: Get URLs for home, product, and collection pagesStep 4: Get URLs for home, product, and collection pages

Get the URLs for the pages that you want to audit. You should test the home page, any product page, and any collection page.

For example, if your preview link is https://12345678.shopifypreview.com, then the URL for a product page is https://12345678.shopifypreview.com/products/sunglasses.

Anchor to Step 5: Append ,[object Object], to each URLStep 5: Append pb=0 to each URL

Append pb=0 (preview bar off) to each URL to prevent the preview bar from displaying during the audit, which could skew results.

For example, https://12345678.shopifypreview.com/products/sunglasses becomes https://12345678.shopifypreview.com/products/sunglasses?pb=0.

Anchor to Step 6: Run Google Lighthouse on each pageStep 6: Run Google Lighthouse on each page

Run Lighthouse on each of the three URLs. For consistent results:

• Use Chrome in Incognito mode to avoid extension interference.
• Run each URL at least three times and use the median score.
• Use the same device and network conditions for all runs.

You can run Lighthouse through:

• Chrome DevTools > Lighthouse tab.
• The Lighthouse CLI: npx lighthouse {url} --output json.
• PageSpeed Insights.

Record the Performance score (0 to 100) for each page.

Anchor to Step 7: Calculate the speed scoreStep 7: Calculate the speed score

Shopify's speed score is a weighted average of the three page scores:

• Home page: 17 percent.
• Product page: 40 percent.
• Collection page: 43 percent.

The weights reflect the relative importance of each page type to merchant conversions. Collection and product pages carry the most weight.

The weighted score isn't the bar the Shopify Theme Store checks. Acceptance requires a minimum average Lighthouse performance score of 60 across the product, collection, and home page, on both desktop and mobile, and that requirement is a plain average of the three page scores. Use the weighted score to see how a change moves the pages that matter most to merchants, and the plain average to check whether you clear the submission bar. See Lighthouse performance and accessibility requirements.

Anchor to Lighthouse CILighthouse CI

Lighthouse CI (LHCI) automates Lighthouse audits on every pull request, preventing performance regressions before they reach production.

Anchor to Shopify Lighthouse CI GitHub ActionShopify Lighthouse CI GitHub Action

Shopify provides an official Lighthouse CI GitHub Action for theme development. The action:

• Runs Lighthouse against a preview of your theme on each pull request.
• Comments score changes on the pull request.
• Can fail the CI check if scores drop below a threshold.

To set up the Shopify Lighthouse CI GitHub Action, add a workflow file to your repository at .github/workflows/lighthouse.yml. See Lighthouse CI for a full walkthrough, including store setup, and the Shopify Lighthouse CI Action documentation for the current configuration syntax and required secrets.

Anchor to Interpreting CI resultsInterpreting CI results

When Lighthouse CI reports a score drop:

1. Check whether the regression is in the lab score or in real user data. Lab regressions aren't always user-visible.
2. Identify which metric changed (LCP, TBT, or CLS) to narrow down the cause.
3. Use the metric gap analysis approach to diagnose the root cause.
4. Revert or fix the change before merging.

Anchor to ReferencesReferences

• Shopify Web Performance Dashboard
• Lighthouse CI
• Shopify Lighthouse CI Action
• Google Lighthouse documentation
• Chrome User Experience Report (CrUX)
• Lab vs. field data
• Debugging with metric gaps
• Build a sustainable performance practice