Video and Screenshots

## What the option actually is `screenshot` is a **Playwright Test runner option**, not a page API. You set it under `use` in `playwright.config.ts`, or narrow it with `test.use({ screenshot: 'only-on-failure' })` inside a file or a `describe` block. When it is on, the runner takes the picture itself around the end of a test; your test code calls nothing. That is the whole point: evidence you did not have to remember to capture, on the runs where you were not watching. Its manual counterpart, `page.screenshot()`, is a separate mechanism you drive yourself mid-test. The two coexist happily, and most mature suites use both. ## The four modes In Playwright 1.63 the option accepts four string values: | Value | When the runner captures | Why you would pick it | |---|---|---| | `'off'` | never | the default; nothing is written | | `'on'` | at the end of every test, pass or fail | short smoke suites where you want a picture of every result | | `'only-on-failure'` | when a test ends failed or timed out | the usual CI setting: evidence exactly where it matters | | `'on-first-failure'` | on the first failing attempt only, not on later retries | stops a retried flaky test writing near-identical images | `'only-on-failure'` fires on **every** failed attempt, so a test that fails three times leaves three sets of images; `'on-first-failure'` leaves one. ## Which pages get captured, and when The runner captures each page open in the test, so an order-tracker test that opened the customer page plus a driver-detail popup produces two files, `test-failed-1.png` and `test-failed-2.png`. The timing matters more than people expect. Capture happens **after the test body has ended**, which means: - a toast that had already faded is not in the image; - a page you closed in a cleanup step cannot be photographed at all; - an element that only appeared while an action was in flight is long gone. The screenshot shows the *aftermath* of the failure, not the moment of it. For the moment itself you want a recorded trace or your own capture taken at the point you care about. ## Where the file lands 1. The runner picks a directory for the test inside **`outputDir`** (`test-results/` unless the config changes it), named from the spec file, the test title and the project, with a `-retry1` suffix on a retried attempt so attempts never overwrite each other. 2. It writes `test-failed-1.png` there, numbering upwards for each additional page. 3. It records the file as an **attachment** named `screenshot` on the test result, which is how the HTML report and other reporters render it inline instead of making a reader dig through folders. A test's output folder is cleaned before that test runs, so you never inherit an image from an earlier run; equally, anything you write outside `outputDir` is yours to manage. ## The object form The string form is shorthand for an object: ```ts use: { screenshot: { mode: 'only-on-failure', fullPage: true }, } ``` - `mode` -- one of the four values above. - `fullPage` -- capture the whole scrollable document instead of the viewport. The default is viewport-only, which on a long delivery-tracking page can crop away the driver map and the timeline, leaving you a photograph of a header. - `omitBackground` -- capture with a transparent background where the page paints none. ## What it is not - **Not a baseline.** These images are evidence of what happened; checking an image against an approved reference is a different mechanism with its own storage and approval flow. - **Not a replacement for a recorded trace.** One PNG of the end state is far less than a step-by-step recording; screenshots are the thing a human glances at first, not the whole story. - **Not free on `'on'`.** A full-page capture on every passing test buys wall-clock time and CI disk for images nobody opens. - **Not per-test selective on its own.** The mode applies to whatever scope you set it in; deciding which cases deserve which evidence is a policy call you express through config scoping. ## A sane default For a food-delivery order tracker, `'only-on-failure'` with `fullPage: true` in the shared config pays for itself: green runs write nothing, and a red one hands the reviewer the entire page -- status banner, driver map and footer -- without anyone editing a test.