> [Agent navigation index](/llms.txt)

# Testing

Brix provides one project-pinned test command for Node and browser Vitest projects, compile-only type tests, managed Playwright end-to-end suites, and Storybook tests.

Choose the test boundary from the behavior under test. The route harness exercises production-configured server infrastructure without a network server. Browser component tests cover Preact UI behavior, MSW isolates code that consumes HTTP, and end-to-end tests verify the complete running application.

Do not use MSW to test a Brix server route. Interception can hide route, middleware, renderer, and application-infrastructure defects. Normal lint also rejects Vitest/Jest module replacement through `brix/no-module-mocking`. Prefer the real harness, MSW at an HTTP-consumer boundary, `vi.fn`, `vi.spyOn`, or an existing dependency injection point.

## Choose a workflow

- [Test API, page, and fragment routes, middleware, auth, rendering, and server errors.](/docs/testing-routes)
- [Test Preact components, islands, stores, browser hooks, and HTTP consumers.](/docs/testing-components)
- [Test navigation, SSR-to-hydration behavior, and the complete running application.](/docs/testing-e2e)

## Select and run test projects

Name Node tests `*.test.*` or `*.spec.*`, browser tests `*.client.test.*` or `*.client.spec.*`, and compile-only public API tests `*.test-d.ts`.

### Run focused checks

```sh
brix test
brix test src/features/profile/api/updateProfile/route.test.ts -t "updates a profile"
brix test --project node
brix test --project browser
brix test --project typecheck
brix test e2e/products.spec.ts -t "opens a product"
brix test --project e2e
brix check

```

Focused Vitest runs do not also run E2E or Storybook. In a workspace, an existing workspace-relative test path selects its owning member automatically. Root `brix test` runs the complete workspace suite, including the shared Storybook catalog. Always await asynchronous assertions such as `.resolves`, `expect.poll`, browser `expect.element`, and file snapshots.

### Browser provisioning

Brix prepares version-matched browsers only when a selected, nonempty browser, E2E, or Storybook suite executes. Working cached browsers are reused. Node-only tests, empty selections, E2E listing, checks, and builds do not download browsers.

For offline provisioning or repair, use `brix playwright install chromium`. Developer runs never install privileged OS packages automatically. On Linux, an administrator may need `brix playwright install-deps chromium`; custom CI can opt into dependency repair with `BRIX_BROWSER_INSTALL_DEPS=1`. `CI=true` alone does not authorize it.

Ordinary tests should not depend on external secrets. Supply request values through the harness `env` fixture. Use `brix test --env` for the test stage, `brix test --stage <stage>` for another configured stage, and `--no-local` to omit local and override files when an integration or E2E test deliberately needs the application environment.

## Compare hydration architectures

Use `runHydrationBenchmark` only to compare controlled, equivalent production deployments. It measures selected island-boundary readiness; it is not an INP or pre-hydration interaction benchmark. See [hydration benchmarks](/docs/testing-e2e#compare-hydration-architectures).

## Test a data-cache store

Custom data-cache adapters can register Brix's Node conformance fixture at test-module scope:

```ts
import { testDataCacheStore } from "brix/test";
import { createMyDataCacheStore } from "./store.ts";

testDataCacheStore("my adapter", async () => createMyDataCacheStore());

```

`testDataCacheStore(name, createStore)` creates a fresh store for each case and verifies reads, writes, tag replacement and eventual invalidation, namespace isolation, repeated invalidation recovery, caller-owned tag safety, and aborted-operation rejection. Use a real isolated backend when its consistency model matters; the fixture creates random namespaces but does not provision or clean up external infrastructure. See [caching](/docs/caching).

Before deployment, `brix verify` runs diagnosis, checks, tests, and the production build without reinstalling dependencies.