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-and-agent-addons

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:

  1. List documentation to find the component or docs entry and, when needed, its story IDs.
  2. Fetch the selected component or story documentation to learn real props and usage.
  3. Use the development tools to preview stories or find stories related to changed components.
  4. Run focused story tests with test-run by using story IDs, files, or changed-story selection while editing. Include accessibility checks unless only component results are needed.
  5. Run the full story set for final verification when the change needs project-wide coverage.
  6. 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.run input and result contract aligned with the MCP test-run registration, 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-run without 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

TriggerConsequenceGuard
Vitest is installed but not enabled in StorybookMCP serves its other tools but does not expose test-runMatch test availability to the addon registration gate
A backing core toolset is not registeredThe affected MCP tool is omitted and the server logs the wiring errorKeep each availability gate aligned with the toolset registration condition
A project uses a Webpack-based builder for Vitest runsThe test request returns a clear builder error instead of waiting for a resultUse a Vite-based Storybook builder for the Vitest test path
A focused request contains an unknown or partly unknown story selectorNo partial verdict is returned; the result reports the missing selectorDiscover IDs from docs or story tools and pass valid selectors
File, changed-story, and story filters have no common matchNo stories run and the result explains the empty selectionTreat filters as an intersection and check the selection details
A focused run produces same-named tests from unrelated filesUnrelated results can corrupt the focused status and totalFilter results by the requested story and its child entries
An enabled accessibility check reports an error-level resultThe completed run is marked as failed and includes the reportTreat error-level accessibility results as failures while allowing warnings to pass
A changed-story request finds no affected storiesThe run passes with no tests, which can hide an incorrect change scopeUse explicit story or file selection when a test must run
The Vitest channel does not return a terminal responseThe queued tool call fails after its timeout and the next call must still be able to runKeep request IDs, timeout cleanup, and queue release aligned
A docs manifest is missing or cannot be readDocumentation calls return an agent-readable error and no false component dataEnable the supported manifest feature and use the correct source
A composed source returns an app shell or has no valid component manifest at bootThe source is omitted from the MCP source listEnable the component manifest feature on the composed Storybook and restart after it becomes reachable
A composed source returns valid JSON in an unsupported manifest shapeThe source is skipped as a manifest-version or schema mismatchKeep the composed Storybooks on a compatible manifest format
A private composed source rejects the bearer tokenThe MCP request returns 401 with OAuth resource guidanceComplete the advertised OAuth flow and retry with a valid token
A request has a disallowed browser origin or a non-JSON bodyThe MCP endpoint rejects it before tool executionUse an allowed Storybook origin and send application/json
Several agents request tests at the same timeRuns execute one at a time, so their results do not mixThe test toolset serializes calls through its run queue
A tool description uses unsupported emphasis or exceeds the client limitThe agent receives a reduced or less useful descriptionKeep descriptions plain and within the tested character limit
A registered input or output schema cannot convert to JSON Schematools/list can fail for every toolTest every registered schema with the MCP adapter
The Vitest child process fails before it becomes readyStorybook reports a fatal startup error and does not restart in a loopFix the Vitest or Storybook setup before retrying
A Vitest config has unsupported bindings or no writable config objectThe setup update makes no edit rather than changing the wrong configUse a writable default config and avoid conflicting template bindings
A story depends on an initial global that its Vitest project does not provideThe story's test check fails or has no meaningful value outside that projectKeep the configured global and the story's project scope aligned
A remote manifest source stops responding during OAuth discoveryThe source is skipped and the other sources remain availableMake the source reachable before Storybook starts; restart after recovery

Key files

FileWhy to read it
code/…/index.tsShows how Storybook stories become a Vitest project and how test configuration follows Storybook configuration.
code/…/updateVitestFile.tsShows how Storybook test setup joins an existing Vitest config without dropping user projects or run-wide settings.
code/…/InitialGlobals.stories.tsxDemonstrates that a Vitest project can provide an initial global to a composed Storybook story and verify it in the story test.
code/…/definition.tsDefines the public automated test contract, selection modes, result states, and failure verdict.
code/…/run.tsExplains focused story selection, changed-story selection, timeouts, and the mapping from a request to a test result.
code/…/format.tsShows how structured test and accessibility results become readable agent output.
code/…/test-manager.tsShows how Vitest results become Storybook status and report data, including focused-run filtering.
code/…/boot-test-runner.tsShows how the Storybook server coordinates the Vitest child process, story index, events, and recovery.
code/…/TestProviderRender.tsxShows how Storybook presents run controls and component, accessibility, and coverage status.
code/…/README.mdDefines the ready-to-use dev-server endpoint and its configurable pathname.
code/…/server.jsonDescribes the addon as a streamable HTTP MCP server for Storybook development.
code/…/preset.tsShows how the MCP endpoint, request gates, composition access, toolset options, and capability status connect to Storybook.
code/…/mcp-handler.tsShows how MCP requests are initialized, converted, scoped to toolsets, and returned to the Storybook server.
code/…/mcp-handler.test.tsDemonstrates endpoint conversion, initialization, toolset selection, and conditional tool registration.
code/…/composition-auth.tsShows how composed Storybook manifests, bearer tokens, OAuth metadata, and remote source caching support agent data access.
code/…/resolve-composition-sources.test.tsDemonstrates source probing, source order, manifest classification, and private-source handling.
code/…/tool-registry.tsShows how shared toolsets become the dev, docs, and test MCP tools and how unavailable tools are contained.
code/…/tool-descriptions.test.tsDefines the client-facing description and JSON Schema guarantees for registered tools.
code/…/README.mdExplains how a hosted or self-managed MCP server can reuse Storybook documentation tools.
code/…/index.tsShows the reusable MCP handler and documentation tool exports.
code/…/index.test.tsDemonstrates local and composed documentation access, source precedence, and tool behavior.
code/…/register.tsShows how per-request component and story manifest access becomes documentation tools for MCP clients.
test-storybooks/…/mcp-endpoint.e2e.test.tsDemonstrates the end-to-end agent workflow across discovery, documentation, preview, and test calls.