{
    "slug": "visual_regression_testing",
    "term": "Visual Regression Testing",
    "category": "testing",
    "difficulty": "intermediate",
    "short": "Automatically comparing screenshots of UI components or pages to a baseline — catching unintended visual changes that functional tests miss.",
    "long": "Visual regression testing captures screenshots at a pixel or component level and diffs them against approved baselines. Tools: Percy (cloud, integrates with Playwright/Cypress), Chromatic (Storybook integration), BackstopJS (self-hosted), and Playwright's built-in toHaveScreenshot(). Pixel-perfect diffing has high false-positive rates from font rendering and anti-aliasing — threshold-based diffing ignores minor differences. Component-level visual testing (Storybook + Chromatic) is more reliable than full-page screenshot comparison.",
    "aliases": [
        "screenshot testing",
        "Percy",
        "Chromatic",
        "visual diff"
    ],
    "tags": [
        "testing",
        "frontend",
        "qa"
    ],
    "misconception": "Unit tests of CSS/HTML are equivalent to visual tests — a CSS change can pass all unit tests while completely breaking the visual layout; only a screenshot comparison catches visual regressions.",
    "why_it_matters": "A refactored CSS file that passes all functional tests but moves every button 20px to the right is caught immediately by visual regression testing — without it, the regression reaches production.",
    "common_mistakes": [
        "Pixel-perfect comparison without threshold — minor rendering differences create constant false failures.",
        "Not updating baselines when intentional changes are made — approved changes are rejected as regressions.",
        "Running visual tests against dynamic content — timestamps, user avatars, ads cause spurious failures.",
        "Full-page screenshots for complex pages — component-level testing is more maintainable."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "end_to_end_testing",
        "regression_testing",
        "snapshot_testing"
    ],
    "prerequisites": [
        "end_to_end_testing",
        "snapshot_testing",
        "continuous_integration"
    ],
    "refs": [
        "https://playwright.dev/docs/screenshots"
    ],
    "bad_code": "// No visual tests — layout regressions reach production:\n// CSS refactor: all tests pass\n// Production: every dropdown is 30px off\n// Discovered by: customer support ticket 3 days later\n// Cost: 3 days * affected users",
    "good_code": "// Playwright visual regression:\nimport { test, expect } from '@playwright/test';\n\ntest('checkout button renders correctly', async ({ page }) => {\n    await page.goto('/checkout');\n    await expect(page.locator('.checkout-btn')).toHaveScreenshot(\n        'checkout-button.png',\n        { threshold: 0.1 } // Allow 10% pixel difference\n    );\n});\n// First run: creates baseline screenshot\n// Subsequent runs: diffs against baseline\n// CSS regression: test fails with visual diff image",
    "quick_fix": "Use Playwright's screenshot comparison or Percy/Chromatic for visual regression testing — run on PR to catch unintended CSS changes before they reach production",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/visual_regression_testing",
        "html_url": "https://codeclaritylab.com/glossary/visual_regression_testing",
        "json_url": "https://codeclaritylab.com/glossary/visual_regression_testing.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Visual Regression Testing](https://codeclaritylab.com/glossary/visual_regression_testing) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/visual_regression_testing"
            }
        }
    }
}