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.
- Test Preact components, islands, stores, browser hooks, and HTTP consumers.
- Test navigation, SSR-to-hydration behavior, and the complete running application.
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
#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.
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.
Test a data-cache store
#Custom data-cache adapters can register Brix's Node conformance fixture at test-module scope:
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 for the contract it checks.
Before deployment, brix verify runs diagnosis, checks, tests, and the production build without reinstalling dependencies.
Continue with route tests, component tests, or E2E tests based on the behavior—not the file extension you happened to start with.