Skip to content

Screenshot APIs

When to Use

Use toHaveScreenshot() for all VR work. Use page.screenshot() only when you need a raw buffer for non-test purposes. Use toMatchSnapshot() only when you already have a buffer and need to diff it.

Decision

API Type Auto-retry stability Baseline diffing Use for
expect(page).toHaveScreenshot() Assertion Yes — waits for two consecutive matching frames Yes (pixelmatch) Primary VR API
expect(buffer).toMatchSnapshot() Assertion No Yes for images Generic snapshot; buffer already captured
page.screenshot() Action No No Raw capture; returns Buffer or writes file

Pattern

Minimal VR test

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

test('homepage', async ({ page }) => {
  await page.goto('https://playwright.dev');
  await expect(page).toHaveScreenshot();
});

Element-level (preferred for components)

await expect(page.locator('.header')).toHaveScreenshot('header.png');

Common Mistakes

  • Wrong: Using page.screenshot() for VR → Right: it produces a file but does no comparison; the test always passes
  • Wrong: Using toMatchSnapshot() on a buffer when you wanted toHaveScreenshot() → Right: you lose the auto-retry stability check
  • Wrong: Inconsistent naming — toHaveScreenshot('thing') vs toHaveScreenshot('Thing.png') → Right: name consistently; casing produces different baseline filenames

See Also