In Jest 30, how do you update snapshots after an intentional change, and what does jest -u actually rewrite or remove?
answer
- every failing snapshot in the run
- obsolete entries go too
- narrow with a pattern first
- watch mode has two keys
basics
~20 sRun jest -u (--updateSnapshot): it re-records every snapshot that fails in that run, writes missing ones and deletes obsolete entries and orphaned .snap files, so narrow the run with a path pattern or -t first and review the diff.
solid answer
~50 s`jest --updateSnapshot`, alias `-u`, switches snapshot writing to its update mode: every snapshot that **fails** in that run is re-recorded with the new output, missing ones are written, obsolete entries are deleted and `.snap` files whose test file is gone are removed. It does not ask whether a difference is intended, so a real bug in the same run gets recorded as the new truth. Narrow it first: a test path pattern limits the files, and `-t` / `--testNamePattern` limits the tests, while skipped tests keep their entries. In `--watch` mode, `u` updates all failing snapshots and `i` steps through them one test at a time, with `u` to accept, `s` to skip and `q` to quit. Until obsolete entries are removed, Jest reports them and the run exits non-zero even when every test passed.
code
bash · 8 lines# see what fails first
npx jest src/format
# accept the intended change for one test only
npx jest -u src/format -t "renderConfig defaults"
# confirm the resolved mode of a plain run
npx jest --showConfig | grep updateSnapshotgo deeper
Recall that -u or --updateSnapshot re-records snapshots, and that you read the diff before committing it.
Explain that -u rewrites every failing snapshot in the run and deletes obsolete entries, and how a path pattern and -t narrow it.
Show the workflow that stops a bug being recorded: run without -u, read each failure, update narrowly or interactively, and keep -u out of CI.
Weigh the review cost of large snapshot updates; a team convention on how updates are made and reviewed matters more than the flag itself.
## The three write modes Every Jest run resolves an internal `updateSnapshot` setting to one of three values, visible with `jest --showConfig`: | Value | When it applies | What Jest writes | |---|---|---| | `new` | a normal local run | only snapshots that do not exist yet | | `all` | `-u` / `--updateSnapshot` was passed | missing ones, every failing one, and it deletes obsolete entries | | `none` | CI mode (`--ci`, or detected) without `-u` | nothing: a missing snapshot fails the test | So the update workflow is the `all` mode, and its reach is the point of this question. ## What `-u` rewrites `jest -u` re-records **every snapshot that fails during this test run**. That wording matters: - Snapshots that still match are left alone, byte for byte. - A snapshot that fails because of the change you meant **and** one that fails because of a bug you did not notice are treated the same way. Both are overwritten. - Inline snapshots are rewritten inside the test source, external ones inside the `.snap` file. The documentation's own advice is to fix any unintended failure **before** updating, so the bug is not recorded as the expected output. ## What `-u` removes - **Obsolete entries**: keys in a `.snap` file that no test in the run checked, typically left behind by a renamed or deleted test. - **Orphaned snapshot files**: a `.snap` file whose test file no longer exists. Without `-u`, Jest only reports them, as `1 snapshot obsolete` with the key listed, and the run **exits non-zero even when every test passed**. That is deliberate: a stale entry is a sign the snapshot file no longer describes the suite. Tests that were skipped, failed, or filtered out by `-t` have their snapshots marked as checked, so a filtered run does not report their entries as obsolete. ## Narrowing an update Updating the whole suite to accept one change is how unrelated diffs get rubber-stamped. Narrow the run instead: 1. Pass a **test path pattern** so only the affected files run: `jest -u src/format`. 2. Add **`-t` / `--testNamePattern`** to limit which tests in those files run; skipped tests keep their entries untouched, even ones that would now fail. 3. Read the resulting `.snap` or test-source diff before committing it. In Jest 30, a run with `-u` and a `-t` pattern naming one test re-records only that test's failing snapshot, keeps a skipped test's entries even when they no longer match, and still deletes an entry whose test has been removed from the file. ## Updating from watch mode `jest --watch` offers two keys once a snapshot fails: - **`u`** updates all failing snapshots in the current watch run, the same as a `-u` run. - **`i`** enters **Interactive Snapshot Mode**, which shows one failing test at a time. Press `u` to update that test's snapshots, `s` to skip it, `q` (or Escape) to quit, and Enter to return to watch mode at the end. Interactive mode is the review-as-you-go option: you see each diff before you accept it. ## Reading an update before committing The update flag records; it does not review. The review happens in the diff: - A **`.snap` diff** shows the old and new text of each entry under its key, so a reviewer can ask whether each change follows from the code change. - Entries that changed but have **nothing to do** with the change being made are the warning sign: they are either a second bug or a test that depends on something unstable. - **Removed** entries should match tests that were renamed or deleted in the same change. - **Added** entries deserve the closest look of all, because they were never compared with anything. ## Habits that keep updates honest - Run the suite **without** `-u` first and read every failure; only then decide what to accept. - Commit snapshot updates in the same change as the code that caused them, so the review shows cause and effect together. - Never put `-u` in a CI script: in CI it turns every failing comparison into a silent rewrite. - After a large refactor, expect obsolete entries and clean them with a targeted `-u` rather than leaving the run red.
- After a refactor every Jest test passes but the run still exits with a failure. What is the likely cause?Obsolete snapshots. If a test was renamed or deleted, its old key is still in the `.snap` file and no test checked it; Jest prints `1 snapshot obsolete` with the key and marks the run failed. Running a targeted `jest -u` removes the entry, or a `.snap` file whose test file is gone, and the run turns green.
- Does jest -u -t 'some test' leave the other tests' snapshots in that file untouched?Their entries stay: tests that `-t` skips are marked as checked, so they are neither rewritten nor reported obsolete, even if they would now fail. Entries that no test in the file owns any more are a different case: an `-u` run still deletes those.
jest -u is the accept-all-changes button in a document review: it takes the edits you meant and the typo someone slipped in, together, without asking which is which.
- jest -u only rewrites the snapshots affected by my change
- jest -u rewrites every snapshot, including the ones that still pass
- Obsolete snapshots are harmless warnings that never fail a run
- Adding -u to the CI test script keeps the pipeline green safely
- Interactive mode is a separate CLI flag rather than a watch-mode key