Introducing a new way to review your PRs.

Read the announcement

storybookjs / storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation

View on GitHub

20 documents · Updated Nov 20, 2026

docs / testing-fixtures-and-sandboxes

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.

LevelMain questionValidation surface
Story fixtureDoes a component state or Storybook feature produce the expected result?Stories and composed story tests
Portable projectDoes the story run in a supported framework and package setup?Test Storybooks
Browser flowDoes the user-facing Storybook experience work from startup through interaction?Playwright and Cypress
Repository packageDo 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

TriggerConsequenceGuard
A template omits a required expected framework, renderer, or builder valueThe generated project can validate a different stack than the one selectedTemplate 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 tasksCI can run the wrong validation path or omit a needed checkGenerated 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 dependenciesBuild, serve, or test tasks fail before they test StorybookprepareSandbox restores the install and framework-generated files (scripts/prepare-sandbox.ts• L44-79)
A mutating browser spec runs with normal parallel specsFile edits can reload another test page during an assertionPlaywright 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 loadThe story is silently absent from browser-mode story testsSandbox 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 featureA cross-framework test reports a false failureTemplate-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 enabledThe endpoint can lose only test tools, not its full tool surfaceThe 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 fileA focused test request cannot select a valid story setThe 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 ruleDocumentation can come from the wrong Storybook or expose an invalid ref without a clear test failureComposition 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 restoreLater Vitest, browser, or visual jobs cannot test the created projectCreate, workspace, and restore paths use the same sandbox ID and derived path (scripts/…/sandboxes.ts• L269-279, scripts/…/sandboxes.ts• L329-365)

Key files

FileWhy to read it
code/…/sandbox-templates.tsDefines the supported project matrix and each template’s validation limits.
scripts/create-nx-sandbox-projects.tsConverts template choices into generated project metadata and validation targets.
code/…/project.jsonShows the generated target and package links for an Astro Vite TypeScript sandbox.
scripts/…/sandbox.tsShows the high-level path from a template to a runnable sandbox.
scripts/…/sandbox-parts.tsShows how stories, mocks, preview settings, and Vitest support are added to a sandbox.
scripts/prepare-sandbox.tsExplains cache restoration before downstream sandbox tasks.
scripts/…/sandboxes.tsMaps sandbox templates to CI create, smoke, visual, Vitest, end-to-end, and platform jobs.
code/…/storybook.setup.tsShows the readiness contract for browser journeys.
code/…/util.tsDefines shared browser actions and template-aware checks.
code/playwright.config.tsDefines parallel, serial, retry, and artifact behavior for sandbox browser tests.
code/vitest.config.storybook.tsDefines browser-mode story testing for the repository.
test-storybooks/…/package.jsonShows the local validation commands and workspace package links for the broadest portable-story fixture.
test-storybooks/…/Button.stories.tsxGives a compact example of the story states used by composed and browser tests.
test-storybooks/…/package.jsonShows the server-rendered fixture’s Storybook and application-server boundary.
test-storybooks/…/vitest.config.tsShows the separate endpoint and Storybook browser test projects used by the MCP test fixture.
test-storybooks/…/ref-fixtures.tsDefines repeatable public, missing-manifest, and private composed Storybook responses.
test-storybooks/…/mcp-composition.e2e.test.tsShows the endpoint-level contract for composed local and remote Storybook documentation.
test-storybooks/…/mcp-endpoint.e2e.test.tsShows the general MCP session, tool, filter, preview, docs, and story-test contract.