Repository files navigation

Storybook test runner turns all of your stories into executable tests.

• Features
• How it works
• Storybook compatibility
• Getting started
• CLI Options
• Ejecting configuration
  • Jest-playwright options
  • Jest options
• Filtering tests (experimental)
• Test reporters
• Running against a deployed Storybook
  • Index.json mode
• Running in CI
  • 1. Running against deployed Storybooks on Github Actions deployment
  • 2. Running against locally built Storybooks in CI
• Setting up code coverage
  • 1 - Instrument the code
    • Using @storybook/addon-coverage
    • Manually configuring istanbul
  • 2 - Run tests with --coverage flag
  • 3 - Merging code coverage with coverage from other tools
  • 4 - Run tests with --shard flag
• Test hooks API
  • setup
  • preRender (deprecated)
  • preVisit
  • postRender (deprecated)
  • postVisit
  • Render lifecycle
  • prepare
  • getHttpHeaders
  • tags (experimental)
  • logLevel
  • errorMessageFormatter
  • Utility functions
    • getStoryContext
    • waitForPageReady
    • StorybookTestRunner user agent
• Recipes
  • Preconfiguring viewport size
  • Accessibility testing
    • With Storybook 9
    • With Storybook 8
  • DOM snapshot (HTML)
  • Image snapshot
