• Docs
  • Components
  • Blocks
  • Admin
CtrlK
Get Started
  • Introduction
  • Setup
  • CLI
  • VS Code Extension
  • Figma Code Connect
  • MCP Server
  • llms.txt
  • Changelog
Foundations
  • Design Tokens
  • Theming & Modes
  • Semantic Colors
  • Spacing
  • Typography
Testing
  • Test Guide
  • Performance Tests
  • Visual Regression
Components
  • Accordion
  • Activity Feed
  • Alert
  • Avatar
  • Badge
  • Breadcrumbs
  • Button
  • Card
  • Carousel
  • Checkbox
  • Collapsible
  • Combobox
  • Command Palette
  • Context Menu
  • Date Picker
  • Dialog
  • Dropdown Menu
  • File Upload
  • Hover Card
  • Input
  • Kbd
  • Label
  • Menubar
  • Metric Card
  • Multi Select
  • Navigation Menu
  • Pagination
  • Popover
  • Progress
  • Quick Actions
  • Radio
  • Rating
  • Resizable
  • Segmented Control
  • Select
  • Separator
  • Sheet
  • Skeleton
  • Slider
  • Spinner
  • Split Button
  • Stepper
  • Switch
  • Table
  • Tabs
  • Tag Input
  • Textarea
  • Timeline
  • Toast
  • Toggle
  • Toggle Group
  • Tooltip
  • Tree View
Blocks
  • Activity Feed
  • App Shell
  • Authentication Block
  • Benefits Section
  • Cta Section
  • Data Table
  • Empty State
  • Faq Section
  • Feature Grid Section
  • Footer Section
  • Hero Section
  • Kpi Dashboard
  • Kpi Strip
  • Link Card
  • Metric Card
  • Navigation Header
  • Pagination Footer
  • Pricing Table
  • Quick Actions
  • Settings Screen
Resources
  • API Reference
Performance TestsAccordion

Visual Regression Testing with Chromatic

Chromatic automatically:

Fragment UI uses Chromatic for automated visual regression testing to catch unintended visual changes across components.

Overview

Chromatic automatically:

  • Captures screenshots of all Storybook stories
  • Compares them against baseline images
  • Detects visual differences between versions
  • Provides a visual review interface for PRs
  • Tracks component changes over time

How It Works

Automatic Testing

  1. On Pull Requests: Chromatic runs automatically and comments on PRs with visual changes
  2. On Main Branch: Chromatic updates baseline images and runs tests
  3. Visual Diffs: Screenshots are compared pixel-by-pixel with configurable thresholds

Configuration

Visual regression tests are configured in:

  • packages/ui/.storybook/preview.ts - Global Chromatic parameters
  • packages/ui/.storybook/chromatic.config.ts - Chromatic-specific configuration
  • .github/workflows/chromatic.yml - CI/CD workflow

Viewports

Components are tested across multiple viewports:

  • Mobile: 320px × 568px
  • Tablet: 768px × 1024px
  • Desktop: 1024px × 768px
  • Large Desktop: 1440px × 900px

Themes

Visual tests run across different themes:

  • Light theme (default)
  • Dark theme

Viewing Results

In GitHub PRs

When Chromatic detects visual changes:

  1. A comment is automatically added to the PR
  2. Click "Review changes" to see visual diffs
  3. Approve or request changes
  4. PR cannot be merged until visual changes are approved

In Chromatic Dashboard

  1. Go to Chromatic Dashboard
  2. Select your project
  3. View build history and visual diffs
  4. Compare versions side-by-side

Story Configuration

Per-Story Configuration

Override Chromatic settings for specific stories:

export const MyStory: Story = {
  parameters: {
    chromatic: {
      // Only test specific viewports
      viewports: [768, 1024],
      // Use stricter diff threshold
      diffThreshold: 0.1,
      // Disable for this story
      disable: false,
      // Pause animations
      pauseAnimationAtEnd: true,
    },
  },
};

Ignoring Dynamic Content

For components with dynamic content (timestamps, random IDs, etc.):

export const MyStory: Story = {
  parameters: {
    chromatic: {
      ignore: {
        // Ignore by CSS selector
        selector: '.timestamp',
        // Or by pixel coordinates
        x: 0,
        y: 0,
        width: 100,
        height: 100,
      },
    },
  },
};

Diff Thresholds

The diff threshold determines how sensitive Chromatic is to visual changes. Lower values mean more strict comparison:

  • 0.0 - 0.1: Very strict (catches minor changes)
  • 0.1 - 0.2: Standard (default: 0.2)
  • 0.2 - 0.5: Relaxed (catches major changes only)

Best Practices

  • Review all changes: Always review visual diffs before approving
  • Use appropriate thresholds: Adjust thresholds per story if needed
  • Ignore dynamic content: Use ignore regions for timestamps, IDs, etc.
  • Test all themes: Ensure components work in both light and dark modes
  • Test all viewports: Verify responsive behavior across screen sizes

Troubleshooting

False Positives

If Chromatic detects changes that aren't real:

  • Check if animations are paused
  • Verify dynamic content is ignored
  • Adjust diff threshold if needed

Missing Screenshots

If screenshots aren't being generated:

  • Verify Storybook is building correctly
  • Check Chromatic workflow in GitHub Actions
  • Ensure Chromatic token is configured

Links

  • Test Guide
  • Performance Tests
  • Chromatic Dashboard
Performance TestsAccordion