GitHub Actions visual testing with Playwright

Here's a minimal GitHub Actions workflow for Playwright visual tests:

name: Visual Tests

on:
  pull_request:
    branches: [main]

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

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

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Run visual tests
        run: npx playwright test --project=visual

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

This runs on PRs to main, installs only the browsers you need, and uploads diff artifacts on failure for easy debugging.

GitHub Actions runners are consistent but not identical to your local machine. Control these factors:

For maximum consistency, use a Docker container. See Docker setup for deterministic rendering for container configuration.

Visual tests are slower than unit tests. These techniques keep feedback fast:

Here's how to cache Playwright browsers:

- name: Cache Playwright browsers
  uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

And test sharding across multiple runners:

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      # ... setup steps ...
      - name: Run visual tests
        run: npx playwright test --shard=${{ matrix.shard }}/4

When visual tests fail, reviewers need to see the diffs. Upload screenshots as artifacts and make them accessible from the PR.

- name: Upload diff artifacts
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: visual-diffs-${{ github.run_id }}
    path: |
      test-results/**/*.png
      test-results/**/*-diff.png
    retention-days: 14

For a better experience, use a GitHub Action or bot that comments on PRs with links to the artifacts or embedded diff images.

You have two options for how visual test failures affect PRs:

• Blocking: Visual test failures prevent merging. High confidence, but requires stable tests and an escape hatch for urgent fixes.
• Report-only: Failures are reported but don't block. Lower friction, but visual regressions can slip through if reports are ignored.

Start with report-only while building confidence. Move to blocking once your tests are stable and the team trusts them. Add a PR label like skip-visual-tests for emergency bypasses.

# Report-only: use continue-on-error
- name: Run visual tests
  continue-on-error: true
  run: npx playwright test --project=visual