How to Run Visual Regression Tests with GitHub Actions

Playwright toHaveScreenshot compares rendered pixels to a committed baseline and fails the job on a visual diff.

Use Playwright's toHaveScreenshot assertion to capture and compare screenshots against committed baselines. On a diff, the test fails; upload the report so reviewers can see the before and after.

Steps

• Commit baseline snapshots generated on a Linux runner to match CI rendering.
• Run npx playwright test so toHaveScreenshot assertions compare against them.
• Upload the report with if: always() to inspect any diffs.

Workflow

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --grep @visual
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

Gotchas

• Font and rendering differ across OSes; generate baselines on the same runner OS you test on.
• Update baselines with --update-snapshots only after a reviewed, intentional UI change.

Related guides