Testing and agent addons
The testing and agent addons connect Storybook stories to two kinds of automated work. @storybook/addon-vitest turns stories into runnable Vitest checks, while @storybook/addon-mcp exposes Storybook data, story workflows, and test runs to MCP clients such as AI agents. The smaller @storybook/mcp package provides the reusable documentation part of that MCP surface for hosted Storybooks and other embedders. See the addon ecosystem for the wider addon model and user-facing addons for addons aimed at people in the Storybook UI.
System boundary
The system has one shared source of truth: Storybook stories and their indexed metadata. Vitest uses that source to select and run checks. MCP uses it to help an automated client discover components, find story IDs, preview changes, publish reviews, and validate the result.
Addon relationship
@storybook/addon-vitest supplies the test capability. @storybook/addon-mcp supplies the agent-facing MCP server and maps the test capability to the test-run MCP tool when the test addon is enabled. The MCP addon treats Vitest as optional, so documentation and development tools remain available when test support is not installed. This keeps test execution in the Vitest addon while allowing the MCP addon to present a single workflow to an agent. The MCP server computes capability availability before it registers tools and uses the same availability to build its instructions. If a backing toolset is missing, it drops only that tool and records the wiring error instead of stopping the full MCP server.
References: code/…/package.json• L1-17 code/…/package.json• L1-8 code/…/package.json• L50-57 code/…/mcp-handler.ts• L25-73 code/…/tool-registry.ts• L70-97 code/…/tool-registry.ts• L186-249
Data boundaries
The test path consumes the Storybook story index and returns run status, story status, accessibility status, reports, and coverage when available. The documentation path consumes component and documentation manifests, which can include prop information, story examples, and docs entries. These outputs give automated tools grounded data instead of requiring them to infer behavior from source names.
References: code/…/definition.ts• L34-117 code/…/types.ts• L32-40 code/…/types.ts• L150-233
Vitest testing
The Vitest addon makes a Storybook story a runnable test unit. It combines the story's render setup and play behavior with Vitest so the same scenarios can run from the Storybook UI, the command line, or an automated tool.
Story-driven test model
The addon reads the stories configured for Storybook and adds them to a Vitest project. It applies Storybook setup and transforms so tests run with the same framework configuration, globals, tags, and preview context that the stories use. Vitest projects can also provide initial globals to composed stories, so a story can verify that config values reach its test context. Browser mode is supported when the project provides the matching Vitest browser setup.
The setup flow can merge the Storybook Vitest project into an existing Vitest configuration. It preserves the user's own projects and keeps run-wide options at the top level, so adding Storybook checks does not silently remove the project's other test work.
The test tool supports three ways to narrow a run: story inputs, story-file filters, and changed stories. These filters can be combined. Omitting them runs all available stories. This gives focused repair and final verification the same test contract.
References: code/…/index.ts• L197-212 code/…/index.ts• L231-281 code/…/index.ts• L378-447 code/…/updateVitestFile.ts• L158-185 code/…/updateVitestFile.ts• L329-372 code/…/updateVitestFile.ts• L425-449 code/…/definition.ts• L148-188 code/…/InitialGlobals.stories.tsx• L7-30 code/…/package.json• L110-125
Test run lifecycle
When a run starts, the addon resolves the requested stories against the current story index. It then asks the Vitest runner to execute the selected set and collects component and accessibility results. It publishes status and report data to Storybook and returns a final run record to the caller.
The tool keeps selection and execution separate. An unknown story or an invalid file filter is reported instead of silently running a smaller set. A changed-story selection can pass with no tests when no stories changed. A completed run still fails when component checks, unhandled errors, or enabled accessibility checks fail. Accessibility warnings do not fail the run. Accessibility errors do not affect the verdict when the run disables accessibility.
The result distinguishes a completed run from no matching stories, a setup or transport error, and cancellation. Completed results carry structured counts and reports. The formatter also creates a readable report with passing stories, failing stories, accessibility findings, unhandled errors, and the final verdict. The same report serves MCP and the tools CLI.
References: code/…/run.ts• L31-142 code/…/run.ts• L174-317 code/…/definition.ts• L41-120 code/…/format.ts• L101-124 code/…/format.ts• L337-435 code/…/format.ts• L442-513 code/…/boot-test-runner.ts• L63-74 code/…/boot-test-runner.ts• L193-251 code/…/boot-test-runner.ts• L289-350 code/…/TestProviderRender.tsx• L109-209 code/…/TestProviderRender.tsx• L270-435
Automated test interface
The addon registers a public test toolset with one main action: run. Its input accepts story selectors, file filters, changed-story selection, and an accessibility-test flag that defaults to enabled. Its output carries both a machine-readable result and a readable summary.
The tool favors story IDs when the caller already discovered them through documentation. A path and export name remain useful when the caller is working in a story file. A caller can use a branch, tag, or commit reference with changed-story selection. If a selector list is only partly valid, the run reports the mismatch rather than silently testing a smaller set.
The tool serializes concurrent runs for one registration. It also guides the caller to the test-stories skill before the first run when the transport supports that guidance, so an agent follows the test workflow instead of replacing it with a shell-level check. Tool descriptions stay plain and within the MCP client description limit, and all registered input and output schemas must convert to MCP JSON Schema so one invalid schema cannot break tool discovery.
References: code/…/definition.ts• L96-120 code/…/definition.ts• L148-235 code/…/definition.ts• L320-367 code/…/run.ts• L195-259 code/…/format.ts• L482-513 code/…/tool-descriptions.test.ts• L11-16 code/…/tool-descriptions.test.ts• L64-113
MCP agent access
MCP, the Model Context Protocol, is the interface that lets an external tool or AI agent call Storybook capabilities through a standard server connection. The addon serves that interface from the running Storybook, normally at /mcp, and exposes only the toolsets that the current Storybook can support.
MCP endpoint
The MCP addon adds an HTTP endpoint to the Storybook development server. An MCP client initializes a session, lists tools, and calls a tool with validated input. The server returns text for agent context and structured data where a client needs stable fields.
The endpoint converts the Storybook server's request and response types to the Web API types used by the MCP transport. It initializes the shared server once, even when requests arrive at the same time. It also buffers tool output so an authentication error found while a tool reads a remote manifest can become a clear 401 response with OAuth guidance. The endpoint can use a configured URL pathname instead of /mcp.
The endpoint accepts JSON MCP requests and applies the Storybook host and origin gates before dispatch. A request may narrow the active toolsets with the X-MCP-Toolsets header. Its instructions and status view reflect the same availability checks used for tool registration.
This diagram shows how an automated client reaches the available Storybook capabilities and their data sources.
flowchart LR
A[Agent or automated tool] -->|MCP request| B[Storybook MCP endpoint]
B --> C{Enabled toolset}
C -->|dev| D[Story and review workflows]
C -->|docs| E[Component and story documentation]
C -->|test| F[Vitest story tests]
D --> G[Story index and preview]
E --> H[Component manifests]
F --> I[Test and accessibility results]
References: code/…/README.md• L11-30 code/…/server.json• L28-45 code/…/preset.ts• L58-97 code/…/preset.ts• L148-211 code/…/mcp-handler.ts• L25-73 code/…/mcp-handler.ts• L114-172 code/…/mcp-handler.ts• L174-251 code/…/mcp-handler.test.ts• L203-371 code/…/mcp-handler.test.ts• L585-715 code/…/package.json• L38-57
Agent toolsets
The MCP addon groups capabilities so a project can enable or disable broad classes of agent work. The dev group supports story previews, changed-story discovery, component-to-story lookup, story guidance, and review creation. The docs group exposes component and story documentation. The test group exposes the Vitest run action as test-run.
An MCP request may further narrow the active groups with the X-MCP-Toolsets header. When the header is present, only named groups are enabled for that request. The server uses the same availability checks for tool registration, server instructions, and its status page, so a client does not receive a tool that the Storybook cannot answer. The registry also keeps a missing backing toolset from removing unrelated tools; it logs the mismatch and omits only the affected tool.
Tool descriptions are part of the agent interface. They use plain text and stay within the limit used by common MCP clients. The MCP server also converts every registered input and output contract to JSON Schema when it lists tools.
References: code/…/types.ts• L14-34 code/…/mcp-handler.ts• L25-50 code/…/mcp-handler.ts• L223-251 code/…/mcp-handler.test.ts• L577-715 code/…/tool-descriptions.test.ts• L53-113 code/…/tool-registry.ts• L52-68 code/…/tool-registry.ts• L150-249 code/…/preset.ts• L180-193
Storybook data access
The docs tools let an agent first list available components and docs entries, then fetch a selected component or story. This order gives the agent valid IDs and real story examples before it writes code or answers questions about props. In a composed Storybook, the same tools can group data from local and remote sources and use a source ID to scope a follow-up request.
The docs toolset is built for the request that uses it. Handler-level sources provide a default composition, while request context can supply a different source set for that request. Its schemas and access rules then reflect the current sources. In a single-Storybook request, the tools use the local manifest provider. This keeps tool metadata and returned data aligned when a client changes between local and composed data.
At dev-server start, composition checks each remote source for a valid component manifest. Sources without a usable manifest are skipped. A non-JSON app-shell response counts as a missing manifest, while valid JSON with an unsupported manifest shape is reported as an invalid manifest. Public sources can be read directly, while private sources use the MCP client's bearer token and the OAuth metadata advertised by the remote Storybook. Remote manifests are cached for later requests and refreshed in the background, which reduces repeated network work without keeping stale data forever. A new bearer token clears the remote cache.
The tools return a useful agent-facing error when a manifest cannot be found, parsed, or queried. The caller can then discover valid entries again instead of treating a transport failure as missing product data. When a tool publishes structured output, the hosted MCP layer validates that output before returning it, while preserving designed agent-facing errors as tool results.
References: code/…/index.ts• L15-27 code/…/register.ts• L49-106 code/…/register.ts• L123-201 code/…/register.ts• L212-388 code/…/types.ts• L15-40 code/…/index.test.ts• L168-270 code/…/index.test.ts• L272-387 code/…/composition-auth.ts• L81-127 code/…/composition-auth.ts• L162-243 code/…/composition-auth.ts• L249-327 code/…/composition-auth.ts• L355-407 code/…/resolve-composition-sources.test.ts• L24-185
MCP package boundary
@storybook/mcp is the reusable MCP library for documentation. It is not a CLI or a standalone process. It creates a fetch-compatible HTTP handler, registers docs-list, docs-show, and docs-show-story, and lets an embedder provide manifest access for a local or composed Storybook. A self-hosted user supplies the manifest source and owns the MCP transport. The package expects a components manifest and can also use a docs manifest.
@storybook/addon-mcp uses the same documentation toolset inside the dev server and adds Storybook-specific development and testing tools. The shared package builds documentation access per request, so hosted and composed surfaces can use the same contract without sharing stale source state. Per-request sources take precedence over handler defaults when an embedder changes the Storybook context.
This split lets hosted Storybooks and other integrations reuse the documentation contract without taking on the full dev-server addon. It also keeps tool names, schemas, descriptions, and rendered results aligned across MCP surfaces.
References: code/…/README.md• L7-26 code/…/README.md• L58-101 code/…/README.md• L123-191 code/…/README.md• L293-336 code/…/package.json• L1-8 code/…/package.json• L25-44 code/…/index.ts• L89-142 code/…/index.test.ts• L38-166 code/…/index.test.ts• L193-270 code/…/index.test.ts• L272-387 code/…/register.ts• L1-8 code/…/register.ts• L74-106 code/…/package.json• L38-42 code/…/tool-registry.ts• L70-103 code/…/tool-registry.ts• L125-148
Automated workflow
An agent uses the addons as one loop rather than as separate features. It discovers grounded Storybook data, makes or updates stories, checks the affected stories, and publishes a review when visual inspection is needed.
Agent validation flow
The normal flow is:
- List documentation to find the component or docs entry and, when needed, its story IDs.
- Fetch the selected component or story documentation to learn real props and usage.
- Use the development tools to preview stories or find stories related to changed components.
- Run focused story tests with
test-runby using story IDs, files, or changed-story selection while editing. Include accessibility checks unless only component results are needed. - Run the full story set for final verification when the change needs project-wide coverage.
- Create a review for visual changes so a person can inspect the affected stories.
The workflow is grounded by tool output at each step. In particular, agents should pass story IDs returned by docs or story-discovery tools instead of deriving IDs from file names. Test output gives both a verdict and the detail needed to repair the story.
References: code/…/definition.ts• L148-188 code/…/definition.ts• L320-367 code/…/tool-registry.ts• L150-184 code/…/index.test.ts• L100-147 test-storybooks/…/mcp-endpoint.e2e.test.ts• L884-1012
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the
test.runinput and result contract aligned with the MCPtest-runregistration, its generated descriptions, and its JSON Schema conversion. - Keep story selector resolution aligned with the story index and changed-story discovery so focused runs do not test a different set than the caller requested. The result filter must also exclude same-named cases from unrelated stories.
- Keep test availability checks aligned with addon registration and the backing toolset. An installed but disabled Vitest addon must remove
test-runwithout breaking the other MCP tools, and a missing toolset must drop only its tool. - Keep the Vitest config merge aligned with Vitest project rules. Existing user projects and run-wide options must remain valid after Storybook setup.
- Keep initial globals aligned across Vitest project configuration, Storybook composition, and story test context so config values reach the stories that depend on them.
- Keep runner event queues, story-index refresh, fatal-error recovery, and process shutdown aligned across the Storybook server and Vitest child process.
- Keep result verdicts, accessibility counts, readable reports, and telemetry summaries aligned when a new run status or failure source is added.
- Keep manifest shapes, source-selection rules, per-request schema selection, cache invalidation, and OAuth responses aligned between composed Storybooks and the shared docs toolset.
- Keep composed-source probing aligned with the manifest contract. A missing or non-JSON app-shell response must not be treated as a version mismatch, while invalid manifest JSON must remain distinguishable.
- Keep toolset option and request-header behavior aligned with the endpoint status page and server instructions so advertised capabilities match callable capabilities.
- Keep the MCP endpoint pathname and base URL aligned when building OAuth resource metadata and unauthorized responses.
- Keep tool descriptions plain and within client limits. Keep every registered schema convertible to the JSON Schema format used by
tools/list. - Keep the reusable package's handler contract aligned with its manifest-provider and per-request context rules when changing hosted or composed integrations.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Vitest is installed but not enabled in Storybook | MCP serves its other tools but does not expose test-run | Match test availability to the addon registration gate |
| A backing core toolset is not registered | The affected MCP tool is omitted and the server logs the wiring error | Keep each availability gate aligned with the toolset registration condition |
| A project uses a Webpack-based builder for Vitest runs | The test request returns a clear builder error instead of waiting for a result | Use a Vite-based Storybook builder for the Vitest test path |
| A focused request contains an unknown or partly unknown story selector | No partial verdict is returned; the result reports the missing selector | Discover IDs from docs or story tools and pass valid selectors |
| File, changed-story, and story filters have no common match | No stories run and the result explains the empty selection | Treat filters as an intersection and check the selection details |
| A focused run produces same-named tests from unrelated files | Unrelated results can corrupt the focused status and total | Filter results by the requested story and its child entries |
| An enabled accessibility check reports an error-level result | The completed run is marked as failed and includes the report | Treat error-level accessibility results as failures while allowing warnings to pass |
| A changed-story request finds no affected stories | The run passes with no tests, which can hide an incorrect change scope | Use explicit story or file selection when a test must run |
| The Vitest channel does not return a terminal response | The queued tool call fails after its timeout and the next call must still be able to run | Keep request IDs, timeout cleanup, and queue release aligned |
| A docs manifest is missing or cannot be read | Documentation calls return an agent-readable error and no false component data | Enable the supported manifest feature and use the correct source |
| A composed source returns an app shell or has no valid component manifest at boot | The source is omitted from the MCP source list | Enable the component manifest feature on the composed Storybook and restart after it becomes reachable |
| A composed source returns valid JSON in an unsupported manifest shape | The source is skipped as a manifest-version or schema mismatch | Keep the composed Storybooks on a compatible manifest format |
| A private composed source rejects the bearer token | The MCP request returns 401 with OAuth resource guidance | Complete the advertised OAuth flow and retry with a valid token |
| A request has a disallowed browser origin or a non-JSON body | The MCP endpoint rejects it before tool execution | Use an allowed Storybook origin and send application/json |
| Several agents request tests at the same time | Runs execute one at a time, so their results do not mix | The test toolset serializes calls through its run queue |
| A tool description uses unsupported emphasis or exceeds the client limit | The agent receives a reduced or less useful description | Keep descriptions plain and within the tested character limit |
| A registered input or output schema cannot convert to JSON Schema | tools/list can fail for every tool | Test every registered schema with the MCP adapter |
| The Vitest child process fails before it becomes ready | Storybook reports a fatal startup error and does not restart in a loop | Fix the Vitest or Storybook setup before retrying |
| A Vitest config has unsupported bindings or no writable config object | The setup update makes no edit rather than changing the wrong config | Use a writable default config and avoid conflicting template bindings |
| A story depends on an initial global that its Vitest project does not provide | The story's test check fails or has no meaningful value outside that project | Keep the configured global and the story's project scope aligned |
| A remote manifest source stops responding during OAuth discovery | The source is skipped and the other sources remain available | Make the source reachable before Storybook starts; restart after recovery |
Key files
| File | Why to read it |
|---|---|
| code/…/index.ts | Shows how Storybook stories become a Vitest project and how test configuration follows Storybook configuration. |
| code/…/updateVitestFile.ts | Shows how Storybook test setup joins an existing Vitest config without dropping user projects or run-wide settings. |
| code/…/InitialGlobals.stories.tsx | Demonstrates that a Vitest project can provide an initial global to a composed Storybook story and verify it in the story test. |
| code/…/definition.ts | Defines the public automated test contract, selection modes, result states, and failure verdict. |
| code/…/run.ts | Explains focused story selection, changed-story selection, timeouts, and the mapping from a request to a test result. |
| code/…/format.ts | Shows how structured test and accessibility results become readable agent output. |
| code/…/test-manager.ts | Shows how Vitest results become Storybook status and report data, including focused-run filtering. |
| code/…/boot-test-runner.ts | Shows how the Storybook server coordinates the Vitest child process, story index, events, and recovery. |
| code/…/TestProviderRender.tsx | Shows how Storybook presents run controls and component, accessibility, and coverage status. |
| code/…/README.md | Defines the ready-to-use dev-server endpoint and its configurable pathname. |
| code/…/server.json | Describes the addon as a streamable HTTP MCP server for Storybook development. |
| code/…/preset.ts | Shows how the MCP endpoint, request gates, composition access, toolset options, and capability status connect to Storybook. |
| code/…/mcp-handler.ts | Shows how MCP requests are initialized, converted, scoped to toolsets, and returned to the Storybook server. |
| code/…/mcp-handler.test.ts | Demonstrates endpoint conversion, initialization, toolset selection, and conditional tool registration. |
| code/…/composition-auth.ts | Shows how composed Storybook manifests, bearer tokens, OAuth metadata, and remote source caching support agent data access. |
| code/…/resolve-composition-sources.test.ts | Demonstrates source probing, source order, manifest classification, and private-source handling. |
| code/…/tool-registry.ts | Shows how shared toolsets become the dev, docs, and test MCP tools and how unavailable tools are contained. |
| code/…/tool-descriptions.test.ts | Defines the client-facing description and JSON Schema guarantees for registered tools. |
| code/…/README.md | Explains how a hosted or self-managed MCP server can reuse Storybook documentation tools. |
| code/…/index.ts | Shows the reusable MCP handler and documentation tool exports. |
| code/…/index.test.ts | Demonstrates local and composed documentation access, source precedence, and tool behavior. |
| code/…/register.ts | Shows how per-request component and story manifest access becomes documentation tools for MCP clients. |
| test-storybooks/…/mcp-endpoint.e2e.test.ts | Demonstrates the end-to-end agent workflow across discovery, documentation, preview, and test calls. |