Visual Comparisons
Playwright · Reference cheat sheet
Visual Comparisons
Playwright · Reference cheat sheet
📋 Overview
toHaveScreenshot and toMatchSnapshot compare pixels/text against committed baselines. Stabilize fonts, animations, and dynamic data before trusting diffs.
🔧 Core concepts
| API | Use |
|---|---|
expect(page).toHaveScreenshot() | Full page / viewport |
expect(locator).toHaveScreenshot() | Element |
maxDiffPixels / maxDiffPixelRatio | Tolerance |
stylePath | Inject CSS for stability |
| Update flag | --update-snapshots |
Baselines are platform-specific (OS + browser). Generate on the same CI image you run.
💡 Examples
Page screenshot assert:
await expect(page).toHaveScreenshot('home.png', {
animations: 'disabled',
caret: 'hide',
maxDiffPixelRatio: 0.01,
});Element + mask:
await expect(page.getByTestId('hero')).toHaveScreenshot({
mask: [page.getByTestId('clock'), page.getByTestId('avatar')],
});Config defaults:
expect: {
toHaveScreenshot: {
maxDiffPixels: 50,
animations: 'disabled',
},
},Update baselines:
npx playwright test --update-snapshots
npx playwright test --update-snapshots --project=chromiumText snapshot:
expect(await page.locator('pre').textContent()).toMatchSnapshot('dump.txt');⚠️ Pitfalls
- Generating snapshots on Windows and comparing on Linux CI.
- Unmasked timestamps, ads, or lazy-loaded images.
- Fonts not installed in CI → different glyph metrics.
- Animations/caret blinking causing 1-pixel flakes.
- Committing huge full-site screenshots without masking.