How to Update Playwright Screenshot Baselines Safely

To update Playwright screenshot baselines safely, first confirm the UI change is intentional, then run the relevant tests in the same pinned browser and operating-system environment that produced the existing baselines. Use --update-snapshots=changed for intended mismatches, inspect every changed image, and commit approved snapshots with the application change they represent. Reserve all for an intentional full regeneration.

A baseline is an expected rendered image, not an instruction to accept every failing comparison. Rendering can vary with operating system, browser version, settings, hardware, power source, and headless mode. When these differ, investigate before updating. [Playwright visual comparisons]

1. Confirm the change and identify affected tests

1. Read the visual assertion failure and verify that the page change is expected. If the UI should not have changed, investigate the test, data, timing, fonts, assets, and runtime environment instead of replacing the baseline.
2. Find the test or tests that own the failing snapshots. Use your repository’s existing test selection convention, such as a file path, title filter, or project selection.
3. Check which Playwright projects are affected. A project can represent a browser, device, or configuration, and can be part of the snapshot filename. Updating one project’s baseline does not validate the others.

There is no universal test-selection command: use the selectors and project names configured in your repository. Playwright projects let a test suite run under separate configurations, so make the affected project scope explicit where practical. [Playwright projects]

2. Match the baseline environment

Run the update where the existing reference images are expected to be authoritative. Align the operating system, Playwright version, installed browser binaries, browser project, headless setting, and relevant rendering configuration. Playwright recommends generating and comparing screenshots in the same environment. [Playwright visual comparisons]

• Keep the Playwright package version pinned through the project’s package manager and lockfile.
• Install the browsers and system dependencies appropriate for that pinned Playwright version using its documented install command. [Playwright browser management]
• If the baselines were generated in CI, prefer the same CI image or operating system for updates. If they were generated locally, use the same local platform and configuration.
• Treat a Playwright, browser, operating-system, or headless-mode change as a rendering migration. Review its resulting image changes as part of that migration.

When an environment migration is intentional, make it a reviewable change: state what changed, regenerate the affected project baselines, inspect the complete diff, and retain the relevant application or configuration changes alongside the snapshots.

3. Choose the right snapshot update mode

For the usual case—an intentional UI change affecting some existing snapshots—run the selected tests with changed:

npx playwright test --update-snapshots=changed

Add the test file, title filter, or project selector used by your repository when you want to limit the run. For example, the general shape is:

npx playwright test path/to/example.spec.ts --project=chromium --update-snapshots=changed

Replace the path and project with values from your configuration. The mode controls which references may be updated; test selection controls which tests run.

Mode	What it does	Use it when	Review concern
changed	Updates snapshots that differ from the current output.	An intentional change should alter existing reference images.	Inspect every changed file; a mismatch can still be accidental.
missing	Generates snapshots that do not yet exist.	Adding screenshot assertions or restoring absent references.	The documented default without an update flag is currently missing; tests that generate missing snapshots fail so the new files can be reviewed.
all	Updates all snapshots, including ones that already match.	A deliberate full regeneration, often as part of a documented environment migration.	Can produce a broad diff and rewrite unchanged references.
none	Prevents snapshot updates for the run.	A run must detect mismatches without writing references.	Use when updates are prohibited in a verification job.

These CLI modes and defaults are version-sensitive. Check the CLI reference and release notes for the Playwright version pinned by your project. The short -u flag without a mode currently defaults to changed, but spell out the mode in shared scripts and team instructions to make the intent clear. [Playwright test CLI] [Playwright release notes]

4. Inspect and approve the image changes

1. Review the test output and locate the newly written or changed snapshot files.
2. Open each image diff at a useful scale. Check the changed region, the surrounding layout, text wrapping, fonts, colors, icons, and image loading.
3. For each difference, ask whether the change follows from the intended UI change. Investigate unrelated differences rather than accepting them because the test run completed.
4. Check the snapshot names and directories. Confirm that the correct browser or project-specific references changed and that other project baselines have not been overlooked.
5. Review the source-code and snapshot diffs together. Commit approved snapshots with the related application change so the reason for the new expected output remains clear.

