How to Run Visual Snapshot Tests in E2E on GitHub Actions

toHaveScreenshot compares against a committed baseline; baselines must be generated on the same OS CI uses.

Commit Linux baselines (generate them with --update-snapshots on a Linux runner or container), then run the suite; on a diff, upload the report so the actual vs expected images are visible.

Assertion

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

test('home page looks right', async ({ page }) => {
  await page.goto('/')
  await expect(page).toHaveScreenshot('home.png', { maxDiffPixelRatio: 0.01 })
})

Workflow

      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: visual-diff
          path: test-results/

Gotchas

• Font rendering differs across OS, so a macOS baseline fails on a Linux runner; generate baselines on the CI platform.
• Use maxDiffPixelRatio to tolerate tiny antialiasing noise without ignoring real changes.

Related guides