playwright-snapshot-saver

playwright-snapshot-saver

Capture Playwright page snapshots (sanitized HTML, screenshots, metadata) into the Page Mirror v2 bundle format consumed by the Page Mirror IntelliJ plugin.

This package is a thin Playwright adapter on top of @pagemirror/snapshot-core, which owns the actual HTML assembly, manifest building, and trace rendering. Selenium / Cypress / Appium adapters are planned and will produce the same on-disk format.

Installation

npm install playwright-snapshot-saver

Usage

Three ways to capture snapshots, from simplest to most flexible.

1. Marker + reporter (recommended)

Mark snapshot points in your tests with snapshot(), then let the reporter extract them from Playwright traces after the run finishes.

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'on', // required — the reporter reads trace ZIPs
  },
  reporter: [
    ['html'],
    ['playwright-snapshot-saver/reporter', { outputDir: '.snapshots' }],
  ],
});

tests/login.spec.ts

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

test('login page', async ({ page }) => {
  await page.goto('/login');
  await snapshot({ page: 'login', state: 'initial' });

  await page.fill('#email', 'bad');
  await page.click('button[type="submit"]');
  await snapshot({ page: 'login', state: 'error' });
});

After npx playwright test, the reporter extracts:

.snapshots/
  login/
    initial/  { index.html, manifest.json, resources/… }
    error/    { index.html, manifest.json, resources/… }

Reporter options

Option	Default	Description
outputDir	'.snapshots'	Base directory for extracted bundles
screenshot	false	Extract a screencast frame as resources/screenshot.webp. Off by default since trace screencast frames are low-fidelity and frequently blank.
manifest	true	Generate manifest.json

Changed in 0.6.0: screenshot extraction is opt-in. Pass screenshot: true to re-enable it.

2. Direct API (saveSnapshot)

Call saveSnapshot() with a live Playwright Page to capture a snapshot immediately during test execution. This path uses Playwright's real page.screenshot(), so screenshots are always sharp.

import { test } from '@playwright/test';
import { saveSnapshot } from 'playwright-snapshot-saver';

test('capture snapshot', async ({ page }) => {
  await page.goto('https://example.com');

  const result = await saveSnapshot(page, {
    outputDir: '.snapshots',
    name: 'initial',
    group: 'example',                     // optional parent directory
    screenshot: { fullPage: true },       // or `false` to skip, or omit for defaults
    manifest: true,
  });

  console.log(result.outputDir);         // .snapshots/example/initial
  console.log(result.files.html);         // .snapshots/example/initial/index.html
  console.log(result.files.resources);    // [ …/resources/<sha1>.css, …/resources/screenshot.png ]
});

SaveSnapshotOptions

Option	Type	Default	Description
outputDir	string	required	Base output directory
name	string	required	Snapshot name — becomes a subdirectory
group	string	—	Parent directory (e.g. page name)
screenshot	Partial<ScreenshotOptions> | false	{ format: 'png', fullPage: false }	Screenshot options. Pass false to disable.
screenshot.format	'png' | 'webp'	'png'	Live-capture supports png only; webp throws. For webp bytes, use the trace-extraction path.
screenshot.fullPage	boolean	false	Capture the full scrollable page
manifest	boolean	true	Generate manifest.json
extraSelectors	string[]	—	Extra selectors the collector keeps
excludeSelectors	string[]	—	Selectors the collector drops
extraAttributes	string[]	—	Extra attributes the collector preserves

saveSnapshot() is skip-write-if-unchanged: when the assembled HTML matches the existing index.html, nothing is rewritten, but the returned files still references the existing paths.

3. Extract from existing traces (CLI or API)

Extract snapshots from Playwright HTML reports, trace ZIPs, or hosted report URLs — without re-running tests.

CLI

# From a local HTML report directory
npx playwright-snapshot-saver extract --source playwright-report

# From a trace ZIP file
npx playwright-snapshot-saver extract --source test-results/login/trace.zip

# From a hosted report URL
npx playwright-snapshot-saver extract --source https://example.com/report

# With filters and options
npx playwright-snapshot-saver extract \
  --source playwright-report \
  --output .snapshots \
  --page login \
  --state initial \
  --screenshot

CLI options

Option	Description
--source <path>	Report directory, trace ZIP, or URL (required)
--output <dir>	Output directory (default: .snapshots)
--page <name>	Filter by page name
--state <name>	Filter by state name
--screenshot	Opt in to resources/screenshot.webp extraction (off by default)
--no-screenshot	Explicitly disable (accepted for backwards compatibility)
--no-manifest	Skip manifest.json generation

extractSnapshots API

import { extractSnapshots } from 'playwright-snapshot-saver';

const result = await extractSnapshots({
  source: 'playwright-report',  // directory, .zip path, or URL
  outputDir: '.snapshots',
  screenshot: true,              // default is false since 0.6.0
  manifest: true,
  filter: { page: 'login' },
});

for (const snap of result.snapshots) {
  console.log(`${snap.page}/${snap.state} -> ${snap.outputDir}`);
  console.log(snap.files.html);          // always present
  console.log(snap.files.manifest);       // when manifest: true
  console.log(snap.files.screenshot);     // when screenshot: true and a frame was available
}

Trace-extracted bundles are fully self-contained: every <link>, <img>, CSS url(...), @font-face, and SVG <use> reference in the source page is rewritten to point at a file under resources/, and the original <base> element is stripped. Open the bundle anywhere — it renders without network access.

Snapshot bundle format (v2)

Each snapshot is a directory containing:

<name>/
  index.html                   # Sanitized DOM referencing resources/ (REQUIRED)
  manifest.json                # Metadata, schema version 2 (REQUIRED)
  resources/
    screenshot.png|webp        # Visual reference (optional)
    <sha1>.css                 # Stylesheet sidecars referenced by <link>
    <sha1>.woff2|png|jpg|…     # Fonts, images, media (trace-extracted bundles)

index.html references every resource via a relative resources/<filename> path. The plugin inlines CSS sidecars before passing the HTML to the JCEF <iframe srcdoc> because srcdoc iframes cannot resolve relative URLs. Producers ship sidecars — do not pre-inline CSS.

manifest.json

{
  "version": 2,
  "url": "https://example.com/login",
  "viewport": { "width": 1280, "height": 720 },
  "timestamp": "2025-01-15T10:30:00Z",
  "userAgent": "Mozilla/5.0 …",
  "playwright": "1.58.0"
}

Exactly one driver field (playwright / selenium / cypress / appium) is populated per manifest, matching the driver that produced the bundle. The Playwright version is auto-detected from your installed @playwright/test.

The v1 format is not backwards compatible — the plugin refuses to load v1 bundles with a user-visible error. Regenerate them by re-running your tests.

See docs/snapshot-bundle-spec.md for the authoritative spec.

Requirements

• Playwright >=1.40.0
• Node.js 18+
• For the marker/reporter workflow: trace: 'on' in Playwright config

License

MIT