Recommended Free Tools
If an existing Playwright snapshot stays unchanged after you run an update command, first run the test through the Playwright Test runner with npx playwright test --update-snapshots. The bare flag means changed: mismatched snapshots are rewritten, while matching snapshots are left alone. If you omit the flag, Playwright normally uses missing, which creates absent baselines but does not refresh an existing one. The other common causes are a test that was not selected, the wrong configuration file, a different snapshot type or path, a timeout, or a CI environment that does not match your local machine.
Start with the command Playwright actually documents
Run the command from the project directory that contains your Playwright configuration:
npx playwright test --update-snapshotsYou can use the short form:
npx playwright test -uThese are Playwright Test runner options. They are not a universal switch for every script that happens to use the Playwright browser library. If your repository has more than one configuration, specify the one that owns the test:
npx playwright test -c playwright.config.ts --update-snapshotsAfter the run, read the assertion output and inspect the working-tree diff. An update command can complete while changing no file because the selected tests did not contain a mismatch, or because they did not run at all.
Understand update modes before changing anything
The CLI and configuration API support four modes. The CLI’s bare --update-snapshots uses changed; the documented default when no update flag is supplied is missing. In configuration, updateSnapshots also defaults to missing.
| Mode | What it does | When to use it |
|---|---|---|
missing |
Creates snapshots that do not exist; leaves existing snapshots alone. | Normal test runs where new assertions need baselines. |
changed |
Replaces snapshots that differ from the result; matching files remain unchanged. | Targeted refresh after an intentional UI or content change. |
all |
Regenerates every matching snapshot, including files that currently pass. | A deliberate full-baseline regeneration followed by review. |
none |
Prevents snapshot updates. | Enforcing read-only baselines in a particular run or environment. |
Use all carefully. It can rewrite many files because of a browser, font, operating-system or dependency change that was not part of your application change. Review the diff rather than committing the result automatically.
A configuration example is:
import { defineConfig } from '@playwright/test';
export default defineConfig({
updateSnapshots: 'changed',
});Prefer the command-line flag for an occasional local update and configuration for a deliberate team policy. Do not set none and then expect a command to overwrite a baseline without changing the effective configuration.
Verify that the snapshot test is selected and executed
Snapshot updates apply only to tests that Playwright actually runs. A correct flag has no effect on a test excluded by a project, grep pattern, file filter, tag, shard or “only” setting.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
List the tests first
npx playwright test --listUse the same project, file path and grep options that you will use for the update. If the test is absent from the list, fix selection before investigating snapshot storage.
Run one test explicitly
npx playwright test tests/account.spec.ts -g "profile renders" --update-snapshotsCheck the terminal output for skipped tests, retries and assertion failures. A test that fails before reaching expect(...).toHaveScreenshot(), toMatchSnapshot() or an aria snapshot assertion cannot update that snapshot.
Check projects and configuration
Multi-project configurations can point at different browsers, base URLs, snapshot directories and devices. Pass the intended project when necessary and confirm that the command is using the expected config file. Running from a parent directory can also select a different package installation or configuration than running from the repository root.
Identify the snapshot kind and the file Playwright writes
Screenshot snapshots
Visual assertions such as expect(page).toHaveScreenshot() normally store files in a per-test snapshot directory. The final location can change when snapshotPathTemplate is configured, and a named format can affect the extension. Read the path printed in the failure report and compare it with the file you opened in an editor. Updating a PNG while inspecting an older WebP, or looking in a default directory while a template is active, makes a successful update appear broken.
import { test, expect } from '@playwright/test';
test('home page', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('home.png');
});Text and binary snapshots
expect(value).toMatchSnapshot() can write text or binary data. Confirm that the value is the one you intend to baseline and that the assertion is reached. A snapshot generated in a different test directory or with a different name is a separate baseline, not an overwrite of the file you expected.
Aria snapshots
Aria snapshots are generated and compared through the accessibility-tree assertion. Generation can take up to the configured expect timeout. If the page is still changing or the timeout is too short, the assertion can fail before a replacement is written. Increase the relevant expect timeout for this test, then rerun and inspect the failure:
import { test, expect } from '@playwright/test';
test('navigation tree', async ({ page }) => {
test.setTimeout(60_000);
await page.goto('/');
await expect(page.getByRole('navigation')).toMatchAriaSnapshot({
timeout: 15_000,
});
});Use a longer timeout to accommodate a genuinely slow page, not to hide a locator that never stabilizes. Wait for the page state or a specific element when that is the real synchronization requirement.
Check how source-embedded snapshots are updated
Some workflows keep snapshot data in source files rather than separate snapshot files. In those workflows, --update-source-method controls how Playwright proposes the change:
Free tools Windows power users keep installed
One-click scans. No signup required.
patch(default): creates a unified diff for you to inspect and apply later.3way: adds conflict markers so you can choose between the current source and the generated value.overwrite: writes the generated value directly into the source.
If you expected an immediate source edit while the mode is patch, look for the generated patch. With 3way, resolve conflict markers manually. Use overwrite only when direct replacement is acceptable and the resulting diff will be reviewed.
Separate a real UI change from rendering noise
A screenshot mismatch is evidence of a pixel difference, not proof that the application is wrong. Before updating, decide whether the changed pixels represent an intended product change or environmental variation.
- Compare browser version, Playwright package version, operating system and installed fonts.
- Use the same viewport, device scale factor, color scheme, locale and timezone.
- Wait for animations, network data and lazy images to settle before capturing.
- Check whether timestamps, random identifiers, ads or user-specific content are in the image.
- Inspect the diff image and the “actual” and “expected” files, not only the assertion’s exit code.
Playwright’s visual assertions provide pixel-difference controls, but increasing tolerance merely to make an unexplained failure pass can conceal a regression. Stabilize the test or remove nondeterministic content first, then choose a tolerance that reflects an intentional visual policy.
Rank #4
Fix CI-only update failures
Do not copy a local baseline into CI until you know the environments are comparable. Check all of the following:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11- The exact Playwright version installed from the lockfile.
- The browser binaries and system dependencies installed on the CI worker.
- Operating system, fonts, locale, timezone, viewport and device scale factor.
- The CI configuration file, project selection, workers, retries and sharding.
- Whether the same test data, secrets and base URL are available.
Install the browsers and required dependencies in the CI job using the Playwright installation step appropriate for your package manager. Playwright’s CI guidance recommends one worker in CI when stability and reproducibility matter. Once the environments match, run the failing test with --update-snapshots only in a controlled baseline-update job, review the diff, and commit approved files rather than allowing every CI run to rewrite them.
Common symptoms, causes and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No file changes | No mismatch was selected, the test was skipped, or mode is missing. |
Run --list, execute the exact test, and use --update-snapshots or explicit changed. |
| “Snapshot not found” | The expected baseline is missing or the path/name differs. | Run the selected test in missing mode and inspect the reported path. |
| Wrong file appears unchanged | A snapshot path template, project or format points elsewhere. | Read the assertion’s actual path and check snapshotPathTemplate. |
| Aria assertion times out | Accessibility-tree generation exceeds the expect timeout or the page never stabilizes. | Wait for the required UI state and increase the assertion timeout where justified. |
| Source file is not overwritten | Source update method is patch or 3way. |
Apply the patch, resolve markers, or intentionally choose overwrite. |
| Local passes, CI fails | Browser, fonts, dependencies, config or test data differ. | Compare environments and use a reproducible CI worker setup. |
A repeatable update workflow
- Commit or stash unrelated work so the snapshot diff is readable.
- Run
npx playwright test --listwith the intended config and confirm the test is included. - Run the smallest failing test without update mode and read the assertion output.
- Inspect the expected, actual and diff artifacts and identify the exact snapshot path.
- Decide whether the mismatch is an application change, test instability or environment drift.
- Run
npx playwright test -c <file> --update-snapshotsfor intentional changed baselines. - Use
allonly for a planned regeneration, then review every changed file. - Run the test again without the update flag to prove the new baseline passes.
- Commit only approved snapshots and the code or configuration change that explains them.
Or skip the browser setup
If your goal is simply to capture a stable website image rather than maintain a Playwright test baseline, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. It also offers an MCP server for Claude, Cursor and other MCP clients, with take_screenshot, get_page_info and capture_pdf.
See the ScreenshotNeo API documentation for all options, including full-page and element captures, device presets, retina scale, PDF settings, custom CSS and JavaScript, waits, request blocking, headers, cookies, geolocation, caching, signed links and bulk capture.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account to get started.
FAQ
Does -u update every snapshot?
No. The bare flag uses changed, so only mismatched snapshots are refreshed. Use all for an intentional full regeneration.
Best Value
Why did a successful run change no files?
The selected tests may already match, the test containing the assertion may not have run, or the effective mode may be missing. Confirm selection with --list and inspect the reported snapshot path.
Should I update snapshots in CI?
Only in a controlled workflow with matching environments and human review. Ordinary CI verification should detect differences, not silently rewrite baselines.
Frequently Asked Questions
Can I update one snapshot without regenerating the suite?
Yes. Filter to the specific test or file, then run that selection with --update-snapshots. The update applies only to tests executed by that command.
What is the safest mode for a large baseline refresh?
Use all only when a browser or rendering change intentionally affects the entire suite. Review the complete diff and rerun without update mode before committing.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
