Test runner
The test runner has been superseded by the Vitest addon, which offers the same functionality, powered by the faster and more modern Vitest browser mode. It also enables the full Storybook Test experience, allowing you to run interaction, accessibility, and visual tests from your Storybook app.
If you are using a Vite-powered Storybook framework, we recommend using the Vitest addon instead of the test runner.
Storybook test runner turns all of your stories into executable tests. It is powered by Jest and Playwright.
- For those without a play function: it verifies whether the story renders without any errors.
- For those with a play function: it also checks for errors in the play function and that all assertions passed.
These tests run in a live browser and can be executed via the command line or your CI server.
Setup
The test-runner is a standalone, framework-agnostic utility that runs parallel to your Storybook. You will need to take some additional steps to set it up properly. Detailed below is our recommendation to configure and execute it.
Run the following command to install it.
npm install @storybook/test-runner --save-dev
Update your package.json
scripts and enable the test runner.
{
"scripts": {
"test-storybook": "test-storybook"
}
}
Start your Storybook with:
npm run storybook
Storybook's test runner requires either a locally running Storybook instance or a published Storybook to run all the existing tests.
Finally, open a new terminal window and run the test-runner with:
npm run test-storybook
Configure
Test runner offers zero-config support for Storybook. However, you can run test-storybook --eject
for more fine-grained control. It generates a test-runner-jest.config.js
file at the root of your project, which you can modify. Additionally, you can extend the generated configuration file and provide testEnvironmentOptions as the test runner also uses jest-playwright under the hood.
CLI Options
The test-runner is powered by Jest and accepts a subset of its CLI options (for example, --watch
, --maxWorkers
).
If you're already using any of those flags in your project, you should be able to migrate them into Storybook's test-runner without any issues. Listed below are all the available flags and examples of using them.
Options | Description |
---|---|
--help | Output usage information test-storybook --help |
-s , --index-json | Run in index json mode. Automatically detected (requires a compatible Storybook) test-storybook --index-json |
--no-index-json | Disables index json mode test-storybook --no-index-json |
-c , --config-dir [dir-name] | Directory where to load Storybook configurations from test-storybook -c .storybook |
--watch | Run in watch mode test-storybook --watch |
--watchAll | Watch files for changes and rerun all tests when something changes.test-storybook --watchAll |
--coverage | Runs coverage tests on your stories and components test-storybook --coverage |
--coverageDirectory | Directory where to write coverage report output test-storybook --coverage --coverageDirectory coverage/ui/storybook |
--url | Define the URL to run tests in. Useful for custom Storybook URLs test-storybook --url http://the-storybook-url-here.com |
--browsers | Define browsers to run tests in. One or multiple of: chromium, firefox, webkit test-storybook --browsers firefox chromium |
--maxWorkers [amount] | Specifies the maximum number of workers the worker-pool will spawn for running tests test-storybook --maxWorkers=2 |
--testTimeout [amount] | Defines the maximum time in milliseconds that a test can run before it is automatically marked as failed. Useful for long-running tests test-storybook --testTimeout=60000 |
--no-cache | Disable the cache test-storybook --no-cache |
--clearCache | Deletes the Jest cache directory and then exits without running tests test-storybook --clearCache |
--verbose | Display individual test results with the test suite hierarchy test-storybook --verbose |
-u , --updateSnapshot | Use this flag to re-record every snapshot that fails during this test run test-storybook -u |
--eject | Creates a local configuration file to override defaults of the test-runner test-storybook --eject |
--json | Prints the test results in JSON. This mode will send all other test output and user messages to stderr. test-storybook --json |
--outputFile | Write test results to a file when the --json option is also specified. test-storybook --json --outputFile results.json |
--junit | Indicates that test information should be reported in a junit file. test-storybook --**junit** |
--ci | Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest to be run with --updateSnapshot . test-storybook --ci |
--shard [index/count] | Requires CI. Splits the test suite execution into multiple machines test-storybook --shard=1/8 |
--failOnConsole | Makes tests fail on browser console errorstest-storybook --failOnConsole |
--includeTags | Experimental feature Defines a subset of stories to be tested if they match the enabled tags. test-storybook --includeTags="test-only, pages" |
--excludeTags | Experimental feature Prevents stories from being tested if they match the provided tags. test-storybook --excludeTags="no-tests, tokens" |
--skipTags | Experimental feature Configures the test runner to skip running tests for stories that match the provided tags. test-storybook --skipTags="skip-test, layout" |
npm run test-storybook -- --watch
Run tests against a deployed Storybook
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 to run against deployed Storybooks, you can use the --url
flag:
npm run test-storybook -- --url https://the-storybook-url-here.com
Alternatively, you can set the TARGET_URL
environment variable and run the test-runner:
TARGET_URL=https://the-storybook-url-here.com yarn test-storybook
Run accessibility tests
When you have the Accessibility addon installed, you can run accessibility tests alongside your interaction tests, using the test-runner.
For more details, including configuration options, see the Accessibility testing documentation.
Run snapshot tests
Snapshot testing is a helpful tool for verifying that edge cases like errors are handled correctly. It can also be used to verify that the rendered output of a component is consistent across different test runs.
Set up
To enable snapshot testing with the test-runner, you'll need to take additional steps to set it up properly.
Add a new configuration file inside your Storybook directory with the following inside:
import type { TestRunnerConfig } from '@storybook/test-runner';
const config: TestRunnerConfig = {
async postVisit(page, context) {
// the #storybook-root element wraps the story. In Storybook 6.x, the selector is #root
const elementHandler = await page.$('#storybook-root');
const innerHTML = await elementHandler.innerHTML();
expect(innerHTML).toMatchSnapshot();
},
};
export default config;
The postVisit
hook allows you to extend the test runner's default configuration. Read more about them here.
When you execute the test-runner (for example, with yarn test-storybook
), it will run through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the __snapshots__
directory.
Configure
Out of the box, the test-runner provides an inbuilt snapshot testing configuration covering most use cases. You can also fine-tune the configuration to fit your needs via test-storybook --eject
or by creating a test-runner-jest.config.js
file at the root of your project.
Override the default snapshot directory
The test-runner uses a specific naming convention and path for the generated snapshot files by default. If you need to customize the snapshot directory, you can define a custom snapshot resolver to specify the directory where the snapshots are stored.
Create a snapshot-resolver.js
file to implement a custom snapshot resolver:
import path from 'path';
export default {
resolveSnapshotPath: (testPath) => {
const fileName = path.basename(testPath);
const fileNameWithoutExtension = fileName.replace(/\.[^/.]+$/, '');
// Defines the file extension for the snapshot file
const modifiedFileName = `${fileNameWithoutExtension}.snap`;
// Configure Jest to generate snapshot files using the following convention (./src/test/__snapshots__/Button.stories.snap)
return path.join('./src/test/__snapshots__', modifiedFileName);
},
resolveTestPath: (snapshotFilePath, snapshotExtension) =>
path.basename(snapshotFilePath, snapshotExtension),
testPathForConsistencyCheck: 'example',
};
Update the test-runner-jest.config.js
file and enable the snapshotResolver
option to use the custom snapshot resolver:
import { getJestConfig } from '@storybook/test-runner';
const defaultConfig = getJestConfig();
const config = {
// The default Jest configuration comes from @storybook/test-runner
...defaultConfig,
snapshotResolver: './snapshot-resolver.js',
};
export default config;
When the test-runner is executed, it will cycle through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the custom directory you specified.
Customize snapshot serialization
By default, the test-runner uses jest-serializer-html
to serialize HTML snapshots. This may cause issues if you use specific CSS-in-JS libraries like Emotion, Angular's ng
attributes, or similar libraries that generate hash-based identifiers for CSS classes. If you need to customize the serialization of your snapshots, you can define a custom snapshot serializer to specify how the snapshots are serialized.
Create a snapshot-serializer.js
file to implement a custom snapshot serializer:
// The jest-serializer-html package is available as a dependency of the test-runner
const jestSerializerHtml = require('jest-serializer-html');
const DYNAMIC_ID_PATTERN = /"react-aria-\d+(\.\d+)?"/g;
module.exports = {
/*
* The test-runner calls the serialize function when the test reaches the expect(SomeHTMLElement).toMatchSnapshot().
* It will replace all dynamic IDs with a static ID so that the snapshot is consistent.
* For instance, from <label id="react-aria970235672-:rl:" for="react-aria970235672-:rk:">Favorite color</label> to <label id="react-mocked_id" for="react-mocked_id">Favorite color</label>
*/
serialize(val) {
const withFixedIds = val.replace(DYNAMIC_ID_PATTERN, 'mocked_id');
return jestSerializerHtml.print(withFixedIds);
},
test(val) {
return jestSerializerHtml.test(val);
},
};
Update the test-runner-jest.config.js
file and enable the snapshotSerializers
option to use the custom snapshot resolver:
import { getJestConfig } from '@storybook/test-runner';
const defaultConfig = getJestConfig();
const config = {
...defaultConfig,
snapshotSerializers: [
// Sets up the custom serializer to preprocess the HTML before it's passed onto the test-runner
'./snapshot-serializer.js',
...defaultConfig.snapshotSerializers,
],
};
export default config;
When the test-runner executes your tests, it will introspect the resulting HTML, replacing the dynamically generated attributes with the static ones provided by the regular expression in the custom serializer file before snapshotting the component. This ensures that the snapshots are consistent across different test runs.
Generate code coverage
Storybook also provides a coverage addon. It is powered by Istanbul, which allows out-of-the-box code instrumentation for the most commonly used frameworks and builders in the JavaScript ecosystem.
Set up
Engineered to work alongside modern testing tools (e.g., Playwright), the coverage addon automatically instruments your code and generates code coverage data. For an optimal experience, we recommend using the test-runner alongside the coverage addon to run your tests.
Run the following command to install the addon.
npx storybook@latest add @storybook/addon-coverage
The CLI's add
command automates the addon's installation and setup. To install it manually, see our documentation on how to install addons.
Start your Storybook with:
npm run storybook
Finally, open a new terminal window and run the test-runner with:
npm run test-storybook -- --coverage
Configure
By default, the @storybook/addon-coverage
offers zero-config support for Storybook and instruments your code via istanbul-lib-instrument
for Webpack, or vite-plugin-istanbul
for Vite. However, you can extend your Storybook configuration file (i.e., .storybook/main.js|ts
) and provide additional options to the addon. Listed below are the available options divided by builder and examples of how to use them.
// For Vite support add the following import
// import type { AddonOptionsVite } from '@storybook/addon-coverage';
import type { AddonOptionsWebpack } from '@storybook/addon-coverage';
// Replace your-framework with the framework and builder you are using (e.g., react-webpack5, vue3-webpack5)
import type { StorybookConfig } from '@storybook/your-framework';
const coverageConfig: AddonOptionsWebpack = {
istanbul: {
include: ['**/stories/**'],
exclude: ['**/exampleDirectory/**'],
},
};
const config: StorybookConfig = {
stories: [],
addons: [
// Other Storybook addons
{
name: '@storybook/addon-coverage',
options: coverageConfig,
},
],
};
export default config;
Vite options
Options | Description | Type |
---|---|---|
checkProd | Configures the plugin to skip instrumentation in production environmentsoptions: { istanbul: { checkProd: true,}} | boolean |
cwd | Configures the working directory for the coverage tests. Defaults to process.cwd() options: { istanbul: { cwd: process.cwd(),}} | string |
cypress | Replaces the VITE_COVERAGE environment variable with CYPRESS_COVERAGE .Requires Cypress's code coverage options: { istanbul: { cypress: true,}} | boolean |
exclude | Overrides the default exclude list with the provided list of files or directories to exclude from coverageoptions: { istanbul: { exclude: ['**/stories/**'],}} | Array<String> or string |
extension | Extends the default extension list with the provided list of file extensions to include in coverageoptions: { istanbul: { extension: ['.js', '.cjs', '.mjs'],}} | Array<String> or string |
forceBuildInstrument | Configures the plugin to add instrumentation in build mode options: { istanbul: { forceBuildInstrument: true,}} | boolean |
include | Select the files to collect coverageoptions: { istanbul: { include: ['**/stories/**'],}} | Array<String> or string |
nycrcPath | Defines the relative path for the existing nyc configuration fileoptions: { istanbul: { nycrcPath: '../nyc.config.js',}} | string |
requireEnv | Overrides the VITE_COVERAGE environment variable's value by granting access to the env variablesoptions: { istanbul: { requireEnv: true,}} | boolean |
Webpack 5 options
Options | Description | Type |
---|---|---|
autoWrap | Provides support for top-level return statements by wrapping the program code in a functionoptions: { istanbul: { autoWrap: true,}} | boolean |
compact | Condenses the output of the instrumented code. Useful for debuggingoptions: { istanbul: { compact: false,}} | boolean |
coverageVariable | Defines the global variable name that Istanbul will use to store coverage resultsoptions: { istanbul: { coverageVariable: '__coverage__',}} | string |
cwd | Configures the working directory for the coverage tests. Defaults to process.cwd() options: { istanbul: { cwd: process.cwd(),}} | string |
debug | Enables the debug mode for additional logging information during the instrumentation processoptions: { istanbul: { debug: true,}} | boolean |
esModules | Enables support for ES Module syntaxoptions: { istanbul: { esModules: true,}} | boolean |
exclude | Overrides the default exclude list with the provided list of files or directories to exclude from coverageoptions: { istanbul: { exclude: ['**/stories/**'],}} | Array<String> or string |
extension | Extends the default extension list with the provided list of file extensions to include in coverageoptions: { istanbul: { extension: ['.js', '.cjs', '.mjs'],}} | Array<String> or string |
include | Select the files to collect coverageoptions: { istanbul: { include: ['**/stories/**'],}} | Array<String> or string |
nycrcPath | Defines the relative path for the existing nyc configuration fileoptions: { istanbul: { nycrcPath: '../nyc.config.js',}} | string |
preserveComments | Includes comments in the instrumented codeoptions: { istanbul: { preserveComments: true,}} | boolean |
produceSourceMap | Configures Instanbul to generate a source map for the instrumented codeoptions: { istanbul: { produceSourceMap: true,}} | boolean |
sourceMapUrlCallback | Defines a callback function invoked with the filename and the source map URL when a source map is generatedoptions: { istanbul: { sourceMapUrlCallback: (filename, url) => {},}} | function |
What about other coverage reporting tools?
Out of the box, code coverage tests work seamlessly with Storybook's test-runner and the @storybook/addon-coverage
. However, that doesn't mean you can't use additional reporting tools (e.g., Codecov). For instance, if you're working with LCOV, you can use the generated output (in coverage/storybook/coverage-storybook.json
) and create your own report with:
npx nyc report --reporter=lcov -t coverage/storybook --report-dir coverage/storybook
Set up CI to run tests
You can also configure the test-runner to run tests on a CI environment. Documented below are some recipes to help you get started.
Run against deployed Storybooks via Github Actions deployment
If you're publishing your Storybook with services such as Vercel or Netlify, they emit a deployment_status
event in GitHub Actions. You can use it and set the deployment_status.target_url
as the TARGET_URL
environment variable. Here's how:
name: Storybook Tests
on: deployment_status
jobs:
test:
timeout-minutes: 60
runs-on: ubuntu-latest
if: github.event.deployment_status.state == 'success'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'
- name: Install dependencies
run: yarn
- name: Install Playwright
run: npx playwright install --with-deps
- name: Run Storybook tests
run: yarn test-storybook
env:
TARGET_URL: '${{ github.event.deployment_status.target_url }}'
The published Storybook must be publicly available for this example to work. We recommend running the test server using the recipe below if it requires authentication.
Run against non-deployed Storybooks
You can use your CI provider (for example, GitHub Actions, GitLab Pipelines, CircleCI) to build and run the test runner against your built Storybook. Here's a recipe that relies on third-party libraries, that is to say, concurrently, http-server, and wait-on to build Storybook and run tests with the test-runner.
name: 'Storybook Tests'
on: push
jobs:
test:
timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'
- name: Install dependencies
run: yarn
- name: Install Playwright
run: npx playwright install --with-deps
- name: Build Storybook
run: yarn build-storybook --quiet
- name: Serve Storybook and run tests
run: |
npx concurrently -k -s first -n "SB,TEST" -c "magenta,blue" \
"npx http-server storybook-static --port 6006 --silent" \
"npx wait-on tcp:127.0.0.1:6006 && yarn test-storybook"
By default, Storybook outputs the build to the storybook-static
directory. If you're using a different build directory, you'll need to adjust the recipe accordingly.
Advanced configuration
Test hook API
The test-runner renders a story and executes its play function if one exists. However, certain behaviors are impossible 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 possible via Playwright/Jest but must be executed in Node.
The test-runner exports test hooks that can be overridden globally to enable use cases like visual or DOM snapshots. These hooks give you access to the test lifecycle before and after the story is rendered. Listed below are the available hooks and an overview of how to use them.
Hook | Description |
---|---|
prepare | Prepares the browser for testsasync prepare({ page, browserContext, testRunnerConfig }) {} |
setup | Executes once before all the tests runsetup() {} |
preVisit | Executes before a story is initially visited and rendered in the browserasync preVisit(page, context) {} |
postVisit | Executes after the story is visited and fully renderedasync postVisit(page, context) {} |
These test hooks are experimental and may be subject to breaking changes. We encourage you to test as much as possible within the story's play function.
To enable the hooks API, you'll need to add a new configuration file inside your Storybook directory and set them up as follows:
import type { TestRunnerConfig } from '@storybook/test-runner';
const config: TestRunnerConfig = {
// Hook that is executed before the test runner starts running tests
setup() {
// Add your configuration here.
},
/* Hook to execute before a story is initially visited before being rendered in the browser.
* The page argument is the Playwright's page object for the story.
* The context argument is a Storybook object containing the story's id, title, and name.
*/
async preVisit(page, context) {
// Add your configuration here.
},
/* Hook to execute after a story is visited and fully rendered.
* The page argument is the Playwright's page object for the story
* The context argument is a Storybook object containing the story's id, title, and name.
*/
async postVisit(page, context) {
// Add your configuration here.
},
};
export default config;
Except for the setup
function, all other functions run asynchronously. Both preVisit
and postVisit
functions include two additional arguments, a Playwright page and a context object which contains the id
, title
, and the name
of the story.
When the test-runner executes, your existing tests will go through the following lifecycle:
- The
setup
function is executed before all the tests run. - The context object is generated containing the required information.
- Playwright navigates to the story's page.
- The
preVisit
function is executed. - The story is rendered, and any existing
play
functions are executed. - The
postVisit
function is executed.
(Experimental) Filter tests
When you run the test-runner on Storybook, it tests every story by default. However, if you want to filter the tests, you can use the tags
configuration option. Storybook originally introduced this feature to generate automatic documentation for stories. But it can be further extended to configure the test-runner to run tests according to the provided tags using a similar configuration option or via CLI flags (e.g., --includeTags
, --excludeTags
, --skipTags
), only available with the latest stable release (0.15
or higher). Listed below are the available options and an overview of how to use them.
Option | Description |
---|---|
exclude | Prevents stories if they match the provided tags from being tested. |
include | Defines a subset of stories only to be tested if they match the enabled tags. |
skip | Skips testing on stories if they match the provided tags. |
import type { TestRunnerConfig } from '@storybook/test-runner';
const config: TestRunnerConfig = {
tags: {
include: ['test-only', 'pages'],
exclude: ['no-tests', 'tokens'],
skip: ['skip-test', 'layout'],
},
};
export default config;
Running tests with the CLI flags takes precedence over the options provided in the configuration file and will override the available options in the configuration file.
Disabling tests
If you want to prevent specific stories from being tested by the test-runner, you can configure your story with a custom tag, enable it to the test-runner configuration file or run the test-runner with the --excludeTags
CLI flag and exclude them from testing. This is helpful when you want to exclude stories that are not yet ready for testing or are irrelevant to your tests. For example:
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
import { MyComponent } from './MyComponent';
const meta: Meta<typeof MyComponent> = {
component: MyComponent,
tags: ['no-tests'], // 👈 Provides the `no-tests` tag to all stories in this file
};
export default meta;
type Story = StoryObj<typeof MyComponent>;
export const ExcludeStory: Story = {
//👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
tags: ['no-tests'],
};
Run tests for a subset of stories
To allow the test-runner only to run tests on a specific story or subset of stories, you can configure the story with a custom tag, enable it in the test-runner configuration file or run the test-runner with the --includeTags
CLI flag and include them in your tests. For example, if you wanted to run tests based on the test-only
tag, you can adjust your configuration as follows:
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
import { MyComponent } from './MyComponent';
const meta: Meta<typeof MyComponent> = {
component: MyComponent,
tags: ['test-only'], // 👈 Provides the `test-only` tag to all stories in this file
};
export default meta;
type Story = StoryObj<typeof MyComponent>;
export const IncludeStory: Story = {
//👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
tags: ['test-only'],
};
Applying tags for the component's stories should either be done at the component level (using meta
) or at the story level. Importing tags across stories is not supported in Storybook and won't work as intended.
Skip tests
If you want to skip running tests on a particular story or subset of stories, you can configure your story with a custom tag, enable it in the test-runner configuration file, or run the test-runner with the --skipTags
CLI flag. Running tests with this option will cause the test-runner to ignore and flag them accordingly in the test results, indicating that the tests are temporarily disabled. For example:
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
import { MyComponent } from './MyComponent';
const meta: Meta<typeof MyComponent> = {
component: MyComponent,
tags: ['skip-test'], // 👈 Provides the `skip-test` tag to all stories in this file
};
export default meta;
type Story = StoryObj<typeof MyComponent>;
export const SkipStory: Story = {
//👇 Adds the `skip-test` tag to this story to allow it to be skipped in the tests when enabled in the test-runner configuration
tags: ['skip-test'],
};
Authentication for deployed Storybooks
If you use a secure hosting provider that requires authentication to host your Storybook, you may need to set HTTP headers. This is mainly because of how the test runner checks the status of the instance and the index of its stories through fetch requests and Playwright. To do this, you can modify the test-runner configuration file to include the getHttpHeaders
function. This function takes the URL of the fetch calls and page visits as input and returns an object containing the headers that need to be set.
import type { TestRunnerConfig } from '@storybook/test-runner';
const config: TestRunnerConfig = {
getHttpHeaders: async (url) => {
const token = url.includes('prod') ? 'prod-token' : 'dev-token';
return {
Authorization: `Bearer ${token}`,
};
},
};
export default config;
Helpers
The test-runner exports a few helpers that can be used to make your tests more readable and maintainable by accessing Storybook's internals (e.g., args
, parameters
). Listed below are the available helpers and an overview of how to use them.
import type { TestRunnerConfig } from '@storybook/test-runner';
import { getStoryContext, waitForPageReady } from '@storybook/test-runner';
const config: TestRunnerConfig = {
// Hook that is executed before the test runner starts running tests
setup() {
// Add your configuration here.
},
/* Hook to execute before a story is initially visited before being rendered in the browser.
* The page argument is the Playwright's page object for the story.
* The context argument is a Storybook object containing the story's id, title, and name.
*/
async preVisit(page, context) {
// Add your configuration here.
},
/* Hook to execute after a story is visited and fully rendered.
* The page argument is the Playwright's page object for the story
* The context argument is a Storybook object containing the story's id, title, and name.
*/
async postVisit(page, context) {
// Get the entire context of a story, including parameters, args, argTypes, etc.
const storyContext = await getStoryContext(page, context);
// This utility function is designed for image snapshot testing. It will wait for the page to be fully loaded, including all the async items (e.g., images, fonts, etc.).
await waitForPageReady(page);
// Add your configuration here.
},
};
export default config;
Accessing story information with the test-runner
If you need to access information about the story, such as its parameters, the test-runner includes a helper function named getStoryContext
that you can use to retrieve it. You can then use it to customize your tests further as needed. For example, if you need to configure Playwright's page viewport size to use the viewport size defined in the story's parameters, you can do so as follows:
import type { TestRunnerConfig } from '@storybook/test-runner';
import { getStoryContext } from '@storybook/test-runner';
const { MINIMAL_VIEWPORTS } = require('storybook/viewport');
const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };
const config: TestRunnerConfig = {
async preVisit(page, story) {
// Accesses the story's parameters and retrieves the viewport used to render it
const context = await getStoryContext(page, story);
const viewportName = context.parameters?.viewport?.defaultViewport;
const viewportParameter = MINIMAL_VIEWPORTS[viewportName];
if (viewportParameter) {
const viewportSize = Object.entries(viewportParameter.styles).reduce(
(acc, [screen, size]) => ({
...acc,
// Converts the viewport size from percentages to numbers
[screen]: parseInt(size),
}),
{},
);
// Configures the Playwright page to use the viewport size
page.setViewportSize(viewportSize);
} else {
page.setViewportSize(DEFAULT_VIEWPORT_SIZE);
}
},
};
export default config;
Working with assets
If you're running a specific set of tests (e.g., image snapshot testing), the test-runner provides a helper function named waitForPageReady
that you can use to ensure the page is fully loaded and ready before running the test. For example:
import type { TestRunnerConfig } from '@storybook/test-runner';
import { waitForPageReady } from '@storybook/test-runner';
import { toMatchImageSnapshot } from 'jest-image-snapshot';
const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
const config: TestRunnerConfig = {
setup() {
expect.extend({ toMatchImageSnapshot });
},
async postVisit(page, context) {
// Awaits for the page to be loaded and available including assets (e.g., fonts)
await waitForPageReady(page);
// Generates a snapshot file based on the story identifier
const image = await page.screenshot();
expect(image).toMatchImageSnapshot({
customSnapshotsDir,
customSnapshotIdentifier: context.id,
});
},
};
export default config;
Index.json mode
The test-runner transforms your story files into tests when testing a local Storybook. For a remote Storybook, it uses the Storybook's index.json (formerly stories.json
) file (a static index of all the stories) to run the tests.
Why?
Suppose you run into a situation where the local and remote Storybooks appear out of sync, or you might not even have access to the code. In that case, the index.json
file is guaranteed to be the most accurate representation of the deployed Storybook you are testing. To test a local Storybook using this feature, use the --index-json
flag as follows:
npm run test-storybook -- --index-json
The index.json
mode is not compatible with the watch mode.
If you need to disable it, use the --no-index-json
flag:
npm run test-storybook -- --no-index-json
How do I check if my Storybook has a index.json
file?
Index.json mode requires a index.json
file. Open a browser window and navigate to your deployed Storybook instance (for example, https://your-storybook-url-here.com/index.json
). You should see a JSON file that starts with a "v": 3
key, immediately followed by another key called "stories", which contains a map of story IDs to JSON objects. If that is the case, your Storybook supports index.json mode.
What's the difference between Chromatic and Test runner?
The test-runner is a generic testing tool that can run locally or on CI and be configured or extended to run all kinds of tests.
Chromatic is a cloud-based service that runs visual and interaction tests (and soon accessibility tests) without setting up the test runner. It also syncs with your git provider and manages access control for private projects.
However, you might want to pair the test runner and Chromatic in some cases.
- Use it locally and Chromatic on your CI.
- Use Chromatic for visual and component tests and run other custom tests using the test runner.
Troubleshooting
The test runner seems flaky and keeps timing out
If your tests time out with the following message:
Timeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout
It might be that Playwright couldn't handle testing the number of stories you have in your project. Perhaps you have a large number of stories, or your CI environment has a really low RAM configuration. In such cases, you should limit the number of workers that run in parallel by adjusting your command as follows:
{
"scripts": {
"test-storybook:ci": "yarn test-storybook --maxWorkers=2"
}
}
The error output in the CLI is too short
By default, the test runner truncates error outputs at 1000 characters, and you can check the full output directly in Storybook in the browser. However, if you want to change that limit, you can do so by setting the DEBUG_PRINT_LIMIT
environment variable to a number of your choosing, for example, DEBUG_PRINT_LIMIT=5000 yarn test-storybook
.
Run the test runner in other CI environments
As the test runner is based on Playwright, you might need to use specific docker images or other configurations depending on your CI setup. In that case, you can refer to the Playwright CI docs for more information.
Tests filtered by tags are incorrectly executed
If you've enabled filtering tests with tags and provided similar tags to the include
and exclude
lists, the test-runner will execute the tests based on the exclude
list and ignore the include
list. To avoid this, make sure the tags provided to the include
and exclude
lists differ.
The test runner doesn't support Yarn PnP out of the box
If you've enabled the test-runner in a project running on a newer version of Yarn with Plug'n'Play (PnP) enabled, the test-runner might not work as expected and may generate the following error when running tests:
PlaywrightError: jest-playwright-preset: Cannot find playwright package to use chromium
This is due to the test-runner using the community-maintained package jest-playwright-preset that still needs to support this feature. To solve this, you can either switch the nodeLinker
setting to node-modules
or install Playwright as a direct dependency in your project, followed by adding the browser binaries via the install
command.
Run test coverage in other frameworks
If you intend on running coverage tests in frameworks with special files like Vue 3 or Svelte, you'll need to adjust your configuration and enable the required file extensions. For example, if you're using Vue, you'll need to add the following to your nyc configuration file (i.e., .nycrc.json
or nyc.config.js
):
export default {
// Other configuration options
extension: ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.vue'],
};
The coverage addon doesn't support optimized builds
If you generated a production build optimized for performance with the --test
flag, and you're using the coverage addon to run tests against your Storybook, you may run into a situation where the coverage addon doesn't instrument your code. This is due to how the flag works, as it removes addons that have an impact on performance (e.g., Docs
, coverage addon). To resolve this issue, you'll need to adjust your Storybook configuration file (i.e., .storybook/main.js|ts
) and include the disabledAddons
option to allow the addon to run tests at the expense of a slower build.
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
const config: StorybookConfig = {
framework: '@storybook/your-framework',
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
addons: ['@storybook/addon-docs', '@storybook/addon-vitest', '@storybook/addon-coverage'],
build: {
test: {
disabledAddons: ['@storybook/addon-docs'],
},
},
};
export default config;
The coverage addon doesn't support instrumented code
As the coverage addon is based on Webpack5 loaders and Vite plugins for code instrumentation, frameworks that don't rely upon these libraries (e.g., Angular configured with Webpack), will require additional configuration to enable code instrumentation. In that case, you can refer to the following repository for more information.
More testing resources
- Interaction testing for user behavior simulation
- Accessibility testing for accessibility
- Visual testing for appearance
- Snapshot testing for rendering errors and warnings
- Test coverage for measuring code coverage
- CI for running tests in your CI/CD pipeline
- Vitest addon for running tests in Storybook
- End-to-end testing for simulating real user scenarios
- Unit testing for functionality