Playwright Cheatsheet

Screenshots, Video, Trace

Use this Playwright reference while you build software engineering projects, review code for technical interview prep, or polish examples for a software engineer resume.

Screenshots

Full page & element

// Full page (viewport only by default)
await page.screenshot({ path: 'page.png' });
await page.screenshot({ path: 'full.png', fullPage: true });

// Element screenshot
await locator.screenshot({ path: 'element.png' });

// As buffer (no file)
const buffer = await page.screenshot();
const base64 = buffer.toString('base64');

Screenshot options

Option	Type	Default	Description
`path`	`string`	—	Save to file (PNG by default)
`fullPage`	`boolean`	`false`	Capture scrollable full page
`clip`	`{ x, y, width, height }`	—	Crop to rectangle
`omitBackground`	`boolean`	`false`	Transparent BG (PNG only)
`type`	`'png' \| 'jpeg'`	`'png'`	Format
`quality`	`number`	—	JPEG quality 0–100
`scale`	`'css' \| 'device'`	`'device'`	Use CSS pixels or device pixels
`animations`	`'disabled' \| 'allow'`	`'disabled'`	Stop CSS/JS animations
`caret`	`'hide' \| 'initial'`	`'hide'`	Text cursor visibility
`timeout`	`number`	`30000`	Max wait for element
`mask`	`Locator[]`	—	Mask locators with a colored box
`maskColor`	`string`	`'#FF00FF'`	Mask fill color

await page.screenshot({
  path: 'masked.png',
  mask: [page.locator('.user-email'), page.locator('.user-name')],
  maskColor: '#000000',
  fullPage: true,
});

Visual regression (screenshot assertions)

// Stored in __snapshots__ dir; fails if pixel diff exceeds threshold
await expect(page).toHaveScreenshot('home.png');
await expect(locator).toHaveScreenshot('button.png');

// Options
await expect(page).toHaveScreenshot('page.png', {
  maxDiffPixels: 100,       // absolute pixel count
  maxDiffPixelRatio: 0.01,  // fraction 0–1
  threshold: 0.2,           // per-pixel color diff 0–1
  fullPage: true,
  animations: 'disabled',
  mask: [page.locator('.ad')],
});

Update stored snapshots:

npx playwright test --update-snapshots

Video recording

// playwright.config.ts
export default defineConfig({
  use: {
    // 'on' (always record) | 'off' | 'retain-on-failure' (recommended)
    // | 'on-first-retry' (record only on retry)
    video: 'retain-on-failure',
  },
});

// Per-context
const context = await browser.newContext({
  recordVideo: {
    dir: 'videos/',
    size: { width: 1280, height: 720 },
  },
});

// Save video after context closes
await context.close();
const path = await page.video()?.path();

Video options

Option	Default	Description
`dir`	(required)	Directory to save videos
`size`	viewport size	Resolution of recording

Getting the video path in tests

test('record example', async ({ page }, testInfo) => {
  await page.goto('https://example.com');
  // video saved automatically to testInfo.outputDir
  const videoPath = await page.video()?.path();
  await testInfo.attach('video', { path: videoPath!, contentType: 'video/webm' });
});

Trace viewer

Traces capture a full timeline: actions, network, console, snapshots.

Enabling traces

// playwright.config.ts
export default defineConfig({
  use: {
    // 'on' (always) | 'off' | 'retain-on-failure' (recommended for CI)
    // | 'on-first-retry' | 'on-all-retries'
    trace: 'retain-on-failure',
  },
});

Trace options (fine-grained)

export default defineConfig({
  use: {
    trace: {
      mode: 'retain-on-failure',
      snapshots: true,            // DOM snapshots per action
      screenshots: true,          // screenshots in timeline
      sources: true,              // attach source files
      attachments: true,          // include test attachments
    },
  },
});

Manual trace control

test('trace manually', async ({ context, page }) => {
  await context.tracing.start({ screenshots: true, snapshots: true });

  await page.goto('/');
  await page.locator('button').click();

  await context.tracing.stop({ path: 'trace.zip' });
});

// Chunked traces (within a started trace)
await context.tracing.startChunk({ title: 'login' });
// ... actions
await context.tracing.stopChunk({ path: 'login-trace.zip' });

Viewing a trace

npx playwright show-trace trace.zip        # local viewer
npx playwright show-trace --port 9323 trace.zip

Or upload to trace.playwright.dev (offline, browser-only).

What the trace contains

Timeline — every action with start/end time
Action detail — selector, call args, log
Before/after DOM snapshots — interactive replay
Network tab — all requests with headers & body
Console tab — console.log / error output
Source tab — your test source with highlighted line

HTML report with attachments

npx playwright test --reporter=html    # generate
npx playwright show-report             # open

// Auto-open after run
export default defineConfig({
  reporter: [['html', { open: 'on-failure' }]],
});

Multiple reporters

export default defineConfig({
  reporter: [
    ['list'],                                      // stdout
    ['html', { outputFolder: 'playwright-report' }],
    ['junit', { outputFile: 'results.xml' }],      // CI integration
    ['json', { outputFile: 'results.json' }],
  ],
});