component-screenshot-testing

name	component-screenshot-testing
description	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.

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" })

Related Skills

• canvas-filmstrip-testing - For matrix-to-canvas rendered progressions
• visual-regression - Shared infrastructure and orchestration
• react-ui - React component development patterns