How to Update One Playwright Screenshot Snapshot Without Updating All

To update one Playwright screenshot snapshot without updating all of them, run only the test that owns the screenshot and pass --update-snapshots. Select the test by file and title:

npx playwright test tests/example.spec.ts -g "updates the profile screenshot" --update-snapshots

Replace the file path and title pattern with your project’s values. The CLI selects tests, not individual toHaveScreenshot() calls. If the selected test has multiple screenshot assertions, inspect every changed baseline before committing.

Playwright documents the --update-snapshots modes as all, changed, missing, and none. With the flag and no explicit mode, the default is changed. Avoid --update-snapshots=all when you intend a narrow update.

Update one snapshot step by step

Find the owning test. Search for the expected image name or the relevant toHaveScreenshot() call. Note its file and full test title.
Select the file and test title. Pass the file to playwright test and use -g with a distinctive title or title pattern.
Use the changed mode. Add --update-snapshots without a mode to use changed. You can write --update-snapshots=changed explicitly if you want the intent visible in scripts.
Check project and browser coverage. If the configuration defines multiple projects, determine which ones this command runs. A selected test may have baselines for multiple browsers or projects.
Review all generated changes. Inspect the visual diff and changed snapshot files. Keep only the baselines that match the intended UI change, then commit those files with the relevant code change.

Command patterns and scope

Goal	Command	Effect
Update changed snapshots for one test	`npx playwright test tests/profile.spec.ts -g "profile page" --update-snapshots`	Runs matching tests in the file and updates differing snapshots.
Make the default mode explicit	`npx playwright test tests/profile.spec.ts -g "profile page" --update-snapshots=changed`	Same changed-snapshot mode, stated explicitly.
Run a file’s tests with updates	`npx playwright test tests/profile.spec.ts --update-snapshots`	Scopes execution to the file, but may update snapshots for multiple tests in it.
Regenerate every snapshot in the selected run	`npx playwright test tests/profile.spec.ts --update-snapshots=all`	Updates all snapshots exercised by that run. This is broader than a single changed baseline.

The -g option is a test-title filter. It can match more than one test, so use a distinctive title and check the number of tests selected in the runner output. A file plus a title filter narrows the run to the intended test as far as the documented CLI selection allows.

What the update modes mean

Mode	Use it when	Scope note
`changed`	You want to update snapshots that differ from the current output. This is the default when the flag has no value.	Still applies to every relevant snapshot assertion executed in the selected tests.
`all`	You intentionally want to regenerate all snapshots in the selected run.	Can create a broad baseline change; do not use for a narrow update.
`missing`	You want to create missing snapshots.	Does not express an intent to replace every existing baseline.
`none`	You want snapshot updating disabled.	Useful when you need to ensure a command does not write updated baselines.

The filter controls which tests execute; the mode controls which snapshots can be updated within that run. Neither selects a single assertion inside a test.

Configuration and baseline filenames

Snapshot output paths and names depend on the test and project configuration. Playwright supports configuration templates for snapshot paths. In multi-project setups, a project name can appear in place of the browser name; browser and platform identifiers may also be part of snapshot filenames. Before accepting a change, check the actual files produced in your repository and confirm they belong to the intended project and environment.

If the test uses a custom snapshot path or a named screenshot, the update command remains the same. The path determines where the baseline is stored; the test selection determines what runs. See the official visual comparisons guide and TestConfig reference for snapshot behavior and configuration.

Why a snapshot may change unexpectedly

Screenshot baselines can vary with operating system, browser version, settings, hardware, power source, and headless mode. Use the same rendering environment that created the baseline where practical. Playwright’s guidance is: “For consistent screenshots, run tests in the same environment where the baseline screenshots were generated.” See Playwright visual comparisons.

When an image differs, first determine whether the difference is the intended UI change or an environment/rendering difference. Review the diff at the changed region and avoid accepting unrelated platform or browser baselines just because they were produced by the same run.

Common problems and fixes

Symptom	Likely cause	Fix
No test runs	The file path is wrong, or `-g` does not match the test title.	Run the file without the title filter to confirm it is discovered, then copy a distinctive phrase from the test title into `-g`.
More than one test runs	The title pattern is broad or appears in multiple test titles.	Use a more distinctive title pattern and verify the runner’s selected-test output before accepting updates.
More than one snapshot changes	The selected test contains multiple screenshot assertions, or multiple projects execute it.	Review each changed image and project-specific baseline. The CLI does not select an individual screenshot assertion.
Every baseline in the run changes	`all` was specified, or the selected test run exercises many snapshots.	Use the test-title filter with the default or explicit `changed` mode. If the test itself has several screenshot calls, review all of them.
The new image differs across machines	Rendering environment, browser version, operating system, or other rendering conditions differ.	Regenerate and compare in the baseline’s intended environment; review before committing.
The updated file is not where expected	Snapshot path templates, project naming, or browser/platform naming affect its location or filename.	Inspect the test configuration and changed-file list; use the configured path convention when reviewing and committing.

Performance, reliability, and cost

Updating a baseline requires running the selected test, so runtime depends on that test and the configured projects. Narrowing by file and title limits unnecessary test execution and reduces the number of outputs to review. If the test is part of a multi-project setup, account for each selected project’s run and baseline.

For reliable updates, make the change in a consistent browser and operating-system environment, inspect image diffs, and review the repository’s changed files before committing. The snapshot command itself has no separate per-update service charge; compute and CI costs depend on where and how often the test suite runs.

Or skip the browser setup

If you need a rendered page image outside the Playwright baseline workflow, ScreenshotNeo offers a website screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF. This does not update Playwright’s test snapshots; it is an alternative when you need to capture a page without maintaining browser capture code. See the ScreenshotNeo API documentation.

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 banners are accepted or removed before capture, along with known newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. AI agents can use its MCP server tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan. Learn more at ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.

Frequently asked questions

Can I update only one `toHaveScreenshot()` call inside a test?

The documented CLI filters at the test level. If one selected test contains several screenshot assertions, review every changed baseline from its run.

Does `-g` match the test file name?

No. Use the file argument to choose a file and -g to filter by test title.

Should I commit snapshot files?

Commit the reviewed baseline files that represent the intended visual change, together with the related code change. Do not accept unexplained image differences.

Where are the official command options documented?

See the Playwright command-line reference, running and debugging tests guide, and visual comparisons guide.