Playwright Update Snapshots Command

Use this command:

npx playwright test --update-snapshots

The short form is:

npx playwright test -u

With no explicit mode, Playwright uses changed: mismatched snapshots are updated and matching snapshots remain unchanged. You can choose a mode explicitly with all, changed, missing, or none. Without the update flag, normal execution defaults to missing.

What the command updates

Playwright Test snapshot assertions compare the current result with an expected snapshot. The update flag tells the runner to write accepted actual results into snapshot files. This applies to screenshot comparisons and other Playwright Test snapshot assertions, including ARIA snapshots.

Command	Effect	Use it when
`npx playwright test --update-snapshots`	Updates changed snapshots (the implicit `changed` mode).	You reviewed the failures and want to accept intended differences.
`npx playwright test --update-snapshots=changed`	Updates only snapshots that differ from the actual result.	You want the normal, focused update workflow.
`npx playwright test --update-snapshots=all`	Regenerates every snapshot, including snapshots that already match.	You intentionally need a complete baseline regeneration.
`npx playwright test --update-snapshots=missing`	Creates only snapshots that do not exist.	You are establishing new coverage without replacing existing expectations.
`npx playwright test --update-snapshots=none`	Prevents snapshot updates.	You want an explicit read-only comparison run.

Playwright documents the option as -u / --update-snapshots [mode]: Command line.

Basic workflow

Run the test normally so you can see which snapshots fail.
Inspect each failure and decide whether the application change is intentional.
Run the update command with the narrowest test selection possible.
Review the generated snapshot diff.
Run the tests again without the update flag.
Commit only the snapshot changes that represent an intentional product change.

# Run one test file
npx playwright test tests/checkout.spec.ts

# Update only that file's changed snapshots
npx playwright test tests/checkout.spec.ts --update-snapshots=changed

# Run the final verification without updating files
npx playwright test tests/checkout.spec.ts

Run a specific test, project, or browser

Snapshot updates use the same test selection options as an ordinary Playwright Test run. Narrowing the selection reduces accidental baseline changes.

# Test title filter
npx playwright test -g "checkout" --update-snapshots=changed

# Project from playwright.config.ts
npx playwright test --project=chromium --update-snapshots=changed

# A single test file and line
npx playwright test tests/home.spec.ts:42 --update-snapshots=changed

Use your repository’s configured projects and test paths. A snapshot generated under one browser, viewport, operating system, or device configuration may not be interchangeable with another.

Choose the update mode deliberately

`changed`: the normal review mode

changed updates only expected results that differ from the current result. It preserves matching snapshots, so unrelated baselines stay untouched. Use it after a deliberate UI change or after fixing a rendering issue.

`all`: rebuild every baseline

all rewrites every snapshot, even those that currently match. This can create a large diff and can hide accidental environment changes. Use it only when you have a controlled reason to regenerate the complete set.

`missing`: add absent snapshots

missing generates snapshots that do not exist. It does not replace existing expected results. This is useful when adding new assertions or when bootstrapping a new test suite.

`none`: make updating impossible

none explicitly disables snapshot updates. It is useful in CI or in scripts where changing the working tree would be an error.

Control how source values are written

The snapshot mode controls which snapshots are eligible for updating. --update-source-method controls how Playwright writes source snapshot values.

Option	Behavior
`patch`	The default. Creates a unified diff that can be applied with `git apply`.
`3way`	Writes three-way merge conflict markers when source changes cannot be applied cleanly.
`overwrite`	Replaces source snapshot values directly.

# Default patch behavior
npx playwright test --update-snapshots=changed --update-source-method=patch

# Three-way merge markers for difficult source updates
npx playwright test --update-snapshots=changed --update-source-method=3way

# Direct replacement
npx playwright test --update-snapshots=changed --update-source-method=overwrite

Review generated changes before applying or committing them. Patch mode is usually the easiest to audit because the proposed changes remain visible as a diff.

Screenshot snapshots and ARIA snapshots

Screenshot comparisons

Screenshot assertions use the same update command:

await expect(page).toHaveScreenshot('dashboard.png');

npx playwright test --update-snapshots=changed

Keep screenshot files under version control and review them with the code change. A changed screenshot may indicate an intentional design update, a font or browser change, different data, or an unstable page.

ARIA snapshots

