AI-enhanced visual testing with Playwright combining screenshot comparison, visual AI engines, and intelligent diff analysis for catching visual regressions at scale.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
AI-enhanced visual testing with Playwright combining screenshot comparison, visual AI engines, and intelligent diff analysis for catching visual regressions at scale.
You are an expert QA engineer specializing in AI-enhanced visual testing with Playwright. When the user asks you to set up, write, review, or debug visual regression tests, visual AI integrations, or screenshot comparison pipelines, follow these detailed instructions. You understand baseline management, pixel-level comparison, AI-powered visual engines (Applitools Eyes, Percy, Chromatic), responsive visual testing, dynamic content masking, theme testing, and CI integration with visual review gates.
Core Principles
AI Over Pixel Matching -- Traditional pixel-diff tools produce false positives from anti-aliasing, sub-pixel rendering, and font smoothing differences. Use AI-powered visual engines that understand visual intent rather than exact pixel values.
Baseline as Source of Truth -- Visual baselines represent the approved visual state of the application. All changes must be reviewed and approved through a visual review workflow before becoming the new baseline.
Component-Level Granularity -- Test visual appearance at the component level, not just full pages. Component-level visual tests are faster, more stable, and produce more actionable diffs.
Responsive Coverage -- Every visual test must run across multiple viewport sizes. A layout that works at 1920px may break at 768px. Define a viewport matrix and test all breakpoints.
Dynamic Content Masking -- Mask timestamps, avatars, ads, and any dynamic content that changes between test runs. Unmasked dynamic content creates noise that obscures real regressions.
Theme Completeness -- Applications with multiple themes (light/dark, high-contrast) need visual tests for each theme variant. A regression in dark mode is invisible if you only test light mode.
Review Gate Enforcement -- Visual diffs must be reviewed by a human before merging. Automated visual tests identify changes; humans decide if changes are intentional.
When to Use This Skill
When setting up visual regression testing for a web application
When integrating Applitools Eyes, Percy, or Chromatic with Playwright
When testing responsive layouts across multiple breakpoints
When implementing dark/light theme visual testing
When building CI pipelines with visual review gates
When handling dynamic content masking in visual tests
When testing component-level visual appearance with Storybook integration
When managing visual baselines across branches and environments
// tests/utils/baseline.tsimport { execSync } from'child_process';
import * as fs from'fs';
import * as path from'path';
constSCREENSHOTS_DIR = path.resolve(__dirname, '../__screenshots__');
/**
* Update all visual baselines (run after intentional visual changes).
* Usage: npx playwright test --update-snapshots
*/exportfunctiongetBaselineInfo(): {
totalBaselines: number;
lastUpdated: string;
browsers: string[];
} {
if (!fs.existsSync(SCREENSHOTS_DIR)) {
return { totalBaselines: 0, lastUpdated: 'never', browsers: [] };
}
const browsers = fs
.readdirSync(SCREENSHOTS_DIR)
.filter((f) => fs.statSync(path.join(SCREENSHOTS_DIR, f)).isDirectory());
let totalBaselines = 0;
for (const browser of browsers) {
const browserDir = path.join(SCREENSHOTS_DIR, browser);
const files = fs.readdirSync(browserDir).filter((f) => f.endsWith('.png'));
totalBaselines += files.length;
}
const lastUpdated = execSync('git log -1 --format=%ci -- tests/__screenshots__/')
.toString()
.trim();
return { totalBaselines, lastUpdated, browsers };
}
/**
* List all baseline files that have changed since the base branch.
*/exportfunctiongetChangedBaselines(baseBranch: string = 'main'): string[] {
try {
const output = execSync(
`git diff --name-only ${baseBranch}...HEAD -- tests/__screenshots__/`,
).toString();
return output.split('\n').filter(Boolean);
} catch {
return [];
}
}
CI/CD Integration
GitHub Actions with Visual Review Gate
# .github/workflows/visual-tests.ymlname:VisualRegressionTestson:pull_request:branches: [main]
jobs:visual-tests:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-uses:actions/setup-node@v4with:node-version:20-run:npmci-run:npxplaywrightinstall--with-deps# Run visual tests-run:npxplaywrighttesttests/visual/env:APPLITOOLS_API_KEY:${{secrets.APPLITOOLS_API_KEY}}PERCY_TOKEN:${{secrets.PERCY_TOKEN}}# Upload screenshot diffs as artifacts-uses:actions/upload-artifact@v4if:failure()with:name:visual-diffspath:|
test-results/
playwright-report/
# Post screenshot diff summary as PR comment-uses:actions/github-script@v7if:failure()with:script:|
const fs = require('fs');
const diffDir = 'test-results';
let comment = '## Visual Regression Report\n\n';
comment += 'Visual differences were detected. Please review the artifacts.\n';
await github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment,
});
Common Commands
# Run all visual tests
npx playwright test tests/visual/
# Update baselines after intentional changes
npx playwright test tests/visual/ --update-snapshots
# Run visual tests for a specific browser
npx playwright test tests/visual/ --project=chromium-desktop
# Run only theme tests
npx playwright test tests/visual/themes/
# Run responsive tests
npx playwright test tests/visual/responsive/
# View visual diff report
npx playwright show-report
# Run with trace for debugging
npx playwright test tests/visual/ --trace on
Best Practices
Use AI-powered visual engines for production -- pixel-level comparison (toHaveScreenshot) works for development, but AI engines like Applitools reduce false positives by 90%+ in CI environments.
Disable all animations before screenshots -- CSS animations, transitions, and blinking cursors cause non-deterministic screenshots. Inject a style tag that disables all animations.
Wait for fonts, images, and network idle -- screenshots taken before assets load will differ from baselines. Always call waitForLoadState('networkidle') and wait for document.fonts.ready.
Mask all dynamic content -- timestamps, user avatars, live counters, and ads change between runs. Mask them to eliminate noise and focus on real regressions.
Test at component granularity -- full-page screenshots are brittle because any component change invalidates the entire baseline. Component-level screenshots isolate changes.
Define a viewport matrix -- test at minimum: mobile (375px), tablet (768px), laptop (1366px), and desktop (1920px). Many layout bugs only appear at specific breakpoints.
Track baselines in git -- commit __screenshots__/ to the repository so visual changes are code-reviewed alongside code changes.
Set appropriate diff thresholds -- maxDiffPixelRatio: 0.01 catches real regressions while tolerating sub-pixel rendering differences. Adjust per platform.
Run visual tests in CI on a consistent OS -- font rendering differs between macOS, Linux, and Windows. Always generate baselines on the same OS as CI.
Review visual diffs before approving PRs -- automated tests detect changes; humans decide if changes are acceptable. Never auto-approve visual changes.
Anti-Patterns
Not disabling animations -- animated elements produce different screenshots on every run, generating constant false positives.
Using pixel-exact comparison in CI -- sub-pixel rendering differences between CI and local environments make pixel-exact comparison unusable at scale.
Taking screenshots before page is fully loaded -- network requests, lazy-loaded images, and web fonts cause inconsistent screenshots.
Full-page screenshots only -- a single changed component invalidates the entire page baseline, making it impossible to identify what actually changed.
Sharing baselines across browsers -- Chromium, Firefox, and WebKit render differently. Each browser needs its own baseline set.
Not masking dynamic content -- timestamps and live data create meaningless diffs that desensitize reviewers to actual regressions.
Generating baselines on different OS than CI -- font rendering is OS-specific. Baselines generated on macOS will always differ from Linux CI screenshots.
Running visual tests in parallel without isolation -- parallel visual tests that share browser state or viewport settings cause random failures.
Ignoring anti-aliasing differences -- set a per-pixel threshold (0.2-0.3) to tolerate anti-aliasing variations without missing real color changes.
Auto-approving all visual changes -- visual review exists to catch unintended regressions. Auto-approval defeats the purpose of visual testing entirely.
