Screenshots and Videos

Playwright captures screenshots and videos on failure by default (when configured) and supports manual screenshots anytime for docs or visual baselines.

Automatic Capture

Config: screenshot: 'only-on-failure', video: 'retain-on-failure'. Attachments appear in HTML report and test-results folder.

Manual: await page.screenshot({ path: 'shot.png', fullPage: true }).

use: {
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
}

await page.screenshot({ path: 'artifacts/dashboard.png', fullPage: true });

Videos are per-context — enable in config use block.

Screenshot Options

page.screenshot({ path, fullPage, clip, mask: [locator] })
locator.screenshot({ path })

mask hides dynamic elements in screenshots.
fullPage captures scrollable content.
clip crops to region — faster visual tests.
Videos stored as .webm in test-results.

Media Capture Reference

Config and API.

Option	Value
screenshot mode	'off' \| 'on' \| 'only-on-failure'
video mode	'off' \| 'on' \| 'retain-on-failure'
Full page	`fullPage: true`
Mask locator	`mask: [page.getByText('clock')]`
Manual path	`test-results/` or custom dir
Attach to report	Automatic with config modes

Masking Dynamic Content

await expect(page).toHaveScreenshot('page.png', {
  mask: [page.locator('.timestamp'), page.getByTestId('avatar')],
});

Managing Video Artifact Size

Full suite video on every test fills disk quickly. Restrict to retain-on-failure and set CI artifact retention policies.

Common Mistakes

video: 'on' for all tests — large CI artifacts.
Not uploading screenshots/videos from CI on failure.
Full page screenshots with infinite scroll — huge files.
Comparing screenshots across OS without tolerance settings.

Key Takeaways

Configure screenshot/video for failure diagnostics.
Manual screenshots useful for docs and debugging.
Mask dynamic regions in visual comparisons.
Upload media artifacts from CI on failure.

Pro Tip

Prefer trace over video for debug — traces include screenshots per step with DOM; video alone is harder to scrub.