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

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.

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.

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

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