component-screenshot-testing

surfdeeper's avatarfrom surfdeeper

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 1, 2025
[Testing and QA]

When & Why to Use This Skill

This Claude skill automates visual regression testing for React components using Playwright. It captures high-resolution component screenshots and compares them against established baselines to detect pixel-level discrepancies, ensuring UI consistency across different states, themes, and layouts. By integrating directly into the development workflow, it helps developers catch unintended styling regressions and layout shifts before they reach production.

Use Cases

  • Detecting layout shifts and alignment issues during React component refactoring or library upgrades.
  • Verifying UI consistency across multiple themes, such as ensuring dark mode and light mode render correctly.
  • Automating visual quality checks for design system components like buttons, panels, and navigation controls.
  • Catching unintended CSS regressions that functional tests might miss, such as color changes or misplaced UI elements.
  • Validating component appearance across different states, including hover, focus, disabled, and active interactions.
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