Run story tests after UI changes
After editing anything that changes how the UI looks, run the story tests using the Storybook test runner, never a package.json test script.
Storybook · Writing and testing · all subjects
test runner
31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Do not report completion while story tests are failing
Never report completion of work while story tests are failing.
Test runner overview and purpose
Storybook test runner turns all stories into executable tests, powered by Jest and Playwright. For stories without a play function, it verifies whether the story renders without errors. For stories with a play function, it checks for errors in the play function and verifies that all assertions passed. These tests run in a live browser and can be executed via command line or CI server.
Test runner superseded by Vitest addon
The test runner has been superseded by the Vitest addon for React, Vue, and Svelte frameworks. The Vitest addon offers the same functionality powered by faster and more modern Vitest browser mode, and enables the full Storybook Test experience with interaction, accessibility, and visual tests from the Storybook app. For Vite-powered Storybook frameworks, using the Vitest addon is recommended instead of the test runner.
Test runner setup steps
To set up the test runner: 1) Install with the package manager command. 2) Update package.json scripts with 'test-storybook' command. 3) Start Storybook with a local development server. 4) In a new terminal, run the test-runner. The test-runner requires either a locally running Storybook instance or a published Storybook to run all existing tests.
Test runner CLI options reference table
Test runner CLI options: --help (output usage information), -s/--index-json (run in index json mode, automatically detected), --no-index-json (disables index json mode), -c/--config-dir [dir-name] (directory for Storybook configs), --watch (run in watch mode), --watchAll (watch files and rerun all tests on changes), --coverage (run coverage tests), --coverageDirectory (directory for coverage report output), --url (define URL to run tests in), --browsers (define browsers: chromium, firefox, webkit), --maxWorkers [amount] (maximum worker pool size), --testTimeout [amount] (max test runtime in milliseconds), --no-cache (disable cache), --clearCache (delete Jest cache directory), --verbose (display individual test results), -u/--updateSnapshot (re-record failing snapshots), --eject (create local config file), --json (print results in JSON), --outputFile (write test results to file with --json), --junit (report in junit file), --ci (fail on new snapshots instead of auto-storing), --shard [index/count] (split test suite across machines), --failOnConsole (fail on browser console errors), --includeTags (test stories matching enabled tags), --excludeTags (prevent stories matching tags from testing), --skipTags (skip testing for stories matching tags).
Test runner zero-config support and eject
Test runner offers zero-config support for Storybook. To get more fine-grained control, run 'test-storybook --eject' which generates a 'test-runner-jest.config.js' file at the root of the project that you can modify. You can also extend the generated configuration file and provide testEnvironmentOptions as the test runner uses jest-playwright under the hood.
Test runner against deployed Storybook
By default, the test-runner assumes a locally running Storybook on port 6006. To run against deployed Storybooks, use the --url flag (e.g., 'test-storybook --url http://the-storybook-url-here.com') or set the TARGET_URL environment variable (e.g., 'TARGET_URL=https://the-storybook-url-here.com yarn test-storybook').
Coverage addon powered by Istanbul
Storybook provides a coverage addon powered by Istanbul that allows out-of-the-box code instrumentation for commonly used frameworks and builders in the JavaScript ecosystem. It works with istanbul-lib-instrument for Webpack or vite-plugin-istanbul for Vite.
Coverage addon setup
To set up code coverage: 1) Install the coverage addon. 2) Start Storybook with 'yarn start' or equivalent. 3) In a new terminal, run the test-runner with coverage via 'yarn test-storybook --coverage'.
Test runner vs Chromatic
The test-runner is a generic testing tool that runs locally or on CI and can be configured 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 git providers and manages access control. You might use both: locally with test-runner and Chromatic on CI, or use Chromatic for visual and component tests while running other custom tests with the test runner.
Coverage addon Vite options
Coverage addon Vite options: checkProd (skip instrumentation in production, boolean), cwd (working directory for coverage tests, defaults to process.cwd(), string), cypress (replace VITE_COVERAGE with CYPRESS_COVERAGE, boolean), exclude (override default exclude list, Array<String> or string), extension (extend default extension list, Array<String> or string), forceBuildInstrument (add instrumentation in build mode, boolean), include (select files to collect coverage, Array<String> or string), nycrcPath (relative path for existing nyc config file, string), requireEnv (override VITE_COVERAGE by accessing env variables, boolean).
Coverage addon Webpack 5 options
Coverage addon Webpack 5 options: autoWrap (support top-level return statements, boolean), compact (condense output, boolean), coverageVariable (global variable for coverage results, string, default '__coverage__'), cwd (working directory, string), debug (enable debug mode, boolean), esModules (enable ES Module syntax, boolean), exclude (override default exclude list, Array<String> or string), extension (extend default extension list, Array<String> or string), include (select files to collect coverage, Array<String> or string), nycrcPath (relative path for nyc config, string), preserveComments (include comments in instrumented code, boolean), produceSourceMap (generate source map, boolean), sourceMapUrlCallback (callback for filename and source map URL, function).
Test runner test hook API
The test-runner exports test hooks that can be overridden globally to enable use cases like visual or DOM snapshots. Hooks are: prepare (prepares browser for tests, 'async prepare({ page, browserContext, testRunnerConfig }) {}'), setup (executes once before all tests, 'setup() {}'), preVisit (executes before story is initially visited, 'async preVisit(page, context) {}'), postVisit (executes after story is visited and fully rendered, 'async postVisit(page, context) {}').
Test runner test lifecycle with hooks
When the test-runner executes with hooks enabled, the lifecycle is: 1) setup function executes before all tests. 2) Context object is generated with required information. 3) Playwright navigates to the story page. 4) preVisit function executes. 5) Story is rendered and any existing play functions execute. 6) postVisit function executes. Except for setup, all other functions run asynchronously. Both preVisit and postVisit include two arguments: a Playwright page and a context object containing id, title, and name of the story.
Test runner tags filtering options
Test runner filtering options via tags: exclude (prevents stories matching provided tags from being tested), include (defines subset of stories only to be tested if they match enabled tags), skip (skips testing on stories matching provided tags). Running tests with CLI flags (--includeTags, --excludeTags, --skipTags) takes precedence over configuration file options and will override them.
Test runner disable tests with tags
To prevent specific stories from being tested, configure the story with a custom tag and enable it in the test-runner configuration file using the exclude option, or run the test-runner with the --excludeTags CLI flag. This is helpful when excluding stories not yet ready for testing or irrelevant to tests.
Test runner include tests for subset of stories
To run tests only on a specific story or subset of stories, configure the story with a custom tag and enable it in the test-runner configuration file using the include option, or run the test-runner with the --includeTags CLI flag. Tags should be applied at the component level (using meta) or at the story level. Importing tags across stories is not supported.
Test runner skip tests with tags
To skip running tests on a particular story or subset of stories, configure the story with a custom tag and enable it in the test-runner configuration file using the skip option, or run the test-runner with the --skipTags CLI flag. This causes the test-runner to ignore the tests and flag them accordingly in test results, indicating the tests are temporarily disabled.
Test runner authentication for deployed Storybooks
If using a secure hosting provider requiring authentication, modify the test-runner configuration file to include the getHttpHeaders function. This function takes the URL of fetch calls and page visits as input and returns an object containing the headers that need to be set.
Test runner getStoryContext helper
The test-runner exports a getStoryContext helper function to access information about a story, such as its parameters. This allows you to customize tests further as needed. For example, you can use it to configure Playwright's page viewport size to use the viewport size defined in the story's parameters.
Test runner waitForPageReady helper
The test-runner provides a waitForPageReady helper function that you can use to ensure the page is fully loaded and ready before running tests. This is useful when running specific sets of tests like image snapshot testing.
Test runner index.json mode
The test-runner transforms story files into tests when testing a local Storybook. For a remote Storybook, it uses the Storybook's index.json file (a static index of all stories) to run tests. Use the --index-json flag to test a local Storybook using this feature. index.json mode is not compatible with watch mode.
Check for index.json support
To check if a Storybook has an index.json file, open a browser and navigate to the deployed instance URL with '/index.json' appended (e.g., 'https://your-storybook-url-here.com/index.json'). You should see a JSON file starting with a 'v': 3 key, immediately followed by a 'stories' key containing a map of story IDs to JSON objects. If present, the Storybook supports index.json mode.
Disable index.json mode
To disable index.json mode, use the --no-index-json flag when running the test-runner.
Test runner timeout troubleshooting
If tests time out with 'Timeout - Async callback was not invoked within the 15000 ms timeout', Playwright may not be handling the number of stories in the project. This can occur with many stories or low RAM CI environments. Limit parallel workers by adjusting the command with --maxWorkers=2 or another lower number.
Test runner error output truncation
By default, the test runner truncates error outputs at 1000 characters. Full output is available in Storybook in the browser. To change the limit, set the DEBUG_PRINT_LIMIT environment variable to a number of choice (e.g., 'DEBUG_PRINT_LIMIT=5000 yarn test-storybook').
Test runner tags filtering incorrect execution
If you've enabled filtering tests with tags and provided similar tags to both include and exclude lists, the test-runner will execute tests based on the exclude list and ignore the include list. Make sure the tags provided to include and exclude lists differ.
Coverage addon Vue and Svelte configuration
For frameworks with special files like Vue 3 or Svelte, adjust your configuration and enable required file extensions. For Vue, add the configuration to the nyc file (.nycrc.json or nyc.config.js).
Coverage addon optimized builds incompatibility
If you generated a production build optimized for performance with the --test flag and using the coverage addon, the coverage addon may not instrument your code. This is because the flag removes addons impacting performance. To resolve this, adjust the Storybook configuration file (.storybook/main.js|ts) and include the disabledAddons option to allow the addon to run at the expense of slower build.
Coverage addon instrumented code requirements
The coverage addon is based on Webpack5 loaders and Vite plugins for code instrumentation. Frameworks not relying on these libraries (e.g., Angular configured with Webpack) require additional configuration to enable code instrumentation.