> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Testing

> Run Catalyst's Playwright UI tests and Vitest unit tests locally, and configure the test environment with .env.test.

Catalyst includes two kinds of tests:

* **UI tests** use [Playwright](https://playwright.dev/docs/intro) to test components and verify workflows in the browser. They live in `tests/`.
* **Unit tests** use [Vitest](https://vitest.dev/) 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`.

> **Note**
>
> 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`.

1. Copy the example file:

   ```shell showLineNumbers={false}
   cp .env.test.example .env.test
   ```

2. 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.

3. 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 UI tests

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

```shell showLineNumbers={false}
pnpm build
pnpm start
```

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

```shell showLineNumbers={false}
pnpm exec playwright test tests/ui/ --project=tests-chromium
```

To run a specific test file:

```shell showLineNumbers={false}
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](https://playwright.dev/docs/test-cli).

## Run the unit tests

```shell showLineNumbers={false}
pnpm test
```

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