Skip to main content

Testing best practices for Hydrogen


Hydrogen 2.0 is out now. These archival Hydrogen 1.0 docs are provided only to assist developers during their upgrade process. Please migrate as soon as possible.

When testing your Hydrogen storefront, make sure you have accounted for any issues that might occur when customers visit your live storefront.

This guide describes best practices for testing your Hydrogen storefront.

Running tests

The Demo Store template contains basic end-to-end (E2E) tests in the /tests/e2e folder. The E2E tests are powered by Vitest and Playwright.

You can use the following command to run tests in development:

yarn test

To run tests in a continuous-integration (CI) environment like GitHub Actions, you can use the following command:

yarn test:ci

Catching common issues

Hydrogen provides an ESLint plugin that enforces Shopify’s JavaScript best practices and catches common issues when using React Server Components in Hydrogen apps.

Hydrogen rules

If you install the ESLint plugin and enable the Hydrogen configuration, then the following Hydrogen rules are included:

server-component-banned-hooksPrevents using the useState, useReducer, useEffect, and useLayoutEffect hooks in files that don't end with the .client extension
client-component-banned-hooksPrevents using the useQuery hook in files that end with the .client extension
prefer-image-componentPrevents using the img tag directly and suggests using the Image component from @shopify/hydrogen
server-no-json-parsePrevents using JSON.parse in a Hydrogen API route or server component
prefer-gqlDetects the use of a GraphQL utility other than the one provided by Hydrogen

Next steps