Playwright treats screenshot assertions as comparisons to reference images and recommends reviewing and committing the changed snapshots. [Playwright visual comparisons]

5. Diagnose unexpected failures before updating

If the same test produces different output from the expected baseline, use the image diff to identify what changed, then investigate the test execution context. The Trace Viewer can help examine the test timeline, DOM snapshots, and network requests. Tracing every test by default adds performance cost, so use traces as a targeted debugging aid. [Playwright Trace Viewer]

Common errors and fixes

Symptom	Likely cause	What to do
Many unrelated snapshots change at once	The OS, browser, Playwright version, headless mode, or rendering configuration differs from the baseline environment.	Re-run in the baseline environment. If the environment change is intentional, treat it as a migration and review the full set of changes.
Only one browser project fails	That browser may render differently, or only its project-specific baseline is stale.	Run and review the affected project explicitly; do not infer other projects passed from one browser’s result.
A missing snapshot is created but the test run fails	The run used the documented missing default or explicit missing mode; generating the reference is followed by a failing run for review.	Inspect the generated image, then run the test again without update mode to verify the comparison passes.
The update command changes snapshots that already match	all was selected.	Use changed for focused mismatches, unless full regeneration is intended.
A CI-only mismatch has no clear visual explanation	CI and local rendering environments may differ, or a timing or network-dependent page state may be involved.	Compare environment and project configuration, inspect the image diff, then use a targeted trace to review DOM and network activity.
The update option or shorthand behaves differently than expected	The project uses a different Playwright version than the CLI behavior being followed.	Check the CLI documentation and release notes for the version in the lockfile; use an explicit mode.

6. Make baseline updates repeatable

• Pin versions: keep Playwright and its browser binaries aligned through the project’s dependency and installation workflow.
• Use a stable environment: generate and compare references on the same OS and browser setup, especially between local development and CI.
• Keep scope narrow: select the affected tests and projects for ordinary UI changes; use a full run when the change’s reach requires it.
• Keep review visible: commit approved snapshots with the code change and make image diffs part of review.
• Separate migrations from routine UI work: browser or environment upgrades can change many images; make that scope apparent to reviewers.

Performance, reliability, and cost

Updating only selected tests and projects avoids needlessly rendering the entire suite during a focused change. A full run can still be appropriate when a shared component or rendering environment affects many pages. Tracing is useful for difficult failures, but Playwright advises against enabling traces for every test by default because it is performance-heavy. [Playwright Trace Viewer]

Baseline generation itself has no special per-screenshot service cost: the work runs through your Playwright test setup and compute environment. The practical costs are test runtime, CI capacity, and reviewer time. A broad all regeneration increases the number of image files to inspect, so use it only when that broad rewrite is the intended change.

Or skip the browser setup

If the goal is a clean capture of a live page rather than a Playwright regression baseline, ScreenshotNeo is a website screenshot API and MCP server. It does not replace Playwright’s baseline comparison or approval workflow, but it can return a page capture with one request. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks and CAPTCHAs, blank pages, failed loads, timeouts, and cache hits are not billed. Responses include X-Page-Verdict and X-Billed headers.
• An MCP server exposes take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.

FAQ

Should I update baselines whenever CI reports a visual mismatch?

No. First establish whether the rendered change is intended and whether the test ran in the baseline environment. Update references only after reviewing the mismatch.

Does a passing Chromium baseline update validate Firefox and WebKit?

No. Run and review each affected Playwright project because projects can use distinct browser or device configurations and snapshot files.

When is all appropriate?

Use it for an intentional full regeneration, such as a reviewed rendering-environment migration. It rewrites matching snapshots as well as mismatches.

Where can I verify the exact update mode for my project?

Check the Playwright CLI documentation and release notes for the version pinned by the project’s lockfile; defaults and behavior can change between versions.