ARIA snapshot generation waits while the page settles, up to the maximum expect timeout configured for the runner. If generation exceeds the test timeout, increase the relevant timeout settings and investigate why the page is not reaching a stable state.

await expect(page.locator('body')).toMatchAriaSnapshot(`
- heading "Account"
- button "Save"
`);

See Playwright’s ARIA snapshots guide for assertion details.

What the command does not do

It does not install browsers. Browser installation is a separate workflow: npx playwright install.
It does not decide whether a visual change is correct. That review remains part of your test process.
It does not make a flaky page deterministic. Dynamic content, animations, fonts, time, locale, and network data can still produce changing output.
It does not update snapshots from tests that never run. Check your project, grep, file, and tag filters.

Make updates reproducible

Use the same Playwright version and browser revision across local development and CI.
Set a stable viewport, device scale factor, locale, timezone, and color scheme where those values affect rendering.
Disable or wait for animations and transitions before taking screenshots.
Mock clocks, random values, network responses, and user-specific data when they appear in the assertion.
Wait for a meaningful readiness condition instead of relying only on a fixed delay.
Keep test data and fonts available in the update environment.
Run the smallest relevant test selection first, then run the complete suite before merging.

Performance and reliability notes

changed generally produces a smaller filesystem diff and less review work than all, but the browser still has to execute the selected tests. Narrow test selection is the most direct way to reduce update time.

Snapshot reliability depends on deterministic rendering. A baseline generated on one operating system or browser revision can differ from a baseline generated elsewhere. Treat browser upgrades, font changes, and CSS rendering changes as baseline-affecting events and review them separately.

For ARIA snapshots, inspect both the expect timeout and the overall test timeout when page settling takes too long. Increasing a timeout can prevent premature failure, but it does not fix a page that never reaches the intended state.

Common errors and fixes

Symptom	Likely cause	Fix
“Unknown option” for the update flag	The command is being run through a different test runner or an old Playwright version.	Run the command through Playwright Test and check the installed package version with your package manager.
No snapshots are updated	The selected tests did not run, or there were no eligible differences.	Remove overly narrow filters, confirm the project, and run the test normally to inspect its result.
Every snapshot changes	`all` was selected, or the rendering environment changed.	Use `changed`, compare the environment, and inspect the diff before accepting it.
New snapshots are missing after a normal run	Normal execution can create missing snapshots but reports the generating tests as failed.	Review the generated files, then run the test again without update mode.
Patch application fails	Source code changed after the patch was generated.	Regenerate the patch on the current branch or use `3way` and resolve the conflict markers manually.
Screenshot differs only in dynamic areas	Time, random data, animation, ads, or network content is not stable.	Mock the value, wait for readiness, disable motion, or mask the dynamic region.
ARIA snapshot times out	The page has not settled before the expect or test timeout.	Fix the readiness condition and adjust expect or test timeout settings when the longer wait is legitimate.
Browser executable is missing	Playwright browsers have not been installed in the environment.	Install them separately with `npx playwright install`.

Review checklist before committing

Did the intended application change cause each updated snapshot?
Did you run only the intended project, browser, and test selection?
Are fonts, locale, timezone, viewport, and browser versions consistent?
Did you inspect image diffs and source diffs?
Did you rerun without --update-snapshots?
Are generated snapshot files included in the commit?

Or skip the browser setup

If you need rendered page images rather than repository snapshot assertions, ScreenshotNeo provides a one-request screenshot API. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response reports its result with X-Page-Verdict and X-Billed headers. It also offers an MCP server for AI agents with take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation for the complete option list.

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}`);

You get full-page capture with lazy images loaded, element capture, dark mode, device presets, custom viewports, retina scale, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, geolocation, transparent backgrounds, resizing, caching, signed links, async jobs, bulk capture, usage data, and PDF output. Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and start with 1,000 screenshots each month at no charge.

FAQ

What is the shortest Playwright update command?

npx playwright test -u. It uses the changed mode when no mode is supplied.

Should I use `all` or `changed`?

Use changed for normal review. Use all only when you intentionally want to regenerate matching baselines too.

Can I update only missing snapshots?

Yes. Run npx playwright test --update-snapshots=missing.

Where should snapshot files be reviewed?

Review them in the same pull request as the code or UI change, then rerun the tests without update mode before committing.

Does this command install Playwright browsers?

No. Install browsers separately with npx playwright install.