Updating Jest Snapshots

The -u / --updateSnapshot Flag

Running npx jest -u (or --updateSnapshot) tells Jest to overwrite every outdated snapshot with the current output, for every test that runs. This is meant for cases where you've reviewed a snapshot failure and confirmed the new output is correct, not a first response to any failing snapshot.

You can scope this to a specific test file or pattern (npx jest formatReceipt -u) to avoid accidentally updating unrelated, currently-broken snapshots elsewhere in the project.

# Update snapshots for every test in the suite
npx jest -u

# Update snapshots only for a specific file or pattern
npx jest formatReceipt.test.js -u

Scoping the update to a specific file avoids accidentally accepting unrelated, unreviewed snapshot changes.

The Safe Update Workflow

1. Run the full suite: npx jest
2. Read every snapshot failure diff carefully
3. Confirm each change is intentional and correct
4. Run: npx jest -u (or scoped to specific files)
5. Review the resulting .snap file changes in your diff/PR

• Never run -u before reading the failure diff — you might be masking a real regression.
• Treat updated .snap file changes in a pull request as reviewable code, not noise to skip past.
• If a snapshot changed unexpectedly (you didn't touch that code), investigate before updating.
• CI environments should typically run Jest without -u, so unreviewed changes fail the build instead of silently updating.

Updating Snapshots Cheat Sheet

Commands and habits for a safe snapshot update workflow.

Why --ci Mode Matters

Running Jest with --ci prevents it from writing brand-new snapshots automatically (which would otherwise happen on the first run of a toMatchSnapshot() call with no existing snapshot). Without this, a typo in a snapshot-based test could pass silently in CI simply because no snapshot existed yet to compare against.

# package.json script for CI
"test:ci": "jest --ci --coverage"

Investigating Unexpected Snapshot Failures

If a snapshot fails for code you didn't intentionally change, that's a signal something else shifted — a shared utility, a dependency upgrade, or an unrelated refactor with side effects. Always understand *why* a snapshot changed before running -u, even when the new output looks reasonable at a glance.

Common Mistakes

• Running jest -u immediately after any snapshot failure without reading the diff first.
• Updating the entire suite's snapshots when only one file's change was actually intended.
• Running CI without --ci, allowing new snapshots to be silently created instead of failing the build.
• Treating .snap file changes in a PR as unreviewable noise instead of real code changes.

Key Takeaways

• -u/--updateSnapshot overwrites outdated snapshots — only after you've reviewed the diff.
• Scope updates to specific files/patterns to avoid accepting unrelated changes.
• --ci mode prevents silently creating new snapshots during automated builds.
• Unexpected snapshot failures often reveal a real, unrelated regression — investigate before updating.