Skip to main content
skill CX Codex

playwright-visual-testing · bradtaylorsf — Claude Code skill: how to install

playwright-visual-testing — a skill providing Playwright visual regression testing patterns. Helps agents configure screenshot assertions, mask dynamic elements, and handle responsive snapshots in CI.

MIT 1 installs ★ 8 updated 2026-02-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bradtaylorsf/alphaagent-team --skill playwright-visual-testing -a claude-code
Open on GitHub

What playwright-visual-testing does

This skill equips coding agents with patterns for Playwright visual regression testing using @playwright/test. It outlines expect(page).toHaveScreenshot() assertions alongside comparison options such as maxDiffPixels, color thresholds, and clipping masks. It also details techniques for flaky interfaces: masking locators with mask, replacing dynamic timestamps in the DOM, and disabling CSS animations via addStyleTag.

Responsive coverage includes iterating over viewport arrays and separating device profiles in playwright.config.ts. The instructions cover dark mode emulation with page.emulateMedia, button interaction states (hover, focus, disabled), and a sample GitHub Actions workflow that uploads test artifacts on failure.

The frontmatter sets user-invocable: false, meaning the agent consults this guide contextually rather than through a direct slash command. Running these suites still requires @playwright/test and browser binaries installed locally.

What it helps with

  • configure full-page and element screenshot comparisons in Playwright
  • mask dynamic timestamps or avatars during regression runs
  • disable CSS animations to eliminate flaky visual test diffs
  • test dark and light color schemes across viewports
  • set up cross-platform snapshotPathTemplate rules in config

Example prompts for the agent

  • Write a Playwright visual regression test for /dashboard with dynamic timestamps masked
  • Update playwright.config.ts to disable animations and configure multi-platform snapshot paths
  • Create component visual tests verifying hover, focus, and disabled button states

How to install playwright-visual-testing

1Skills CLI (Vercel)

npx skills add bradtaylorsf/alphaagent-team --skill playwright-visual-testing -a claude-code

2Manually: put the files in place

~/.claude/skills/playwright-visual-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/playwright-visual-testing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about playwright-visual-testing

How to install playwright-visual-testing in Claude Code?

Run npx skills add bradtaylorsf/alphaagent-team --skill playwright-visual-testing -a claude-code in your terminal.

What does playwright-visual-testing do?

It gives coding agents standard patterns for Playwright visual regression: screenshot assertions, dynamic content masking, animation suppression, and CI configuration.

Can you run this skill directly via a slash command?

No, it specifies user-invocable: false in its frontmatter. Your agent references its rules automatically when you request visual testing code or snapshot configurations.

Source text

SKILL.md · MIT
---
name: playwright-visual-testing
description: Playwright visual comparison and screenshot testing
user-invocable: false
---

# Playwright Visual Testing Skill

Patterns for visual regression testing with Playwright.

## Screenshot Assertions

### Basic Screenshot Comparison

```typescript
import { test, expect } from '@playwright/test'

test('visual comparison', async ({ page }) => {
  await page.goto('/')

  // Compare full page
  await expect(page).toHaveScreenshot()

  // With custom name
  await expect(page).toHaveScreenshot('homepage.png')
})

// Element screenshot
test('component visual test', async ({ page }) => {
  await page.goto('/components')

  const card = page.locator('.card').first()
  await expect(card).toHaveScreenshot('card-component.png')
})
```

### Screenshot Options

```typescript
await expect(page).toHaveScreenshot('name.png', {
  // Comparison options
  maxDiffPixels: 100,           // Allow N different pixels
  maxDiffPixelRatio: 0.05,      // Allow 5% difference
  threshold: 0.2,                // Color difference threshold (0-1)

  // Capture options
  fullPage: true,                // Capture entire scrollable page
  clip: { x: 0, y: 0, width: 800, height: 600 },
  scale: 'css',                  // 'css' or 'device'
  animations: 'disabled',        // Disable animations
  mask: [page.locator('.dynamic')],  // Mask dynamic content
  maskColor: '#FF00FF',          // Mask overlay color
})
```

### Updating Snapshots

