DOCSEARCHbyAlgolia
Submit Docs

Chromatic Documentation: Visual, Accessibility, and Interaction Testing

website·Indexed Apr 17, 2026

https://www.chromatic.com/docs/

Official documentation for Chromatic, a cloud-based toolchain for visual testing, reviewing, and documenting Storybook components. This guide covers setup and integration with Storybook, Playwright, and Cypress. It details features including the Diff Inspector for analyzing visual changes, accessibility testing powered by axe, interaction testing for user behaviors, and Shadow DOM support. The docs also explain configuration options, CI/CD workflows, monorepo management, browser support, and custom integrations via webhooks and Slack.

Tokens
110.8K
Snippets
424
Records
708
Agent score
50%

What's inside Chromatic

  1. Overview of the Accessibility Dashboard

    The Accessibility dashboard provides a comprehensive view of accessibility violations across your Storybook components. It continuously monitors violations to help you track compliance trends and prioritize remediation. Key features include daily sampling of violations, trend visualization over time, and a component-level data table that ranks components by violation count to help teams address accessibility debt by focusing on high-impact areas first.

  2. Overview of Chromatic UI Testing Platform

    Chromatic is a testing platform that scans every possible UI state across browsers to catch bugs in appearance, functionality, and accessibility. It integrates with Storybook, Playwright, and Cypress to enable visual, interaction, and accessibility testing. Key capabilities include assigning reviewers, resolving discussions for team sign-off, and running tests in parallel across multiple browsers and viewports.

  4. Understand Chromatic resource loading and timeout behavior

    Chromatic waits for resources like images and fonts to load before capturing a snapshot. If resources fail to load, it can lead to unintended UI changes in the snapshot. Chromatic uses a multistage timeout: 15 seconds to render a story and an additional 15 seconds to execute interaction tests. If resources do not load within this time, Chromatic will retry. After several retries, the snapshot is captured anyway, and a warning message is displayed.

  5. Handle Build Update webhooks

    Chromatic sends a POST request to your webhook URL whenever a build's status changes. The request body includes details about the build, such as the build number, branch, commit hash, status, result, and links to the Storybook and Chromatic web UI. The payload uses version 2 of the webhook format. You can use this data to trigger external CI/CD pipelines, update status badges, or notify team channels.
    {
  "version": 2,
  "event": "build",
  "build": {
    "number": 123,
    "branch": "main",
    "commit": "f6f223efb3b99b83ac3b0b6ece9f9620619933c1",
    "committerName": "John Doe",
    "status": "ACCEPTED",
    "result": "SUCCESS",
    "storybookUrl": "https://5dca7f6a6ce19b00201febb7-yubzntxvow.chromatic.com/",
    "webUrl": "https://www.chromatic.com/build?appId=5dca7f6a6ce19b00201febb7&number=123",
    "changeCount": 12,
    "componentCount": 42,
    "specCount": 100,
    "project": {
      "name": "my-project",
      "accountName": "my-org",
      "accountAvatarUrl": "https://avatars.githubusercontent.com/u/24584319?s=200",
      "webUrl": "https://www.chromatic.com/builds?appId=5dca7f6a6ce19b00201febb7"
    }
  }
}

  6. Storybook MCP for AI Agent Integration

    Chromatic supports Storybook MCP (Model Context Protocol) to improve AI agent output by providing better context about your components. Chromatic simplifies the process of hosting your Storybook MCP server with proper authentication and access control, enabling AI agents to interact with your component library more effectively.

  7. Understand how Chromatic captures UI snapshots

    A snapshot is an image of the UI rendered by a test, along with metadata captured in Chromatic's Capture Cloud infrastructure. Snapshots power UI Tests and UI Review features. Chromatic captures snapshots by loading tests in standardized browsers, waiting for the UI to render (based on network quiescence and other heuristics), taking a screenshot, cropping it to the UI dimensions, and saving it for comparison against baselines.

    For Stories, the screenshot is cropped to the bounding box of the <body> element to eliminate negative space. For E2E tests (Playwright/Cypress), the full width and height of the rendered UI is captured.

  8. Understand TurboSnap mechanism for selective UI testing

    TurboSnap is a Chromatic feature that accelerates UI tests by analyzing Git history and the Webpack/Vite dependency graph. It identifies only the components and stories affected by code changes and snapshots them. For unchanged stories, it copies snapshots from the baseline ancestor build. This reduces test runtime and billable snapshot counts. If any UI tests were denied on the ancestor build, Chromatic will always re-capture those stories to handle inconsistent snapshots.

  9. Configure email notifications for UI Tests and UI Review

    Chromatic sends email notifications to keep collaborators informed about build changes and discussions. The notification behavior differs by feature:

    • UI Tests: The build owner receives emails when there are changes to a build or when discussions occur. If you are not the build owner but participate in a discussion thread, you will receive notifications for replies to that specific thread.
    • UI Review: The PR owner and any participants receive emails when a discussion begins, is replied to, or gets resolved.

    You can control which activities trigger emails and where they are sent by visiting the Notifications page.

    https://www.chromatic.com/notifications

  10. Integrate accessibility testing with Chromatic and Storybook

    Chromatic integrates accessibility testing into your development workflow by building on Storybook and the axe-core library. This setup allows you to write stories as test cases and run accessibility checks locally in Storybook for fast feedback. When you are ready to merge, Chromatic automatically runs accessibility regression tests on all stories in CI, providing a dashboard to view WCAG issues across components.

  11. Understand the difference between UI Tests and UI Review

    Chromatic separates automated testing from human review to streamline the pull request workflow:

    • UI Tests: Automated checks that run in CI when code is pushed. They compare snapshots against the baseline to detect visual and functional regressions (e.g., layout shifts, color changes, interaction failures). They do not require human approval to pass if changes are accepted.
    • UI Review: A manual process where stakeholders (designers, PMs) review the specific changes (changeset) that will be merged. It ensures that intentional changes are approved before merging.

    Key Distinction: UI Tests verify what changed (technical correctness), while UI Review verifies if the change is acceptable (business/design approval).

  12. Handle Review Update webhooks

    Chromatic sends a POST request to your webhook URL when a review is created. The payload contains information about the review, including its number, title, status (OPEN, MERGED, or CLOSED), base and head branch names, and author details. This is useful for tracking review lifecycle events in external project management tools.
    {
  "version": 2,
  "event": "review",
  "review": {
    "number": 1,
    "title": "My review",
    "status": "OPEN",
    "baseRefName": "main",
    "headRefName": "feature",
    "isCrossRepository": false,
    "webUrl": "https://www.chromatic.com/review?appId=5dca7f6a6ce19b00201febb7&number=1",
    "author": {
      "name": "John Doe",
      "username": "example",
      "avatarUrl": "https://avatars.githubusercontent.com/u/24584319?s=200"
    }
  }
}