Applitools Eyes with Storybook for Component Screenshot Testing

Applitools Eyes can capture Storybook stories as visual checkpoints and compare them with saved baselines. The current quick-start flow uses the @applitools/eyes-storybook package, npx eyes-setup to create configuration, an Applitools API key, and npx eyes-storybook to run the checks. The first run establishes baselines; later runs surface visual differences for review in the Applitools Dashboard.

This is screenshot comparison for the component states represented by your stories. It does not invent missing stories or verify behavior that your stories do not render. Start by deciding which states matter, then make those states reproducible in Storybook.

1. Prepare stories for visual coverage

Stories are the units the runner can discover and capture. Add stories for meaningful variants and states, such as default, hover, loading, empty, validation error, disabled, and long-content cases where they apply. A component with only a default story will only provide that state to this visual workflow.

Keep story inputs deterministic: use fixed text, dates, and data rather than values that change on each run.
Make required fonts, assets, and styles available to the Storybook instance before capture.
Separate materially different states into stories so a review identifies which state changed.
Review animations, rotating content, clocks, random data, and remote content; these can create differences unrelated to a code change.

2. Install and configure Eyes

Use the documented quick-start commands in the project that contains Storybook. The guided setup generates an applitools.config.js with defaults.

npm i -D @applitools/eyes-storybook
npx eyes-setup

When prompted, provide an Applitools API key, or set it in the environment. Do not commit a real key to source control.

# macOS or Linux shell
export APPLITOOLS_API_KEY="YOUR_API_KEY"

# PowerShell
$env:APPLITOOLS_API_KEY="YOUR_API_KEY"

Keep the generated configuration in the project and review it alongside your repository’s Storybook setup. The exact options needed can depend on the project; the supplied quick-start evidence does not establish a complete configuration reference or compatibility matrix. See the Applitools documentation for current configuration details.

3. Run the story screenshots

The CLI can start Storybook for the run. From the project root:

npx eyes-storybook

If Storybook is already running and reachable at a URL, pass it with -u:

npx eyes-storybook -u http://localhost:6006

Use the URL of the instance you intend to test. Ensure the server is ready and its stories load before starting the runner. The CLI discovers available stories and captures visual checkpoints; use the result link to open the run in the Applitools Dashboard.

4. Review and update baselines deliberately

The first run creates baselines for each story and environment. Later runs compare new captures to those baselines. A difference is a review item, not an automatic verdict that the code is wrong.

Open the run in the Dashboard and inspect the changed story and its screenshot difference.
Check whether the difference matches the intended code or design change.
Accept intended changes and save the updated baseline.
Reject unexpected changes, keep the prior baseline, and investigate the component, styles, assets, or test environment.

Make baseline updates part of code review when they result from a planned visual change. Avoid accepting a batch of differences without checking what changed; an accidental baseline update can make a regression appear normal on later runs.

5. Choose CLI or the Storybook addon

The CLI is the documented quick-start path and supports command-line runs, including targeting an existing Storybook URL. Applitools also offers an Eyes Addon for Storybook for teams that prefer to run and triage checks in Storybook. Its product materials describe results grouped to match Storybook structure and a workflow for interactive development and headless pipeline runs using the same configuration. Confirm current compatibility and setup instructions for your Storybook version in Applitools’ documentation before adopting the addon.

Whichever route you choose, use the same coverage principle: add stories for the states you intend to protect, run them consistently, and have a person review baseline changes.

6. Run checks in a development or pipeline workflow

For local development, run the CLI after changing a component or its stories, then review the result. For a pipeline, run it in an environment where the repository dependencies, API key, and Storybook assets are available. The sources describe CLI usage in pipeline workflows, but do not specify a universal CI configuration; adapt the command to your CI provider and the way your project builds and serves Storybook.

Store APPLITOOLS_API_KEY as a CI secret, not as a checked-in value.
Make sure the command waits for the Storybook server to be ready if your pipeline starts it separately.
Keep dependencies and browser-related environment consistent between runs where practical.
Publish or retain the run link so reviewers can inspect visual changes and their context.
Decide who can accept baseline changes and how those changes are reviewed with the code.

7. Handle dynamic content and environment differences

Unstable inputs make screenshot diffs noisy. Fix or control timestamps, randomized content, animations, remote data, and feature flags when possible. Keep the viewport and environment consistent for comparisons, and check whether a change is limited to one story or appears across many stories.

Eyes materials for other integrations discuss match levels and ignored dynamic regions, but those examples are not Storybook API instructions. Do not copy Playwright-specific option syntax into Storybook configuration. Consult the current Storybook SDK documentation for supported controls and syntax.

8. Troubleshooting

Symptom	Likely cause	What to check
The runner cannot authenticate	The API key is missing, invalid, or unavailable to the process.	Set `APPLITOOLS_API_KEY` in the shell or CI secret environment, then rerun. Do not put the real key in committed files.
No stories are captured	The wrong Storybook URL was supplied, the server is not ready, or stories are not discoverable in that instance.	Open the Storybook URL, confirm the intended stories render, and use the correct `-u` value for an existing server.
The CLI cannot reach a running Storybook	The URL, port, host binding, or server lifetime is wrong.	Check that the instance is reachable from the runner process and remains running for the capture.
Many unrelated differences appear	Environment or rendered content varies between runs.	Stabilize data, time, fonts, assets, viewport, and animation state; compare which stories share the difference.
An intended update keeps appearing as a diff	The reviewed baseline has not been accepted and saved for the relevant story and environment.	Confirm the correct run and environment, then accept the intended change in the Dashboard.
A visual issue is not detected	The affected state is not represented by a story or was not included in the run.	Add a story that renders the state and confirm it is discovered in the run.
Addon instructions do not match the project	Storybook or addon compatibility and setup may vary.	Check Applitools’ current integration documentation for the project’s versions; use the documented CLI path if appropriate.

9. Performance, reliability, and cost considerations

Run time depends on the number of stories and environments being captured, the Storybook startup and load time, and the rendered assets. Keep the suite focused on useful component states, and avoid duplicating equivalent stories across runs without a reason. The available research does not establish a Storybook-specific benchmark, fixed run time, or pricing figure, so estimate from your own workflow and consult current Applitools account information for costs.

Reliability improves when the same stories render the same inputs in comparable environments. A stable Storybook URL, loaded fonts and assets, controlled dynamic content, and explicit baseline review all reduce avoidable noise. Visual checks complement functional and accessibility tests; a screenshot comparison alone does not prove that interactions, semantics, or keyboard behavior work.

Or skip the browser setup

If you need a screenshot artifact without installing or running the Storybook Eyes workflow, ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request captures a URL as PNG, JPEG, WebP, or PDF. This captures a page URL; it does not replace Eyes’ story discovery and baseline comparison workflow.

For a published Storybook URL, a basic call looks like this. See the ScreenshotNeo API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Replace the example target with your publicly reachable Storybook URL. ScreenshotNeo removes cookie banners, popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does Eyes create a screenshot test for every possible component state?

No. It captures the stories Storybook exposes. Create stories for the states you want to compare.

Can I run Eyes against Storybook that is already running?

Yes. The quick start documents npx eyes-storybook -u http://localhost:6006 for an existing instance.

Should every visual difference be accepted?

No. Accept only deliberate UI changes; investigate and reject unexpected differences.

Can ScreenshotNeo replace the Eyes baseline review?

No. ScreenshotNeo can capture a URL, while the Eyes workflow described here discovers stories and compares captures against baselines for review.