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.
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.
| 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
- Target specific elements - Use
data-testidto capture just the component - Test states - Hover, focus, disabled, active states
- Consistent viewport - Set fixed dimensions to avoid flaky tests
- 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