Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Testing and toolingRead Markdown
    On this page

    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

    #

    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.