```bash
# Update all snapshots
npx playwright test --update-snapshots

# Update specific test
npx playwright test visual.spec.ts --update-snapshots
```

## Handling Dynamic Content

### Masking Elements

```typescript
test('mask dynamic content', async ({ page }) => {
  await page.goto('/dashboard')

  await expect(page).toHaveScreenshot('dashboard.png', {
    mask: [
      page.locator('.timestamp'),
      page.locator('.user-avatar'),
      page.locator('.random-ad'),
    ],
  })
})
```

### Waiting for Stability

```typescript
test('wait for animations', async ({ page }) => {
  await page.goto('/animated-page')

  // Wait for animations to complete
  await page.waitForTimeout(500)

  // Or wait for specific state
  await page.locator('.loading').waitFor({ state: 'hidden' })

  await expect(page).toHaveScreenshot()
})
```

### Disabling Animations

```typescript
// playwright.config.ts
export default defineConfig({
  use: {
    // Disable CSS animations and transitions
    // JS animations need manual handling
  },
})

// In test
test('no animations', async ({ page }) => {
  await page.goto('/')

  // Add CSS to disable animations
  await page.addStyleTag({
    content: `
      *, *::before, *::after {
        animation-duration: 0s !important;
        animation-delay: 0s !important;
        transition-duration: 0s !important;
        transition-delay: 0s !important;
      }
    `,
  })

  await expect(page).toHaveScreenshot()
})
```

### Replacing Dynamic Content

```typescript
test('replace dynamic dates', async ({ page }) => {
  await page.goto('/orders')

  // Replace dynamic dates with static text
  await page.evaluate(() => {
    document.querySelectorAll('.date').forEach(el => {
      el.textContent = 'FIXED_DATE'
    })
  })

  await expect(page).toHaveScreenshot()
})
```

## Responsive Testing

### Multiple Viewports

```typescript
const viewports = [
  { name: 'mobile', width: 375, height: 667 },
  { name: 'tablet', width: 768, height: 1024 },
  { name: 'desktop', width: 1280, height: 720 },
]

for (const viewport of viewports) {
  test(`homepage - ${viewport.name}`, async ({ page }) => {
    await page.setViewportSize(viewport)
    await page.goto('/')

    await expect(page).toHaveScreenshot(`homepage-${viewport.name}.png`)
  })
}
```

### Using Projects

```typescript
// playwright.config.ts
export default defineConfig({
  projects: [
    {
      name: 'desktop-chrome',
      use: {
        ...devices['Desktop Chrome'],
        viewport: { width: 1280, height: 720 },
      },
    },
    {
      name: 'mobile-safari',
      use: {
        ...devices['iPhone 13'],
      },
    },
    {
      name: 'tablet-portrait',
      use: {
        ...devices['iPad Pro 11'],
      },
    },
  ],
})
```

## Theming and States

### Dark Mode

```typescript
test('dark mode', async ({ page }) => {
  await page.emulateMedia({ colorScheme: 'dark' })
  await page.goto('/')

  await expect(page).toHaveScreenshot('homepage-dark.png')
})

test('light mode', async ({ page }) => {
  await page.emulateMedia({ colorScheme: 'light' })
  await page.goto('/')

  await expect(page).toHaveScreenshot('homepage-light.png')
})
```

### Component States

```typescript
test('button states', async ({ page }) => {
  await page.goto('/components/button')

  const button = page.getByRole('button', { name: 'Submit' })

  // Default state
  await expect(button).toHaveScreenshot('button-default.png')

  // Hover state
  await button.hover()
  await expect(button).toHaveScreenshot('button-hover.png')

  // Focus state
  await button.focus()
  await expect(button).toHaveScreenshot('button-focus.png')

  // Disabled state
  await page.evaluate(() => {
    (document.querySelector('button') as HTMLButtonElement).disabled = true
  })
  await expect(button).toHaveScreenshot('button-disabled.png')
})
```

## Configuration

### Global Config

