In Playwright, what does running the tests with -u actually rewrite, and what does it leave untouched?

## What the flag is `-u` is the short form of `--update-snapshots` on the Playwright test command. It changes what the runner does when a capture and its reference disagree: instead of only reporting the difference, it writes the new image over the old one. In Playwright 1.63 the flag takes an optional mode rather than being a plain boolean: | Mode | Meaning | |---|---| | `all` | Regenerate references for the tests that ran | | `changed` | Regenerate the references that did not match | | `missing` | Create only references that do not exist — how an ordinary run already behaves | | `none` | Write nothing at all; a missing or mismatched reference is just a failure | The same values are available as `updateSnapshots` in `playwright.config.ts`, which is where a project pins the behaviour for automated runs. ## The three boundaries of a regeneration 1. **Only the tests that ran.** Filters compose with the flag. `npx playwright test tests/statement.spec.ts -g "balance" -u` refreshes the references belonging to the matching tests in that one file and nothing else. This is the useful property: a targeted redesign does not sweep the whole suite's baselines. 2. **Only the projects that ran.** Reference paths carry the project name, so `--project=chromium -u` cannot touch another project's files. Regenerating a change that affects the whole matrix means running the whole matrix. 3. **Only this platform.** The path also carries the platform, so a regeneration on one operating system leaves the other system's references exactly as they were. A suite whose references were generated on a laptop and consumed on a Linux runner needs the regeneration to happen where the run happens. ## What it never does - It does not delete anything. A reference for a renamed or deleted test stays on disk forever; nothing in the run prunes it, and the orphan is invisible because no assertion looks for it. - It does not review anything. The flag replaces the recorded expectation with whatever the application produced at that moment, so the verdict after a regeneration is meaningless until the suite is run again without the flag. - It does not repair a path problem. If the reference file name changed — a renamed test with an auto-generated name, a new project, a different platform — the flag creates the new file and quietly leaves the old one behind. ## The mechanics that trip people up - Running with `-u` from a machine whose fonts or rendering differ from the machine the suite normally runs on produces references that immediately fail everywhere else. - Regenerating with a filter applied and then dropping the filter shows the rest of the suite still failing, which looks like the flag did not work. - Adding a project to the config means every screenshot assertion has a missing reference for that project, so the first run there is a write-and-fail regardless of the flag. ## Running it deliberately A regeneration is worth treating as its own command, not a reflex when a check goes red: 1. Narrow the run to the tests whose appearance is genuinely meant to change. 2. Regenerate on the same kind of machine that runs the suite normally. 3. Re-run without the flag, so the pass you report comes from a comparison rather than from a write. 4. Look at the images the command changed before they leave your working tree — the flag has no opinion about whether the new picture is correct.