Testing fixtures and sandboxes
Storybook validates product behavior at several levels. Shared stories act as fixtures for component and interaction checks. Framework sandboxes show that the same behavior works in real projects. Browser harnesses then check the running Storybook UI. This page complements Developer workflows and relates to Project setup and migration, Repository automation, and Testing and agent addons.
Validation model
The validation system moves from a small, repeatable story to a complete framework project. Each level answers a different question and gives the next level a useful signal.
| Level | Main question | Validation surface |
|---|---|---|
| Story fixture | Does a component state or Storybook feature produce the expected result? | Stories and composed story tests |
| Portable project | Does the story run in a supported framework and package setup? | Test Storybooks |
| Browser flow | Does the user-facing Storybook experience work from startup through interaction? | Playwright and Cypress |
| Repository package | Do shared packages keep their contracts across the monorepo? | Vitest projects and package tests |
Test Storybooks
Test Storybooks are small projects that exercise Storybook features through normal framework entry points. They keep stories, preview settings, and test commands close to the project shape that users run.
Portable story fixtures
The portable-story kitchen sinks provide shared examples for React, Vue, Svelte, and Next.js. Their stories cover args, decorators, globals, loaders, custom render functions, accessibility states, and framework-specific behavior. The projects point at workspace Storybook packages so a package change can be checked in a realistic application context (test-storybooks/…/package.json• L17-50, test-storybooks/…/package.json• L16-46, test-storybooks/…/package.json• L15-44, test-storybooks/…/package.json• L16-46).
Stories are also inputs to component tests. A test composes the story with its args and annotations, renders it in the framework test environment, and checks the resulting behavior. This keeps the browser story and the lower-level component check aligned (test-storybooks/…/Button.stories.tsx• L7-113, test-storybooks/…/Button.test.tsx• L1-113, test-storybooks/…/Button.test.ts• L1-145).
References: test-storybooks/…/Button.stories.tsx• L7-113 test-storybooks/…/Button.test.tsx• L1-113 test-storybooks/…/Button.test.ts• L1-145
Framework coverage
Each project selects the framework and builder that it represents. The set is intentionally uneven: React has the broadest local test surface, while Svelte, Vue 3, and Next.js leave some commands as explicit gaps or route them to another test layer. A missing target records a coverage limit rather than pretending that a test exists (test-storybooks/…/package.json• L5-15, test-storybooks/…/package.json• L7-13, test-storybooks/…/package.json• L7-14, test-storybooks/…/package.json• L5-14).
The React Storybook also exercises shared preview state and addon behavior. Its configuration supplies a global locale, a decorator, addon coverage, static files, aliases, and links to older Storybook versions. These settings make one fixture useful for both current behavior and compatibility checks (test-storybooks/…/main.ts• L5-47, test-storybooks/…/preview.tsx• L6-29).
References: test-storybooks/…/package.json• L5-15 test-storybooks/…/package.json• L7-13 test-storybooks/…/package.json• L7-14 test-storybooks/…/package.json• L5-14 test-storybooks/…/main.ts• L5-47 test-storybooks/…/preview.tsx• L6-29
Server kitchen sink
The server kitchen sink checks Storybook when a server-rendered component set runs beside an application server. It supports a combined local run and separate Storybook build and server checks, so the fixture covers the boundary between Storybook and a consuming server project (test-storybooks/…/package.json• L9-14).
References: test-storybooks/…/package.json• L9-14 test-storybooks/…/package.json• L47-59
MCP test project
The MCP (Model Context Protocol) test project checks endpoint behavior and Storybook stories in separate Vitest projects. Its end-to-end tests start the needed Storybook configuration and stop it after the run. Local HTTP fixtures stand in for public, manifest-free, and private composed Storybooks, which keeps source and auth cases repeatable without relying on a remote service (test-storybooks/…/vitest.config.ts• L17-45, test-storybooks/…/helpers.ts• L88-129, test-storybooks/…/ref-fixtures.ts• L90-130).
The composition scenarios check that documentation tools can list local and remote sources, fetch a component from either source, omit references without a manifest, and default a missing source ID to the local source. A separate docgen-server configuration checks that local docs remain available through MCP even when the local component manifest is not served over HTTP (test-storybooks/…/mcp-composition.e2e.test.ts• L49-244, test-storybooks/…/mcp-composition-docgen-server.e2e.test.ts• L49-172, test-storybooks/…/main.ts• L4-26).
References: test-storybooks/…/vitest.config.ts• L10-47 test-storybooks/…/helpers.ts• L23-129 test-storybooks/…/ref-fixtures.ts• L15-130 test-storybooks/…/mcp-composition.e2e.test.ts• L49-244 test-storybooks/…/mcp-composition-docgen-server.e2e.test.ts• L49-172
MCP endpoint scenarios
The endpoint harness checks the public MCP contract from session start through tool calls. It covers protocol validation, tool discovery and filtering, story previews, documentation lookup, story test execution, concurrent test requests, and the HTML response path (test-storybooks/…/mcp-endpoint.e2e.test.ts• L32-1194).
The story test tool accepts focused story inputs, story-file path filters, or changed-story selection. File filters require non-empty entries and report an error when no story file matches. This keeps focused test requests explicit while preserving selection from the current working tree or a Git reference (test-storybooks/…/mcp-endpoint.e2e.test.ts• L571-701, test-storybooks/…/mcp-endpoint.e2e.test.ts• L1001-1037).
The project also tests degraded capability instead of treating every missing dependency as a server failure. When the Vitest addon is installed but not enabled, the endpoint keeps its other tools and omits only test execution. When Git is unusable, change detection returns the normal no-change result (test-storybooks/…/mcp-addon-vitest-not-enabled.e2e.test.ts• L5-55, test-storybooks/…/mcp-git-unusable.e2e.test.ts• L5-41, test-storybooks/…/main.ts• L4-13).
Private composition adds a second boundary. The harness checks OAuth discovery, bearer-token gating, remote authentication failures, and local documentation access while authenticated (test-storybooks/…/main.ts• L4-16, test-storybooks/…/mcp-composition-auth.e2e.test.ts• L36-256, test-storybooks/…/ref-fixtures.ts• L61-87).
References: test-storybooks/…/mcp-endpoint.e2e.test.ts• L32-1194 test-storybooks/…/mcp-addon-vitest-not-enabled.e2e.test.ts• L19-55 test-storybooks/…/mcp-git-unusable.e2e.test.ts• L17-41 test-storybooks/…/mcp-composition-auth.e2e.test.ts• L36-256
Code sandboxes
Code sandboxes are generated projects based on the supported template matrix. They test the complete Storybook setup path instead of only a package in isolation. A template declares its expected framework, renderer, and builder. It can also declare which validation tasks do not apply (code/…/sandbox-templates.ts• L33-140).
Template matrix
The matrix spans framework versions, builders, languages, and development states. CI groups templates by cadence and creates only the tasks that the template supports. Generated project metadata connects each template to sandbox creation, build, serve, type checking, Vitest, and end-to-end targets (scripts/create-nx-sandbox-projects.ts• L11-66, scripts/create-nx-sandbox-projects.ts• L68-90).
The generated Astro Vite TypeScript project follows this same model. Its metadata links the sandbox to the core CLI and relevant addons, then exposes sandbox, build, development, serve, and visual-check targets (code/…/project.json• L1-28).
This model tests Storybook as a user would receive it. A template first creates a base application. Storybook is then initialized on top of it. The resulting project becomes the input for all later checks.
References: code/…/sandbox-templates.ts• L33-140 scripts/create-nx-sandbox-projects.ts• L11-66 code/…/project.json• L1-28
Sandbox lifecycle
Sandbox creation turns a template into a repeatable test project. It installs or links the local packages, adds representative stories and mocks, applies framework setup, and prepares the project for the selected validation tasks. The same lifecycle can use linked workspace packages for local debugging or a local registry for a closer release-like check (scripts/…/sandbox.ts• L42-61, scripts/…/sandbox.ts• L80-101, scripts/…/sandbox.ts• L161-215).
The lifecycle separates the generated project from its cache. In Nx runs, the project files are cached without node_modules; a later task restores dependencies and any built Storybook output before it runs. This keeps the cache small while preserving the same project between build, serve, and browser stages (scripts/…/sandbox.ts• L216-247, scripts/prepare-sandbox.ts• L11-29, scripts/prepare-sandbox.ts• L44-91).
The sandbox flow below shows how one template becomes several independent validation paths.
flowchart LR
T[Template definition] --> G[Generated application]
G --> S[Prepared sandbox]
S --> B[Build and serve]
S --> V[Vitest story tests]
B --> E[Playwright browser flows]
B --> C[Visual check]
S --> K[Type check or smoke check]
References: scripts/…/sandbox.ts• L80-101 scripts/…/sandbox.ts• L161-215 scripts/prepare-sandbox.ts• L30-91
Published sandbox projects
Generated sandboxes also serve as public reproduction projects. The generation flow keeps a pre-Storybook project and an after-Storybook project. The publish flow copies successful outputs, adds project documentation, removes install-only data, and commits the result to the sandbox repository (scripts/…/generate.ts• L385-407, scripts/…/publish.ts• L47-91).
References: scripts/…/generate.ts• L385-407 scripts/…/publish.ts• L47-91
End-to-end harnesses
End-to-end harnesses drive a running Storybook through a browser. They check the manager, preview, addons, navigation, and framework behavior as a user sees them.
Sandbox browser journeys
The shared sandbox suite runs against the sandbox selected by STORYBOOK_TEMPLATE_NAME and STORYBOOK_URL. A setup test waits for the Storybook index and a known story before other tests start. SbPage then provides common actions for loading stories, using the preview iframe, opening addon panels, and waiting for stable UI state (code/…/storybook.setup.ts• L1-45, code/…/util.ts• L8-18, code/…/util.ts• L123-179).
The tests focus on product behavior that should remain stable across templates. Examples include addon controls, accessibility results, component interactions, static files, framework rendering, and module mocking. Template metadata allows a journey to skip a feature when the framework cannot support it (code/…/addon-a11y.spec.ts• L8-47, code/…/component-tests.spec.ts• L9-45, code/…/util.ts• L382-405).
Mutating journeys run after the parallel browser pass and use one worker. This prevents a test that edits sandbox files from changing the server state seen by another page (code/playwright.config.ts• L10-12, code/playwright.config.ts• L61-96).
References: code/…/storybook.setup.ts• L1-45 code/…/util.ts• L8-18 code/…/util.ts• L123-179 code/playwright.config.ts• L61-96
Internal Storybook journeys
The internal harness tests the repository’s own Storybook rather than a generated user project. It waits for the internal server, then runs focused browser checks with the same failure traces and CI result reporting used by the other Playwright path (scripts/…/e2e-tests-internal.ts• L9-42, code/…/playwright.config.ts• L1-34).
The two harnesses have different roles. Sandbox journeys compare framework projects. Internal journeys protect the repository’s main Storybook and its local integration points.
References: scripts/…/e2e-tests-internal.ts• L9-42 code/…/playwright.config.ts• L1-34
Shared test configuration
Shared configuration keeps package tests consistent while allowing browser tests and framework projects to add their own needs. It defines common setup, package resolution rules, time limits, browser mode, and CI reporting.
Story test configuration
Repository Vitest projects resolve workspace packages to source and apply one setup file. The setup adds DOM matchers, shared assertions, approved console handling, and common mocks. The root configuration collects package projects and the Storybook browser project when the environment supports it (code/vitest.shared.ts• L23-47, code/vitest-setup.ts• L1-43, vitest.config.ts• L15-33).
The Storybook browser project runs stories tagged for Vitest in Chromium. This gives story tests a real browser surface while keeping ordinary package tests in their normal environment (code/vitest.config.storybook.ts• L21-65). Sandbox setup applies the same idea to generated projects by selecting only stories with the vitest tag (scripts/…/sandbox-parts.ts• L564-641).
References: code/vitest.shared.ts• L23-47 code/vitest-setup.ts• L1-43 vitest.config.ts• L15-33 code/vitest.config.storybook.ts• L21-65 scripts/…/sandbox-parts.ts• L564-641
Validation task paths
The task runner exposes separate checks because each one gives a different kind of confidence:
- A smoke test confirms that Storybook can start.
- A type check confirms that the generated project accepts its public types.
- Vitest runs story tests in the sandbox and stores browser diagnostics.
- End-to-end tasks run browser journeys against development or built Storybook output.
These tasks share the prepared sandbox but do not share the same assertion layer. A passing smoke test therefore does not replace a browser journey or a type check (scripts/…/smoke-test.ts• L4-14, scripts/…/check-sandbox.ts• L5-14, scripts/…/vitest-test.ts• L19-65, scripts/…/e2e-tests-build.ts• L12-59).
References: scripts/…/smoke-test.ts• L4-14 scripts/…/check-sandbox.ts• L5-14 scripts/…/vitest-test.ts• L19-65 scripts/…/e2e-tests-build.ts• L12-59
Continuous integration sandbox flows
CI maps each selected template to a create job and then to the validation jobs that its metadata allows. The create stage builds the sandbox, stores it as a workspace artifact, and can verify docgen baselines. Later stages restore that same sandbox for development smoke or browser checks, visual checks, browser-mode Vitest, and built Storybook end-to-end checks (scripts/…/sandboxes.ts• L187-283, scripts/…/sandboxes.ts• L293-395).
The CI flow also covers platform and cost boundaries. Daily workflows add Windows build and development browser jobs. Slow development templates use more workers and larger executors, while templates with skipped tasks do not receive jobs for those checks. This keeps coverage tied to the supported template and avoids treating every framework as identical (scripts/…/sandboxes.ts• L88-109, scripts/…/sandboxes.ts• L283-291, scripts/…/sandboxes.ts• L415-525, scripts/…/sandboxes.ts• L528-548).
References: scripts/…/sandboxes.ts• L187-283 scripts/…/sandboxes.ts• L293-395 scripts/…/sandboxes.ts• L415-525 scripts/…/sandboxes.ts• L528-548
Change checklist
When these files or sections are changed, remember to consider these:
- When a template changes its framework, renderer, or builder, update its expected metadata and confirm that generated Nx targets still match its supported tasks.
- When a generated sandbox project changes its target set or implicit package links, confirm that the template generator and CI task selection still describe the same validation paths.
- When a story changes its title, name, or tags, check both composed tests and browser journeys that use its Storybook ID.
- When a sandbox setup changes, check both linked-package runs and local-registry runs. They exercise different dependency paths.
- When a Playwright journey writes to sandbox files, keep it in the serial mutating project so it cannot affect parallel pages.
- When shared Vitest setup or browser conditions change, check both package projects and the Storybook browser project.
- When a test command or output path changes, keep CI result and artifact collection aligned with the task runner.
- When MCP composition fixtures change, keep public, no-manifest, and private source behavior aligned with the matching Storybook configuration and endpoint expectations.
- When MCP tool availability changes, update both the normal endpoint contract and the installed-but-not-enabled case.
- When MCP test-run filters change, keep non-empty file validation, path matching, no-match errors, and changed-story selection aligned with the endpoint schema and behavior.
- When MCP test projects change, keep endpoint tests and Storybook browser tests mapped to their intended project and browser mode.
- When CI sandbox stages or skip rules change, keep workspace packing, artifact paths, and downstream restore steps aligned across Linux and Windows jobs.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A template omits a required expected framework, renderer, or builder value | The generated project can validate a different stack than the one selected | Template metadata is checked when the sandbox is generated (code/…/sandbox-templates.ts• L49-57) |
| Generated project metadata exposes targets that do not match the template’s supported tasks | CI can run the wrong validation path or omit a needed check | Generated project targets are derived from the template matrix (scripts/create-nx-sandbox-projects.ts• L68-90, code/…/project.json• L13-26) |
| A cached sandbox is used without restoring dependencies | Build, serve, or test tasks fail before they test Storybook | prepareSandbox restores the install and framework-generated files (scripts/prepare-sandbox.ts• L44-79) |
| A mutating browser spec runs with normal parallel specs | File edits can reload another test page during an assertion | Playwright isolates mutating specs in a serial one-worker project (code/playwright.config.ts• L81-96) |
A story loses the vitest tag or its project setup cannot load | The story is silently absent from browser-mode story tests | Sandbox setup selects the tag and the shared project uses the Storybook Vitest plugin (scripts/…/sandbox-parts.ts• L620-641, code/vitest.config.storybook.ts• L27-35) |
| A framework cannot support a shared browser feature | A cross-framework test reports a false failure | Template-aware checks skip only the unsupported feature (code/…/component-tests.spec.ts• L15-24, code/…/util.ts• L392-405) |
| The MCP Vitest addon is installed but not enabled | The endpoint can lose only test tools, not its full tool surface | The no-addon configuration and endpoint test require other tools to remain available (test-storybooks/…/main.ts• L4-13, test-storybooks/…/mcp-addon-vitest-not-enabled.e2e.test.ts• L19-54) |
| An MCP file filter is empty or matches no story file | A focused test request cannot select a valid story set | The endpoint schema rejects empty entries and reports a no-match error (test-storybooks/…/mcp-endpoint.e2e.test.ts• L600-607, test-storybooks/…/mcp-endpoint.e2e.test.ts• L1001-1024) |
| MCP composition fixtures lose a source ID, manifest, or default-source rule | Documentation can come from the wrong Storybook or expose an invalid ref without a clear test failure | Composition and fixture tests assert local, remote, missing-manifest, default-source, and auth behavior (test-storybooks/…/ref-fixtures.ts• L43-87, test-storybooks/…/mcp-composition.e2e.test.ts• L49-244) |
| A CI job packs a sandbox under a path that a downstream job does not restore | Later Vitest, browser, or visual jobs cannot test the created project | Create, workspace, and restore paths use the same sandbox ID and derived path (scripts/…/sandboxes.ts• L269-279, scripts/…/sandboxes.ts• L329-365) |
Key files
| File | Why to read it |
|---|---|
| code/…/sandbox-templates.ts | Defines the supported project matrix and each template’s validation limits. |
| scripts/create-nx-sandbox-projects.ts | Converts template choices into generated project metadata and validation targets. |
| code/…/project.json | Shows the generated target and package links for an Astro Vite TypeScript sandbox. |
| scripts/…/sandbox.ts | Shows the high-level path from a template to a runnable sandbox. |
| scripts/…/sandbox-parts.ts | Shows how stories, mocks, preview settings, and Vitest support are added to a sandbox. |
| scripts/prepare-sandbox.ts | Explains cache restoration before downstream sandbox tasks. |
| scripts/…/sandboxes.ts | Maps sandbox templates to CI create, smoke, visual, Vitest, end-to-end, and platform jobs. |
| code/…/storybook.setup.ts | Shows the readiness contract for browser journeys. |
| code/…/util.ts | Defines shared browser actions and template-aware checks. |
| code/playwright.config.ts | Defines parallel, serial, retry, and artifact behavior for sandbox browser tests. |
| code/vitest.config.storybook.ts | Defines browser-mode story testing for the repository. |
| test-storybooks/…/package.json | Shows the local validation commands and workspace package links for the broadest portable-story fixture. |
| test-storybooks/…/Button.stories.tsx | Gives a compact example of the story states used by composed and browser tests. |
| test-storybooks/…/package.json | Shows the server-rendered fixture’s Storybook and application-server boundary. |
| test-storybooks/…/vitest.config.ts | Shows the separate endpoint and Storybook browser test projects used by the MCP test fixture. |
| test-storybooks/…/ref-fixtures.ts | Defines repeatable public, missing-manifest, and private composed Storybook responses. |
| test-storybooks/…/mcp-composition.e2e.test.ts | Shows the endpoint-level contract for composed local and remote Storybook documentation. |
| test-storybooks/…/mcp-endpoint.e2e.test.ts | Shows the general MCP session, tool, filter, preview, docs, and story-test contract. |