Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

To visually test Vue.js components with Storybook, write stories for the component states that matter, capture those stories, and compare each run with an accepted visual baseline. Review every difference: approve intentional design changes as the new baseline, or fix unexpected changes and rerun. A visual diff checks appearance, not whether interactions work.

What a Storybook visual test checks

A visual test compares a rendered story image with a previous baseline. It can surface visible changes in layout, color, size, contrast, and other aspects of appearance. Storybook’s visual testing documentation describes visual tests as a way to catch bugs in UI appearance.

The story is the test case: each story captures a component in a particular state, including the props and variations you choose to represent. Storybook’s Vue tutorial explains that every story can serve as a test specification. This makes story coverage important: a state with no story is not covered by this visual workflow.

Set up Storybook for Vue 3 with Vite

For the Vue 3 and Vite integration, Storybook’s framework documentation lists Vue 3 and Vite 5 or later as requirements. The commands below follow its documented setup; compatibility and commands can change, so check the current Vue 3 + Vite framework guide if your project uses a different version or build tool.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. From your project directory, run npm create storybook@latest and follow the setup prompts.

  2. Start Storybook with npm run storybook.

  3. Open the local Storybook instance and confirm that your component stories render before configuring visual comparisons.

For other Vue and build-tool combinations, do not assume these requirements apply; consult the relevant framework documentation.

Write stories for the visual states that matter

Choose states that would be important to notice if their appearance changed. For a button, that might mean separate stories for its ordinary, disabled, and loading states. For a form field, it might mean empty, populated, and validation-error states. These are examples of how to choose coverage, not required Storybook story names.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  • Include relevant props and meaningful variations so a story represents a clear, reproducible state.

  • Keep story setup stable. If a state depends on data, provide it explicitly rather than relying on a changing external value.

  • Add stories for additional states as the component’s visual requirements grow. The visual workflow can only compare states represented by stories.

Add Chromatic and create visual baselines

Storybook documents Chromatic visual testing as its cloud visual-testing service and describes the @chromatic-com/storybook addon. This documented setup requires a Chromatic account and project.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. Install the addon using npx storybook@latest add @chromatic-com/storybook.

  2. Sign in to Chromatic, select or create a project, and link that project to the addon as prompted.

  3. Run the visual tests from the Storybook UI. The first build creates baselines; later runs compare new captures against those baselines.

  4. Review the visual-test panel and the changed pixels for each difference. Accept a change as the updated baseline when it is intentional. If it is unexpected, fix the component or story and rerun the check.

    What’s actually slowing this PC down?

    Pick the symptom - the matching free tool is one click away.

    Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Storybook documents chromatic.config.json options including projectId, optional buildScriptName, debug, and zip. Confirm their current meanings and setup in the live documentation before relying on a particular configuration.

Review diffs instead of treating them as automatic verdicts

A difference is a prompt for review, not proof that the interface is broken. Decide whether it reflects an approved design change or an unintended change. Accept the former as the new baseline; for the latter, correct the component or story and run the comparison again. The baseline should reflect the appearance the team intends to preserve.

For team automation, Storybook’s visual-testing documentation describes configuring CI with Chromatic authentication and a project token, as well as pull- or merge-request checks that notify teams about test errors or UI changes. Follow the current service documentation for the setup applicable to your project; this workflow does not depend on a particular CI provider.

Choose the test that answers your question

Test type What it observes What you maintain How to interpret results
Visual Rendered appearance, compared as images Stories and accepted visual baselines Review differences and approve intended changes or investigate unexpected ones
Interaction Behavior after simulated user actions A story’s play function and assertions Check whether actions produce the asserted outcomes
Snapshot Rendered DOM or HTML changes Snapshots and their expected output Review markup changes; Storybook notes that snapshots can be noisy to maintain
Accessibility Accessibility checks Accessibility test setup and any relevant assertions Use as a complementary check, not a substitute for appearance or behavior testing

Storybook documents interaction tests that use a story’s play function to simulate actions and assert outcomes. They can run with the Vitest addon or test-runner. A screenshot comparison does not prove that a button works, a form submits, or any other interaction succeeds. Use interaction tests for those behavior questions and visual tests for appearance.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshoot common visual-testing problems

The Vue/Vite setup does not match the project

The documented framework requirements here are Vue 3 and Vite 5 or later. If your versions or build tool differ, consult Storybook’s framework documentation for the matching integration rather than assuming this setup applies.

A story does not show the state you intended

Check that the story supplies the intended props and state, then confirm that it renders correctly in Storybook before running a comparison. A visual test can only capture the state the story actually renders.

A comparison reports a visual difference

Inspect the changed area and decide whether the design change is intentional. Update the baseline only for an approved change; otherwise, correct the component or story and rerun.

The Chromatic addon or project is not linked

Check that the addon installation completed, that you signed in, and that you selected or created a project and linked it to the addon. Use Chromatic’s current setup guidance if the prompts or configuration differ.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

CI cannot authenticate or reports an error

Verify the Chromatic authentication and project token configuration against Storybook’s current CI instructions. The documented workflow relies on those credentials; do not assume a particular provider’s settings from this general guide.

Or skip the browser setup

If you need a screenshot outside Storybook’s story-and-baseline workflow, ScreenshotNeo can capture a URL with one GET request and return an image or PDF. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots per month are free with no card, with paid plans starting at $5 for 3,000. This is a screenshot API, not a replacement for Storybook visual baselines or interaction assertions.

cURL example (see the ScreenshotNeo API documentation):

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

Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.