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

Managed browser tests resolve Vitest and its optimizer dependencies from the installed Brix package,
even when the app lives under `tools/dashboard` in a non-Brix repository with different tooling.
Do not add Vitest to the nested app or reuse the parent's installation to make browser tests run.

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.

For a new feature, take the cheapest boundary that proves the behavior: route harness first for
server code, a browser component test for UI behavior, and one E2E path only for integration that
depends on the running application. A passing focused test should be followed by the relevant project
suite; run `brix verify` before release or deployment.

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 the boundary

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

## 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`.

The named `node`, `browser`, and `typecheck` projects come from application Vite configs. The
`node` and `browser` projects apply the application's supported `vite.plugins`, `define`, and
`resolve` options; `typecheck` compiles only `src/**/*.test-d.ts` files. Generated
libraries do not have those named projects by default: use `brix test#member-ui`, or `brix test`
inside the library, for ordinary unit tests. Verify a styled library's public API and rendered
styles in a consuming application's typecheck and browser projects under each supported theme.

Type-level assertions belong inside `it` or `test` blocks imported from `brix/test`, even though
the typecheck project compiles rather than executes them. Use `@ts-expect-error` for rejected calls;
a file of top-level expressions alone has no test suite.

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

Managed application tests hide console output from passing tests while retaining failing-test logs,
printed after each failing test finishes. Use `brix test --verbose` for live runner progress and
failure diagnostics without routine passing-test logs. To see all console output while debugging,
run `brix test --verbose --silent=false`. This Vitest setting does not filter external subprocess
output or change Playwright E2E logging.

Managed test projects, including Storybook tests, disable Vitest's persistent module cache
(`fsModuleCache`, enabled by default in Vitest). Brix transforms depend on Panda configuration and
discovered routes outside each module, so cached transforms could survive route or theme changes.
Libraries have no Vitest config, so `brix test` passes `--no-fsModuleCache` for them; a project
with its own `vite.config.*` or `vitest.config.*` keeps that config's setting.

Vitest clears its cache only when an npm, Yarn, pnpm, or Bun install record changes, and Brix
installs write none of them. `brix install`, `brix ci`, and `brix deps add|remove|update` therefore
delete `node_modules/.vitest-cache`, including the one shared by external workspace projects. A
custom `fsModuleCachePath` is not cleared; delete it after dependency changes.

### 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 unit tests should not depend on external secrets. Supply request values through the harness
`env` fixture. Managed full-stack E2E starts a real server and loads the `test-run` stage when no resolved
environment was inherited; keep its values provider-free for offline runs. Use `brix test --env` for
the reserved `test-run` stage, `brix test --stage <stage>` for another configured stage, and
`--no-local` to omit local and override files. See [E2E environment selection](/docs/testing-e2e.md).

## 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.md#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, entries that stay readable after `freshUntil` until `staleUntil`, tag replacement and eventual invalidation, namespace isolation, repeated invalidation recovery, copy safety for written and returned entries, and aborted-operation rejection. Checks that an unrelated invalidation left an entry in place first wait for a control entry sharing the invalidated tag to disappear, so a late wrong invalidation on an eventually consistent backend still fails. 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 [writing a custom store](/docs/caching-stores.md#write-a-custom-store) for the contract it checks.

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

Continue with [route tests](/docs/testing-routes.md), [component tests](/docs/testing-components.md), or
[E2E tests](/docs/testing-e2e.md) based on the behavior—not the file extension you happened to start with.