```typescript
// playwright.config.ts
export default defineConfig({
  expect: {
    toHaveScreenshot: {
      // Default comparison options
      maxDiffPixels: 50,
      threshold: 0.3,
      animations: 'disabled',
    },
    toMatchSnapshot: {
      maxDiffPixelRatio: 0.05,
    },
  },

  // Snapshot directory
  snapshotDir: './screenshots',

  // Platform-specific snapshots
  snapshotPathTemplate: '{testDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{ext}',
})
```

### Platform Handling

```typescript
// Separate snapshots per platform
// playwright.config.ts
export default defineConfig({
  snapshotPathTemplate: '{testDir}/__snapshots__/{testFileName}/{arg}-{projectName}-{platform}{ext}',
})

// Or ignore platform differences
test('cross-platform visual', async ({ page }) => {
  await page.goto('/')

  await expect(page).toHaveScreenshot('homepage.png', {
    maxDiffPixelRatio: 0.1,  // Allow platform font differences
  })
})
```

## CI Integration

### GitHub Actions

```yaml
# .github/workflows/visual.yml
name: Visual Tests

on: [push, pull_request]

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npx playwright install --with-deps

      - run: npx playwright test

      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: visual-test-results
          path: test-results/
          retention-days: 7
```

### Updating in CI

```bash
# Update snapshots in CI (usually PR)
npx playwright test --update-snapshots

# Commit updated snapshots
git add **/*.png
git commit -m "Update visual snapshots"
```

## Best Practices

### Stable Screenshots

```typescript
test('stable visual test', async ({ page }) => {
  // 1. Use consistent viewport
  await page.setViewportSize({ width: 1280, height: 720 })

  // 2. Load page and wait
  await page.goto('/', { waitUntil: 'networkidle' })

  // 3. Wait for fonts to load
  await page.waitForFunction(() => document.fonts.ready)

  // 4. Disable animations
  await page.addStyleTag({
    content: '* { animation: none !important; transition: none !important; }'
  })

  // 5. Mask dynamic content
  await expect(page).toHaveScreenshot('page.png', {
    mask: [page.locator('.timestamp'), page.locator('.ad')],
  })
})
```

### Organizing Snapshots

```
tests/
├── visual/
│   ├── homepage.spec.ts
│   ├── dashboard.spec.ts
│   └── components.spec.ts
├── __snapshots__/
│   ├── homepage.spec.ts-snapshots/
│   │   ├── homepage-desktop-chromium.png
│   │   └── homepage-mobile-webkit.png
│   └── components.spec.ts-snapshots/
│       ├── button-default.png
│       └── button-hover.png
```

## Integration

Used by:
- `frontend-developer` agent
- `fullstack-developer` agent

© bradtaylorsf · MIT · bradtaylorsf/alphaagent-team

Similar skills

All skills for Testing and QA →

playwright-visual-testing by other authors comes first.

playwright-visual-testing manutej playwright-visual-testing is a Claude Code skill that uses Playwright MCP to inspect pages, capture screenshots, and test user flows and responsive layouts. CX Codex +1 1,400installs playwright secondsky A Playwright skill for browser automation and end-to-end testing. It finds your running dev server and writes the test script for the task. CX Codex +1 1,100installs playwright-screenshot-inspector curiositech playwright-screenshot-inspector — a skill for visual UI testing: runs Playwright in headless mode, captures screenshots, and analyzes them through a multimodal model. CX Codex +1 262installs playwright-e2e-testing-cursorrules-prompt-file PatrickJS playwright-e2e-testing-cursorrules-prompt-file — a Cursor rule that turns the agent into a QA engineer for Playwright and TypeScript, writing a 3–5 test file from a feature description. CX Codex +1 ★ 41,178repo stars setup-visual-testing davila7 setup-visual-testing — a slash command that wires up visual regression testing: component and page snapshots, responsive breakpoints, accessibility checks. CX Codex +1 300installs visual-testing kindlmann visual-testing — a skill for visual regression testing: it compares screenshots against approved baselines and flags pixel-level differences that functional tests miss. CX Codex +1 1,500installs visual-regression-testing aj-geddes visual-regression-testing catches unintended UI changes by capturing screenshots of pages and components and comparing them across versions. CX Codex +1 741installs

From the same set2

Project sponsors

Companies that keep this analytics open