• Troubleshooting
  • Yarn PnP (Plug n' Play) support
  • React Native support
  • The error output in the CLI is too short
  • The test runner seems flaky and keeps timing out
  • The test runner reports "No tests found" running on a Windows CI
  • Adding the test runner to other CI environments
  • Merging test coverage results in wrong coverage
• Future work
• Contributing

• ⚡️ Zero config setup
• 💨 Smoke test all stories
• ▶️ Test stories with play functions
• 🏃 Test your stories in parallel in a headless browser
• 👷 Get feedback from error with a link directly to the story
• 🐛 Debug them visually and interactively in a live browser withaddon-interactions
• 🎭 Powered byJest andPlaywright
• 👀 Watch mode, filters, and the conveniences you'd expect
• 📔 Code coverage reports

See the announcement of Interaction Testing with Storybook in detail inthis blog post or watchthis video to see it in action.

The Storybook test runner uses Jest as a runner, and Playwright as a testing framework. Each one of your.stories files is transformed into a spec file, and each story becomes a test, which is run in a headless browser.

The test runner is simple in design – it just visits each story from a running Storybook instance and makes sure the component is not failing:

• For stories without aplay function, it verifies whether the story rendered without any errors. This is essentially a smoke test.
• For those with aplay function, it also checks for errors in theplay function and that all assertions passed. This is essentially aninteraction test.

If there are any failures, the test runner will provide an output with the error, alongside with a link to the failing story, so you can see the error yourself and debug it directly in the browser:

Use the following table to use the correct version of this package, based on the version of Storybook you're using:

1. Install the test runner:

yarnadd @storybook/test-runner-D

2. Add atest-storybook script to your package.json

{"scripts": {"test-storybook":"test-storybook"  }}

3. Optionally, followthe documentation for writing interaction tests and usingaddon-interactions to visualize the interactions with an interactive debugger in Storybook.

4. Run Storybook (the test runner runs against a running Storybook instance):

yarnstorybook

5. Run the test runner:

yarntest-storybook

yarntest-storybook--urlhttp://127.0.0.1:9009orTARGET_URL=http://127.0.0.1:9009 yarn test-storybook

Usage: test-storybook [options]

The test runner is based onJest and will accept most of theCLI options that Jest does, like--watch,--watchAll,--maxWorkers,--testTimeout, etc. It works out of the box, but if you want better control over its configuration, you can eject its configuration by runningtest-storybook --eject to create a localtest-runner-jest.config.js file in the root folder of your project. This file will be used by the test runner.

The configuration file will accept options for two runners:

The test runner usesjest-playwright and you can passtestEnvironmentOptions to further configure it.

The Storybook test runner comes with Jest installed as an internal dependency. You can pass Jest options based on the version of Jest that comes with the test runner.

If you're already using a compatible version of Jest, the test runner will use it, instead of installing a duplicate version in your node_modules folder.

Here's an example of an ejected file used to extend the tests timeout from Jest:

// ./test-runner-jest.config.jsconst{ getJestConfig}=require('@storybook/test-runner');consttestRunnerConfig=getJestConfig();/** *@type {import('@jest/types').Config.InitialOptions} */module.exports={// The default Jest configuration comes from@storybook/test-runner  ...testRunnerConfig,/** Add your own overrides below   *@see https://jestjs.io/docs/configuration   */testTimeout:20000,// default timeout is 15s};

You might want to skip certain stories in the test-runner, run tests only against a subset of stories, or exclude certain stories entirely from your tests. This is possible via thetags annotation. By default, the test-runner includes every story with the'test' tag. This tag is included by default in Storybook 8 for all stories, unless the user tells otherwise viatag negation.

This annotation can be part of a story, therefore only applying to that story, or the component meta (the default export), which applies to all stories in the file:

constmeta={component:Button,tags:['atom'],};exportdefaultmeta;// will inherit tags from project and meta to be ['dev', 'test', 'atom']exportconstPrimary={};exportconstSecondary={// will combine with project and meta tags to be ['dev', 'test', 'atom', 'design']tags:['design'],};exportconstTertiary={// will combine with project and meta tags to be ['dev', 'atom']tags:['!test'],};

For more information on how tags combine (and can be selectively removed), please see theofficial docs.

Once your stories have your own custom tags, you can filter them via thetags property in your test-runner configuration file. You can also use the CLI flags--includeTags,--excludeTags or--skipTags for the same purpose. The CLI flags will take precedence over the tags in the test-runner config, therefore overriding them.

Both--skipTags and--excludeTags will prevent a story from being tested. The difference is that skipped tests will appear as "skipped" in the cli output, whereas excluded tests will not appear at all. Skipped tests can be useful to indicate tests that are temporarily disabled.

The test runner uses default Jest reporters, but you can add additional reporters by ejecting the configuration as explained above and overriding (or merging with) thereporters property.

Additionally, if you pass--junit totest-storybook, the test runner will addjest-junit to the reporters list and generate a test report in a JUnit XML format. You can further configure the behavior ofjest-junit by either setting specificJEST_JUNIT_* environment variables or by defining ajest-junit field in your package.json with the options you want, which will be respected when generating the report. You can look at all available options here:https://github.com/jest-community/jest-junit#configuration

By default, the test runner assumes that you're running it against a locally served Storybook on port 6006.If you want to define a target url so it runs against deployed Storybooks, you can do so by passing theTARGET_URL environment variable:

TARGET_URL=https://the-storybook-url-here.com yarn test-storybook

Or by using the--url flag:

yarn test-storybook --url https://the-storybook-url-here.com

By default, the test runner transforms your story files into tests. It also supports a secondary "index.json mode" which runs directly against your Storybook's index data, which dependending on your Storybook version is located in astories.json orindex.json, a static index of all the stories.

This is particularly useful for running against a deployed storybook becauseindex.json is guaranteed to be in sync with the Storybook you are testing. In the default, story file-based mode, your local story files may be out of sync – or you might not even have access to the source code.

Furthermore, it is not possible to run the test-runner directly against.mdx stories or custom CSF dialects like when writing Svelte native stories withaddon-svelte-csf. In these casesindex.json mode must be used.

https://your-storybook-url-here.com/index.json

On Storybook 6.4 and 6.5, to run inindex.json mode, first make sure your Storybook has a file calledstories.json that has"v": 3, available at:

https://your-storybook-url-here.com/stories.json

If your Storybook does not have astories.json file, you can generate one, provided:

• You are running Storybook 6.4 or above
• You are not usingstoriesOf stories

To enablestories.json in your Storybook, set thebuildStoriesJson feature flag in.storybook/main.js:

// .storybook/main.tsconstconfig={// ... rest of the configfeatures:{buildStoriesJson:true},};exportdefaultconfig;

Once you have a validstories.json file, your Storybook will be compatible with the "index.json mode".

By default, the test runner will detect whether your Storybook URL is local or remote, and if it is remote, it will run in "index.json mode" automatically. To disable it, you can pass the--no-index-json flag:

yarn test-storybook --no-index-json

If you are running tests against a local Storybook but for some reason want to run in "index.json mode", you can pass the--index-json flag:

yarn test-storybook --index-json

If you want to add the test-runner to CI, there are a couple of ways to do so:

On Github actions, once services like Vercel, Netlify and others do deployment runs, they follow a pattern of emitting adeployment_status event containing the newly generated URL underdeployment_status.target_url. You can use that URL and set it asTARGET_URL for the test-runner.

Here's an example of an action to run tests based on that:

name:Storybook Testson:deployment_statusjobs:test:timeout-minutes:60runs-on:ubuntu-latestif:github.event.deployment_status.state == 'success'steps:      -uses:actions/checkout@v4      -uses:actions/setup-node@v4with:node-version:'18.x'      -name:Install dependenciesrun:yarn      -name:Run Storybook testsrun:yarn test-storybookenv:TARGET_URL:'${{ github.event.deployment_status.target_url }}'

In order to build and run tests against your Storybook in CI, you might need to use a combination of commands involving theconcurrently,http-server andwait-on libraries. Here's a recipe that does the following: Storybook is built and served locally, and once it is ready, the test runner will run against it.

{"test-storybook:ci":"concurrently -k -s first -n\"SB,TEST\" -c\"magenta,blue\"\"yarn build-storybook --quiet && npx http-server storybook-static --port 6006 --silent\"\"wait-on tcp:6006 && yarn test-storybook\""}

And then you can essentially runtest-storybook:ci in your CI:

name:Storybook Testson:pushjobs:test:timeout-minutes:60runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4      -uses:actions/setup-node@v4with:node-version:'18.x'      -name:Install dependenciesrun:yarn      -name:Run Storybook testsrun:yarn test-storybook:ci

The test runner supports code coverage with the--coverage flag orSTORYBOOK_COLLECT_COVERAGE environment variable. The pre-requisite is that your components are instrumented usingistanbul.

Instrumenting the code is an important step, which allows lines of code to be tracked by Storybook. This is normally achieved by using instrumentation libraries such as theIstanbul Babel plugin, or its Vite counterpart. In Storybook, you can set up instrumentation in two different ways:

For select frameworks (React, Preact, HTML, Web components, Svelte and Vue) you can use the@storybook/addon-coverage addon, which will automatically configure the plugin for you.

Install@storybook/addon-coverage:

yarn add -D @storybook/addon-coverage

And register it in your.storybook/main.js file:

// .storybook/main.tsconstconfig={// ...rest of your code hereaddons:['@storybook/addon-coverage'],};exportdefaultconfig;

The addon has default options that might suffice for your project, and it accepts anoptions object for project-specific configuration.

If your framework does not use Babel or Vite, such as Angular, you will have to manually configure whatever flavor ofIstanbul (Webpack loader, etc.) your project might require. Also, if your project uses Vue or Svelte, you will need to add one extra configuration for nyc.

You can find recipes inthis repository that include many different configurations and steps on how to set up coverage in each of them.

After setting up instrumentation, run Storybook then run the test-runner with--coverage:

yarn test-storybook --coverage

The test runner will report the results in the CLI and generate acoverage/storybook/coverage-storybook.json file which can be used bynyc.

If you want to generate coverage reports withdifferent reporters, you can usenyc and point it to the folder which contains the Storybook coverage file.nyc is a dependency of the test runner so you will already have it in your project.

Here's an example generating anlcov report:

npx nyc report --reporter=lcov -t coverage/storybook --report-dir coverage/storybook

This will generate a more detailed, interactive coverage summary that you can access atcoverage/storybook/index.html file which can be explored and will show the coverage in detail:

Thenyc command will respectnyc configuration files if you have them in your project.

If you want certain parts of your code to be deliberately ignored, you can use istanbulparsing hints.

The test runner reports coverage related to thecoverage/storybook/coverage-storybook.json file. This is by design, showing you the coverage which is tested while running Storybook.

Now, you might have other tests (e.g. unit tests) which arenot covered in Storybook but are covered when running tests with Jest, which you might also generate coverage files from, for instance. In such cases, if you are using tools likeCodecov to automate reporting, the coverage files will be detected automatically and if there are multiple files in the coverage folder, they will be merged automatically.

Alternatively, in case you want to merge coverages from other tools, you should:

1 - move or copy thecoverage/storybook/coverage-storybook.json intocoverage/coverage-storybook.json;2 - runnyc report against thecoverage folder.

Here's an example on how to achieve that:

{"scripts": {"test:coverage":"jest --coverage","test-storybook:coverage":"test-storybook --coverage","coverage-report":"cp coverage/storybook/coverage-storybook.json coverage/coverage-storybook.json && nyc report --reporter=html -t coverage --report-dir coverage"  }}

The test-runner collects all coverage in one filecoverage/storybook/coverage-storybook.json. To split the coverage file you should rename it using theshard-index. To report the coverage you should merge the coverage files with the nyc merge command.

Github CI example:

test:name:Running Test-storybook (${{ matrix.shard }})strategy:matrix:shard:[1, 2, 3, 4]steps:    -name:Testing storybookrun:yarn test-storybook --coverage --shard=${{ matrix.shard }}/${{ strategy.job-total }}    -name:Renaming coverage filerun:mv coverage/storybook/coverage-storybook.json coverage/storybook/coverage-storybook-${matrix.shard}.jsonreport-coverage:name:Reporting storybook coveragesteps:    -name:Merging coveragerun:yarn nyc merge coverage/storybook merged-output/merged-coverage.json    -name:Report coveragerun:yarn nyc report --reporter=text -t merged-output --report-dir merged-output

Circle CI example:

test:parallelism:4steps:    -run:command:yarn test-storybook --coverage --shard=$(expr $CIRCLE_NODE_INDEX + 1)/$CIRCLE_NODE_TOTALcommand:mv coverage/storybook/coverage-storybook.json coverage/storybook/coverage-storybook-${CIRCLE_NODE_INDEX + 1}.jsonreport-coverage:steps:    -run:command:yarn nyc merge coverage/storybook merged-output/merged-coverage.jsoncommand:yarn nyc report --reporter=text -t merged-output --report-dir merged-output

Gitlab CI example:

test:parallel:4script:    -yarn test-storybook --coverage --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL    -mv coverage/storybook/coverage-storybook.json coverage/storybook/coverage-storybook-${CI_NODE_INDEX}.jsonreport-coverage:script:    -yarn nyc merge coverage/storybook merged-output/merged-coverage.json    -yarn nyc report --reporter=text -t merged-output --report-dir merged-output

The test runner renders a story and executes itsplay function if one exists. However, there are certain behaviors that are not possible to achieve via the play function, which executes in the browser. For example, if you want the test runner to take visual snapshots for you, this is something that is possible via Playwright/Jest, but must be executed in Node.

To enable use cases like visual or DOM snapshots, the test runner exports test hooks that can be overridden globally. These hooks give you access to the test lifecycle before and after the story is rendered.

There are three hooks:setup,preVisit, andpostVisit.setup executes once before all the tests run.preVisit andpostVisit execute within a test before and after a story is rendered.

All three functions can be set up in the configuration file.storybook/test-runner.js which can optionally export any of these functions.

Async function that executes once before all the tests run. Useful for setting node-related configuration, such as extending Jest globalexpect for accessibility matchers.

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={asyncsetup(){// execute whatever you like, in Node, once before all tests run},};exportdefaultconfig;

Async function that receives aPlaywright Page and a context object with the current story'sid,title, andname.Executes within a test before the story is rendered. Useful for configuring the Page before the story renders, such as setting up the viewport size.

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={asyncpreVisit(page,context){// execute whatever you like, before the story renders},};exportdefaultconfig;

Async function that receives aPlaywright Page and a context object with the current story'sid,title, andname.Executes within a test after a story is rendered. Useful for asserting things after the story is rendered, such as DOM and image snapshotting.

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={asyncpostVisit(page,context){// execute whatever you like, after the story renders},};exportdefaultconfig;

To visualize the test lifecycle with these hooks, consider a simplified version of the test code automatically generated for each story in your Storybook:

// executed once, before the testsawaitsetup();it('button--basic',async()=>{// filled in with data for the current storyconstcontext={id:'button--basic',title:'Button',name:'Basic'};// playwright page https://playwright.dev/docs/pagesawaitpage.goto(STORYBOOK_URL);// pre-visit hookif(preVisit)awaitpreVisit(page,context);// render the story and watch its play function (if applicable)awaitpage.execute('render',context);// post-visit hookif(postVisit)awaitpostVisit(page,context);});

These hooks are very useful for a variety of use cases, which are described in therecipes section further below.

Apart from these hooks, there are additional properties you can set in.storybook/test-runner.js:

The test-runner has a defaultprepare function which gets the browser in the right environment before testing the stories. You can override this behavior, in case you might want to hack the behavior of the browser. For example, you might want to set a cookie, or add query parameters to the visiting URL, or do some authentication before reaching the Storybook URL. You can do that by overriding theprepare function.

Theprepare function receives an object containing:

• browserContext: aPlaywright Browser Context instance
• page: aPlaywright Page instance.
• testRunnerConfig: the test runner configuration object, coming from the.storybook/test-runner.js.

For reference, please use thedefaultprepare function as a starting point.

The test-runner makes a fewfetch calls to check the status of a Storybook instance, and to get the index of the Storybook's stories. Additionally, it visits a page using Playwright. In all of these scenarios, it's possible, depending on where your Storybook is hosted, that you might need to set some HTTP headers. For example, if your Storybook is hosted behind a basic authentication, you might need to set theAuthorization header. You can do so by passing agetHttpHeaders function to your test-runner config. That function receives theurl of the fetch calls and page visits, and should return an object with the headers to be set.

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={getHttpHeaders:async(url)=>{consttoken=url.includes('prod') ?'XYZ' :'ABC';return{Authorization:`Bearer${token}`,};},};exportdefaultconfig;

Thetags property contains three options:include | exclude | skip, each accepting an array of strings:

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={tags:{include:[],// string array, e.g. ['test', 'design'] - by default, the value will be ['test']exclude:[],// string array, e.g. ['design', 'docs-only']skip:[],// string array, e.g. ['design']},};exportdefaultconfig;

tags are used for filtering your tests. Learn morehere.

When tests fail and there were browser logs during the rendering of a story, the test-runner provides the logs alongside the error message. ThelogLevel property defines what kind of logs should be displayed:

• info (default): Shows console logs, warnings, and errors.
• warn: Shows only warnings and errors.
• error: Displays only error messages.
• verbose: Includes all console outputs, including debug information and stack traces.
• none: Suppresses all log output.

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={logLevel:'verbose',};exportdefaultconfig;

TheerrorMessageFormatter property defines a function that will pre-format the error messages before they get reported in the CLI:

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={errorMessageFormatter:(message)=>{// manipulate the error message as you likereturnmessage;},};exportdefaultconfig;

For more specific use cases, the test runner provides utility functions that could be useful to you.

While running tests using the hooks, you might want to get information from a story, such as the parameters passed to it, or its args. The test runner now provides agetStoryContext utility function that fetches the story context for the current story:

Suppose your story looks like this:

// ./Button.stories.tsexportconstPrimary={parameters:{theme:'dark',},};

You can access its context in a test hook like so:

// .storybook/test-runner.tsimport{TestRunnerConfig,getStoryContext}from'@storybook/test-runner';constconfig:TestRunnerConfig={asyncpostVisit(page,context){// Get entire context of a story, including parameters, args, argTypes, etc.conststoryContext=awaitgetStoryContext(page,context);if(storyContext.parameters.theme==='dark'){// do something}else{// do something else}},};exportdefaultconfig;

It's useful for skipping or enhancing use cases likeimage snapshot testing,accessibility testing and more.

ThewaitForPageReady utility is useful when you're executingimage snapshot testing with the test-runner. It encapsulates a few assertions to make sure the browser has finished downloading assets.

// .storybook/test-runner.tsimport{TestRunnerConfig,waitForPageReady}from'@storybook/test-runner';constconfig:TestRunnerConfig={asyncpostVisit(page,context){// use the test-runner utility to wait for fonts to load, etc.awaitwaitForPageReady(page);// by now, we know that the page is fully loaded},};exportdefaultconfig;

The test-runner adds aStorybookTestRunner entry to the browser's user agent. You can use it to determine if a story is rendering in the context of the test runner. This might be useful if you want to disable certain features in your stories when running in the test runner, though it's likely an edge case.

// At the render level, useful for dynamically rendering something based on the test-runnerexportconstMyStory={render:()=>{constisTestRunner=window.navigator.userAgent.match(/StorybookTestRunner/);return(<div><p>Isthisstoryrunninginthetestrunner?</p><p>{isTestRunner ?'Yes' :'No'}</p></div>);},};

Given that this check is happening in the browser, it is only applicable in the following scenarios:

• inside of a render/template function of a story
• inside of a play function
• inside of preview.js
• inside any other code that is executed in the browser

Below you will find recipes that use both the hooks and the utility functions to achieve different things with the test-runner.

You can usePlaywright's Page viewport utility to programatically change the viewport size of your test. If you use@storybook/addon-viewports, you can reuse its parameters and make sure that the tests match in configuration.

// .storybook/test-runner.tsimport{TestRunnerConfig,getStoryContext}from'@storybook/test-runner';import{MINIMAL_VIEWPORTS}from'@storybook/addon-viewport';constDEFAULT_VIEWPORT_SIZE={width:1280,height:720};constconfig:TestRunnerConfig={asyncpreVisit(page,story){constcontext=awaitgetStoryContext(page,story);constviewportName=context.parameters?.viewport?.defaultViewport;constviewportParameter=MINIMAL_VIEWPORTS[viewportName];if(viewportParameter){constviewportSize=Object.entries(viewportParameter.styles).reduce((acc,[screen,size])=>({          ...acc,// make sure your viewport config in Storybook only uses numbers, not percentages[screen]:parseInt(size),}),{});page.setViewportSize(viewportSize);}else{page.setViewportSize(DEFAULT_VIEWPORT_SIZE);}},};exportdefaultconfig;

In Storybook 9, the accessibility addon has been enhanced with automated reporting capabilities and the Test-runner has out of the box support for it. If you have@storybook/addon-a11y installed, as long as you enable them via parameters, you will get a11y checks for every story:

// .storybook/preview.tsconstpreview={parameters:{a11y:{// 'error' will cause a11y violations to fail teststest:'error',// or 'todo' or 'off'},},};exportdefaultpreview;

If you had a11y tests set up previously for Storybook 8 (with the recipe below), you can uninstallaxe-playwright and remove all the code from the test-runner hooks, as they are not necessary anymore.

You can installaxe-playwright and use it in tandem with the test-runner to test the accessibility of your components.If you use@storybook/addon-a11y, you can reuse its parameters and make sure that the tests match in configuration, both in the accessibility addon panel and the test-runner.

// .storybook/test-runner.tsimport{TestRunnerConfig,getStoryContext}from'@storybook/test-runner';import{injectAxe,checkA11y,configureAxe}from'axe-playwright';constconfig:TestRunnerConfig={asyncpreVisit(page,context){// Inject Axe utilities in the page before the story rendersawaitinjectAxe(page);},asyncpostVisit(page,context){// Get entire context of a story, including parameters, args, argTypes, etc.conststoryContext=awaitgetStoryContext(page,context);// Do not test a11y for stories that disable a11yif(storyContext.parameters?.a11y?.disable){return;}// Apply story-level a11y rulesawaitconfigureAxe(page,{rules:storyContext.parameters?.a11y?.config?.rules,});// in Storybook 6.x, the selector is #rootawaitcheckA11y(page,'#storybook-root',{detailedReport:true,detailedReportOptions:{html:true,},// pass axe options defined in@storybook/addon-a11yaxeOptions:storyContext.parameters?.a11y?.options,});},};exportdefaultconfig;

You can usePlaywright's built in APIs for DOM snapshot testing:

// .storybook/test-runner.tsimporttype{TestRunnerConfig}from'@storybook/test-runner';constconfig:TestRunnerConfig={asyncpostVisit(page,context){// the #storybook-root element wraps the story. In Storybook 6.x, the selector is #rootconstelementHandler=awaitpage.$('#storybook-root');constinnerHTML=awaitelementHandler.innerHTML();expect(innerHTML).toMatchSnapshot();},};exportdefaultconfig;

When running with--stories-json, tests get generated in a temporary folder and snapshots get stored alongside. You will need to--eject and configure a customsnapshotResolver to store them elsewhere, e.g. in your working directory:

// ./test-runner-jest.config.jsconst{ getJestConfig}=require('@storybook/test-runner');consttestRunnerConfig=getJestConfig();/** *@type {import('@jest/types').Config.InitialOptions} */module.exports={// The default Jest configuration comes from@storybook/test-runner  ...testRunnerConfig,snapshotResolver:'./snapshot-resolver.js',};

// ./snapshot-resolver.jsconstpath=require('path');// 👉 process.env.TEST_ROOT will only be available in --index-json or --stories-json mode.// if you run this code without these flags, you will have to override it the test root, else it will break.// e.g. process.env.TEST_ROOT = process.cwd()module.exports={resolveSnapshotPath:(testPath,snapshotExtension)=>path.join(process.cwd(),'__snapshots__',path.basename(testPath)+snapshotExtension),resolveTestPath:(snapshotFilePath,snapshotExtension)=>path.join(process.env.TEST_ROOT,path.basename(snapshotFilePath,snapshotExtension)),testPathForConsistencyCheck:path.join(process.env.TEST_ROOT,'example.test.js'),};

Here's a slightly different recipe for image snapshot testing:

// .storybook/test-runner.tsimport{TestRunnerConfig,waitForPageReady}from'@storybook/test-runner';import{toMatchImageSnapshot}from'jest-image-snapshot';constcustomSnapshotsDir=`${process.cwd()}/__snapshots__`;constconfig:TestRunnerConfig={setup(){expect.extend({ toMatchImageSnapshot});},asyncpostVisit(page,context){// use the test-runner utility to wait for fonts to load, etc.awaitwaitForPageReady(page);// If you want to take screenshot of multiple browsers, use// page.context().browser().browserType().name() to get the browser name to prefix the file nameconstimage=awaitpage.screenshot();expect(image).toMatchImageSnapshot({      customSnapshotsDir,customSnapshotIdentifier:context.id,});},};exportdefaultconfig;

The Storybook test-runner relies on a library calledjest-playwright-preset, of which does not seem to support PnP. As a result, the test-runner won't work out of the box with PnP, and you might have the following error:

PlaywrightError: jest-playwright-preset: Cannot find playwright package to use chromium

If that is the case, there are two potential solutions:

1. Installplaywright as a direct dependency. You might need to runyarn playwright install after that, so you install Playwright's browser binaries.
2. Switch your package manager's linker mode tonode-modules.

The test-runner is web based and therefore won't work with@storybook/react-native directly. However, if you use theReact Native Web Storybook Addon, you can run the test-runner against the web-based Storybook generated with that addon. In that case, things would work the same way.

By default, the test runner truncates error outputs at 1000 characters, and you can check the full output directly in Storybook, in the browser. If you do want to change that limit, however, you can do so by setting theDEBUG_PRINT_LIMIT environment variable to a number of your choosing, for example,DEBUG_PRINT_LIMIT=5000 yarn test-storybook.

If your tests are timing out withTimeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout, it might be that playwright couldn't handle to test the amount of stories you have in your project. Maybe you have a large amount of stories or your CI has a really low RAM configuration.

In either way, to fix it you should limit the amount of workers that run in parallel by passing the--maxWorkers option to your command:

{"test-storybook:ci":"concurrently -k -s first -n\"SB,TEST\" -c\"magenta,blue\"\"yarn build-storybook --quiet && npx http-server storybook-static --port 6006 --silent\"\"wait-on tcp:6006 && yarn test-storybook --maxWorkers=2\""}

Another option is trying to increase the test timeout by passing the--testTimeout option to your command (adding--testTimeout=60000 will increase test timeouts to 1 minute):

"test-storybook:ci":"concurrently -k -s first -n\"SB,TEST\" -c\"magenta,blue\"\"yarn build-storybook --quiet && npx http-server storybook-static --port 6006 --silent\"\"wait-on tcp:6006 && yarn test-storybook --maxWorkers=2 --testTimeout=60000\""

There is currently abug in Jest which means tests cannot be on a separate drive than the project. To work around this you will need to set theTEMP environment variable to a temporary folder on the same drive as your project. Here's what that would look like on GitHub Actions:

env:# Workaround for https://github.com/facebook/jest/issues/8536TEMP:${{ runner.temp }}

As the test runner is based on playwright, depending on your CI setup you might need to use specific docker images or other configuration. In that case, you can refer to thePlaywright CI docs for more information.

After merging test coverage reports coming from the test runner with reports from other tools (e.g. Jest), if the end result isnot what you expected. Here's why:

The test runner usesbabel as coverage provider, which behaves in a certain way when evaluating code coverage. If your other reports happen to use a different coverage provider thanbabel, such asv8, they will evaluate the coverage differently. Once merged, the results will likely be wrong.

Example: inv8, import and export lines are counted as coverable pieces of code, however inbabel, they are not. This impacts the percentage of coverage calculation.

While the test runner does not providev8 as an option for coverage provider, it is recommended that you set your application's Jest config to usecoverageProvider: 'babel' if you can, so that the reports line up as expected and get merged correctly.

For more context,here's some explanation whyv8 is not a 1:1 replacement for Babel/Istanbul coverage.

Future plans involve adding support for the following features:

• 📄 Run addon reports
• ⚙️ Spawning Storybook via the test runner in a single command

We welcome contributions to the test runner! Please see ourContributing Guide for details on how to get started, our development workflow, and release process.