Screenshot Comparison

## The rule in one line `expect(page).toHaveScreenshot()` compares the current capture with a **reference image** stored on disk (also called a baseline or an expectation). When that file is absent, Playwright does two things in the same assertion: it **writes** the capture to the reference path, and it **fails** the test with a message of the form `A snapshot doesn't exist at <path>, writing actual.` Candidates routinely guess one half of this and miss the other. "It passes because there is nothing to compare" and "it fails and writes nothing until you pass `-u`" are both wrong. ## Why failing is the correct behaviour A screenshot baseline is a claim about what the UI is supposed to look like. The run that produced it has no idea whether the bank statement page rendered correctly, half-loaded, or with a broken stylesheet. - A passing first run would mean any state at all — including a visibly broken page — silently becomes the definition of correct. - Failing forces a human decision: look at the written PNG, then commit it or fix the page. - The message names the exact path it wrote, so the file is easy to find and inspect. - The written file shows up as a new untracked file in the working tree, which is the signal that a baseline was created rather than verified. ## What governs the write The behaviour is not hard-coded; it follows the runner's snapshot-update setting, configurable as `updateSnapshots` in `playwright.config.ts` or as `--update-snapshots` on the command line. | Setting | Effect on a missing reference | |---|---| | `'missing'` (the default) | The reference is created from the actual capture, and the test still fails | | `'none'` | Nothing is written; the missing reference is simply a failure | | `'all'` / `'changed'` | Regeneration modes you pass deliberately when refreshing existing references | Pinning `updateSnapshots: 'none'` for continuous integration is the usual move: on a machine where nobody will look at the file, creating a baseline has no value, and the failure is the whole point. ## How a first run still ends up green This is the part interviewers probe, because it explains a confusing pipeline result: 1. Attempt one finds no reference, writes the capture to the baseline path, and fails. 2. If retries are configured, attempt two runs against a workspace where the file now exists. 3. The second capture matches the file the first attempt wrote, so the assertion passes. 4. The runner reports the test as passed on retry — flaky, not failed — and the overall run can be green. Nothing was actually verified. The suite compared the application against itself. That is why the missing-reference failure is worth understanding rather than working around. ## The naming detail that surprises people When the matcher is called with no name argument, the reference file name is derived from the test title plus an index, so a test titled `statement balance widget` produces `statement-balance-widget-1.png`, and a second call in the same test produces `-2`. Passing an explicit name — `toHaveScreenshot('balance.png')` — decouples the file from the title, which matters because renaming the test otherwise orphans the old PNG and triggers the write-and-fail path all over again. ## Reading the failure correctly When this failure appears, the useful questions are mechanical: - Is the reference genuinely new, or did the path change because the test was renamed, or because a new project or platform was added to the run? - Did the run happen somewhere the written file will be thrown away, such as a container image, in which case the same failure repeats forever? - Is `updateSnapshots` set to something other than the default, which changes whether a file appeared at all? Answering those three separates "a new baseline exists and needs a look" from "the path this suite expects has quietly moved".