Your designer changes the button color from blue to green. You run your visual tests. They fail. The button looks different from the baseline. But this is an intentional change, not a bug. You need to update the baseline to accept the new design. This is the --update-snapshots workflow.
# Update ALL snapshots
npx playwright test --update-snapshots
# Update snapshots for specific test file only
npx playwright test tests/visual/login.spec.ts --update-snapshots
# Update snapshots for a specific test by name
npx playwright test -g "login page" --update-snapshotsDesigner makes a UI change. Developer implements it.
Run visual tests: npx playwright test. Tests fail as expected.
Review the diff images in test-results/ folder. Confirm the changes match the design.
If changes look correct, run npx playwright test --update-snapshots to update baselines.
Run tests again without the flag. All should pass now.
Commit the updated snapshot files. Include "update visual baselines" in the commit message.
Create a PR. Reviewers can see the old and new screenshots in the diff.
Never run --update-snapshots on the full suite after a CSS bug. You will overwrite good baselines with broken screenshots. Always update only the tests affected by the intentional change.
When you commit updated snapshots, the PR shows image diffs. GitHub renders PNG diffs side by side. Reviewers can see exactly what changed. This is one of the best features of storing snapshots in git.
# See which snapshot files changed
git diff --name-only -- "*.png"
# Stage only the specific snapshots that should change
git add tests/visual/login.spec.ts-snapshots/login-btn-*.png
# Do NOT blindly: git add *.pngAdd a CI check that fails if snapshots are updated without a corresponding code change. If only .png files changed in a PR but no .ts or .css files did, something is suspicious.
Key Point: Use --update-snapshots only for intentional changes. Review diffs first. Update specific files, not the entire suite. Commit snapshots with your code changes.