Testing

Catalyst includes two kinds of tests:

UI tests use Playwright to test components and verify workflows in the browser. They live in tests/.
Unit tests use Vitest and live alongside the code they test, as lib/**/*.spec.ts files.

Run all of the commands on this page from your project root, the directory that contains package.json.

If your project uses the older monorepo structure, run them from the core/ directory instead.

Set up the test environment

UI tests read your existing .env.local, plus a .env.test file for test-specific settings. Values in .env.test override those in .env.local.

Copy the example file:
```
cp .env.test.example .env.test
```
In .env.test, set PLAYWRIGHT_TEST_BASE_URL to the storefront the tests should run against. It defaults to http://localhost:3000. To test a deployed storefront, set it to that storefront’s URL.

Optionally, set the other variables in .env.test. The comments in .env.test.example describe each one:

Variable	Purpose
`TESTS_READ_ONLY`	When `true`, skips any test that creates, modifies, or deletes store data. Use this when testing against a live store.
`BIGCOMMERCE_ACCESS_TOKEN`	An API account access token the tests use to read, and when `TESTS_READ_ONLY` is `false`, create and clean up store data. Some tests fail without it. `.env.test.example` lists the scopes it needs.
`BIGCOMMERCE_CLIENT_ID`, `BIGCOMMERCE_CLIENT_SECRET`	Required for the JWT login tests. Those tests are skipped if these aren’t set.
`TEST_CUSTOMER_ID`, `TEST_CUSTOMER_EMAIL`, `TEST_CUSTOMER_PASSWORD`	An existing customer account to use instead of creating one.
`DEFAULT_PRODUCT_ID`, `DEFAULT_COMPLEX_PRODUCT_ID`	A simple product and a product with variants to use in product tests.
`TESTS_LOCALE`, `TESTS_FALLBACK_LOCALE`	The locale to test in, and the fallback for missing translation keys. Both default to `en`.

Run the tests against a production build so they include your latest changes. Build and start the storefront first:

pnpm build
pnpm start

Then, in another terminal, run all UI tests in Chromium:

pnpm exec playwright test tests/ui/ --project=tests-chromium

To run a specific test file:

pnpm exec playwright test tests/visual-regression/components/badge.spec.ts --project=tests-chromium

Catalyst’s Playwright config defines two projects:

tests-chromium runs every test except mobile tests.
tests-webkit-mobile runs only *.mobile.spec.ts files, on a mobile WebKit device.

To run a single test by name, add -g "<test name>". For more options, see the Playwright CLI documentation.

pnpm test

This runs Vitest against the lib/**/*.spec.ts files. Playwright specs in tests/ aren’t included.