How do you capture a screenshot in Playwright?
Call await page.screenshot({ path: 'home.png' }). That saves what is visible in the viewport as a PNG. Add fullPage: true for the whole scrollable page, or call screenshot() on a locator to capture one element. The rest of this answer covers the options you actually use in a test suite: automatic screenshots on failure and visual comparison.
Three kinds of screenshot
// tests/screenshots.spec.ts
import { test } from '@playwright/test';
test('capture the fees page', async ({ page }, testInfo) => {
await page.goto('/fees');
// 1. what the viewport shows
await page.screenshot({ path: 'screenshots/fees-viewport.png' });
// 2. the full scrollable page
await page.screenshot({ path: 'screenshots/fees-full.png', fullPage: true });
// 3. one element only
await page.getByRole('table').screenshot({ path: 'screenshots/fees-table.png' });
// attach to the HTML report instead of (or as well as) saving a file
const png = await page.screenshot();
await testInfo.attach('fees page', { body: png, contentType: 'image/png' });
});
screenshot() returns the image as a Buffer whether or not you pass a path, so you can attach it to the report or send it elsewhere. On a 390-pixel-wide viewport, a long page with fullPage: true comes back 390 pixels wide and as tall as the content.
Useful options
type: 'jpeg'withquality: 80for smaller files.clip: { x, y, width, height }to capture a fixed rectangle.mask: [locator]to paint over changing content such as dates, OTP timers or ads.animations: 'disabled'to stop CSS animations so the picture is stable.omitBackground: truefor a transparent background (PNG only).
Screenshots on failure, automatically
You do not have to add screenshot calls to every test. Set the screenshot option in the config and the runner takes one at the end of each test:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
screenshot: 'only-on-failure', // 'off' | 'on' | 'only-on-failure' | 'on-first-failure'
},
});
The images land in test-results/ and appear in the HTML report (npx playwright show-report). For a full picture of a failure, a trace is even better because it holds a screenshot of every step; see tracing in Playwright. Video is covered in capturing videos during test execution.
Visual comparison with toHaveScreenshot
A plain screenshot is only a picture. expect(page).toHaveScreenshot() compares the page with a saved baseline image and fails if they differ:
import { test, expect } from '@playwright/test';
test('fees page looks right', async ({ page }) => {
await page.goto('/fees');
await expect(page).toHaveScreenshot('fees.png', {
mask: [page.getByTestId('last-updated')],
maxDiffPixels: 100,
});
});
What to expect when you run it:
- The first run fails on purpose, because no baseline exists yet. Playwright writes the baseline into a folder next to the test, such as
screenshots.spec.ts-snapshots/. - The file name includes the browser and the operating system, for example
fees-chromium-win32.png. A baseline made on Windows is not used on a Linux CI runner, because fonts render differently. - When the design changes on purpose, refresh baselines with
npx playwright test --update-snapshots.
To avoid the Windows versus Linux mismatch, many teams create baselines inside the official Playwright Docker image so they match CI.
Common problems
- Blank or half-loaded screenshot. The page had not finished rendering. Wait for a visible element with
await expect(locator).toBeVisible()first, not a fixed timeout. - Flaky visual tests. Mask dynamic areas, disable animations and fix the viewport and locale in the config.
- Screenshot of a headless run looks different from what you see. Check the viewport and device settings; see viewports in Playwright.
Want to master Playwright hands-on?
Join Uncodemy's Playwright Automation Testing Course in Noida — Dedicated Placement Support.
Explore the Course →