component-screenshot-testing

Screenshot testing for React components with Playwright. Captures component pixels and compares to baselines. Auto-apply when editing React component stories or *.visual.spec.ts files that test UI components.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill automates visual regression testing for React components using Playwright. It ensures UI consistency by capturing component-level screenshots and comparing them against baseline images to detect pixel-level discrepancies, layout shifts, and styling regressions. By integrating directly into the development workflow, it helps maintain high-quality user interfaces with automated, pixel-perfect verification.

Use Cases

  • Visual Regression Detection: Automatically identify unintended UI changes, color shifts, or layout breaks when refactoring React components or updating global stylesheets.
  • Theme and Dark Mode Verification: Validate that components render correctly across different visual themes and ensure styling consistency in both light and dark modes.
  • Component State Testing: Capture and compare screenshots of various component states, such as hover, focus, active, and disabled, to ensure interactive elements look correct.
  • Design System QA: Maintain the visual integrity of a shared UI library by running automated screenshot tests whenever core components are modified.
  • Cross-Platform Layout Checks: Verify that complex layouts and alignments remain intact across different viewport sizes and rendering environments.
namecomponent-screenshot-testing
descriptionScreenshot testing for React components with Playwright. Captures component pixels and compares to baselines. Auto-apply when editing React component stories or *.visual.spec.ts files that test UI components.

Component Screenshot Testing Skill

Captures React component screenshots and compares them to baseline PNGs. Tests that UI components render correctly at the pixel level.

This is about component appearance, not data or canvas rendering. It catches:

  • Color/style changes in React components
  • Layout shifts and alignment issues
  • Missing or misplaced UI elements
  • Theme/styling regressions

For canvas-based filmstrip testing (matrix progressions), see canvas-filmstrip-testing.

When to Use This

  • Testing React components (buttons, controls, panels, etc.)
  • UI styling changes
  • Theme/dark mode appearance
  • Component layout verification

Architecture

stories/
  components/                    → Shared React components for stories
    StripViewer.tsx
    ProgressionStrip.tsx
  ui-components/                 → UI component stories (if present)
    Button.visual.spec.ts
    Panel.visual.spec.ts

Commands

# Run visual tests
npm run test:visual:headless        # CI/agents
npm run test:visual:headed          # Debugging with browser UI

# Update baselines after intentional changes
npm run test:visual:update:headless
npm run test:visual:update:headed

# Clear test artifacts
npm run reset:visual                # Clear results/reports only
npm run reset:visual:all            # Clear results + colocated baselines

# Verify stories compile (fast check)
npm run stories:build

Test Structure

// Example: stories/ui-components/Button.visual.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Button Component', () => {
  test('primary button', async ({ page }) => {
    await page.goto('http://localhost:3001/?page=ui-button');

    const button = page.getByTestId('button-primary');
    await expect(button).toHaveScreenshot('button-primary.png');
  });

  test('disabled button', async ({ page }) => {
    await page.goto('http://localhost:3001/?page=ui-button');

    const button = page.getByTestId('button-disabled');
    await expect(button).toHaveScreenshot('button-disabled.png');
  });
});

Best Practices

  1. Target specific elements - Use data-testid to capture just the component
  2. Test states - Hover, focus, disabled, active states
  3. Consistent viewport - Set fixed dimensions to avoid flaky tests
  4. Wait for render - Ensure component is fully rendered before screenshot
// Wait for component to be ready
await page.waitForSelector('[data-testid="my-component"]');
await page.waitForLoadState('networkidle');

// Screenshot just the component
const element = page.getByTestId('my-component');
await expect(element).toHaveScreenshot('my-component.png');

Debugging with Chrome DevTools MCP

When a visual test fails:

// Start dev server
npm run stories

// Open in browser
mcp__chrome-devtools__new_page({ url: "http://localhost:3001/?page=ui-button" })

// Take snapshot to find element UIDs
mcp__chrome-devtools__take_snapshot()

// Screenshot specific element
mcp__chrome-devtools__take_screenshot({ uid: "<element-uid>" })

// After fixing, reload and re-check
mcp__chrome-devtools__navigate_page({ type: "reload" })
  • canvas-filmstrip-testing - For matrix-to-canvas rendered progressions
  • visual-regression - Shared infrastructure and orchestration
  • react-ui - React component development patterns