Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs: clarify behavior of each trace and video mode (#41127)

Yury Semikhatsky08e2d03b41d1
diff --git a/docs/src/test-api/class-testoptions.md b/docs/src/test-api/class-testoptions.md
index 475d51821d..813a37f3ac 100644
--- a/docs/src/test-api/class-testoptions.md
+++ b/docs/src/test-api/class-testoptions.md
@@ -591,14 +591,16 @@ export default defineConfig({
- `snapshots` ?<[boolean]> Whether to capture DOM snapshot on every action. Defaults to true. Optional.
- `sources` ?<[boolean]> Whether to include source files for trace actions. Defaults to true. Optional.
-Whether to record trace for each test. Defaults to `'off'`.
+Whether to record trace for each test. Defaults to `'off'`. The initial run of a test is the "first run"; subsequent runs caused by [retries](../test-retries.md) are "retries".
* `'off'`: Do not record trace.
-* `'on'`: Record trace for each test.
-* `'on-first-retry'`: Record trace only when retrying a test for the first time.
-* `'on-all-retries'`: Record trace only when retrying a test.
-* `'retain-on-failure'`: Record trace for each test. When test run passes, remove the recorded trace.
-* `'retain-on-first-failure'`: Record trace for the first run of each test, but not for retries. When test run passes, remove the recorded trace.
-* `'retain-on-failure-and-retries'`: Record trace for each test run. Retains all traces when an attempt fails.
+* `'on'`: Record and keep a trace for every run.
+* `'on-first-retry'`: Record and keep a trace only for the first retry of a test.
+* `'on-all-retries'`: Record and keep a trace for every retry.
+* `'retain-on-failure'`: Record a trace for every run, but keep it only for runs that failed. A failed run's trace is kept even when a later retry passes.
+* `'retain-on-first-failure'`: Record a trace only for the first run of a test (not for retries), and keep it only if that run failed.
+* `'retain-on-failure-and-retries'`: Record a trace for every run, and keep it for any run that failed or that is a retry.
+
+See [trace modes](../test-use-options.md#trace-modes) for a side-by-side comparison of what each mode records and keeps.
For more control, pass an object that specifies `mode` and trace features to enable.
@@ -648,14 +650,16 @@ export default defineConfig({
- `position` ?<[AnnotatePosition]<"top-left"|"top"|"top-right"|"bottom-left"|"bottom"|"bottom-right">> Position of the test information overlay. Defaults to `"top-left"`.
- `fontSize` ?<[int]> Font size of the test information in pixels. Defaults to `14`.
-Whether to record video for each test. Defaults to `'off'`.
+Whether to record video for each test. Defaults to `'off'`. The initial run of a test is the "first run"; subsequent runs caused by [retries](../test-retries.md) are "retries".
* `'off'`: Do not record video.
-* `'on'`: Record video for each test.
-* `'on-first-retry'`: Record video only when retrying a test for the first time.
-* `'on-all-retries'`: Record video only when retrying a test.
-* `'retain-on-failure'`: Record video for each test. When test run passes, remove the recorded video.
-* `'retain-on-first-failure'`: Record video for the first run of each test, but not for retries. When test run passes, remove the recorded video.
-* `'retain-on-failure-and-retries'`: Record video for each test run. Retains all videos when an attempt fails.
+* `'on'`: Record and keep a video for every run.
+* `'on-first-retry'`: Record and keep a video only for the first retry of a test.
+* `'on-all-retries'`: Record and keep a video for every retry.
+* `'retain-on-failure'`: Record a video for every run, but keep it only for runs that failed. A failed run's video is kept even when a later retry passes.
+* `'retain-on-first-failure'`: Record a video only for the first run of a test (not for retries), and keep it only if that run failed.
+* `'retain-on-failure-and-retries'`: Record a video for every run, and keep it for any run that failed or that is a retry.
+
+See [video modes](../test-use-options.md#video-modes) for a side-by-side comparison of what each mode records and keeps.
To control video size, pass an object with `mode` and `size` properties. If video size is not specified, it will be equal to [`property: TestOptions.viewport`] scaled down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size.
diff --git a/docs/src/test-use-options-js.md b/docs/src/test-use-options-js.md
index 50c9246e86..a88d3a76d6 100644
--- a/docs/src/test-use-options-js.md
+++ b/docs/src/test-use-options-js.md
@@ -152,6 +152,57 @@ export default defineConfig({
| [`property: TestOptions.trace`] | Playwright can produce test traces while running the tests. Later on, you can view the trace and get detailed information about Playwright execution by opening [Trace Viewer](./trace-viewer.md). Options include: `'off'`, `'on'`, `'retain-on-failure'` and `'on-first-retry'` |
| [`property: TestOptions.video`] | Playwright can record [videos](./videos.md) for your tests. Options include: `'off'`, `'on'`, `'retain-on-failure'` and `'on-first-retry'` |
+#### Trace modes
+
+The `trace` option supports several modes that differ in **which runs are recorded** and **which recordings are kept** after the test finishes. The initial run of a test is the "first run"; subsequent runs caused by [retries](./test-retries.md) are "retries".
+
+| Mode | Records a trace on | Keeps the trace when |
+| :- | :- | :- |
+| `'off'` | never | — |
+| `'on'` | every run | always |
+| `'retain-on-failure'` | every run | that run failed |
+| `'retain-on-first-failure'` | first run only | the first run failed |
+| `'retain-on-failure-and-retries'` | every run | that run failed, or it is a retry |
+| `'on-first-retry'` | first retry only | always |
+| `'on-all-retries'` | every retry | always |
+
+The following table shows which traces are kept in a few common scenarios, assuming `retries: 2` is configured:
+
+| Mode | Passes on first run | Fails, then passes on retry | Fails on every run |
+| :- | :- | :- | :- |
+| `'off'` | — | — | — |
+| `'on'` | first run | first run + retry | all three runs |
+| `'retain-on-failure'` | — | first run | all three runs |
+| `'retain-on-first-failure'` | — | first run | first run |
+| `'retain-on-failure-and-retries'` | — | first run + retry | all three runs |
+| `'on-first-retry'` | — | first retry | first retry |
+| `'on-all-retries'` | — | first retry | both retries |
+
+#### Video modes
+
+The `video` option supports the same set of modes as `trace`, and they record and keep recordings using the same rules.
+
+| Mode | Records a video on | Keeps the video when |
+| :- | :- | :- |
+| `'off'` | never | — |
+| `'on'` | every run | always |
+| `'retain-on-failure'` | every run | that run failed |
+| `'retain-on-first-failure'` | first run only | the first run failed |
+| `'retain-on-failure-and-retries'` | every run | that run failed, or it is a retry |
+| `'on-first-retry'` | first retry only | always |
+| `'on-all-retries'` | every retry | always |
+
+The following table shows which videos are kept in a few common scenarios, assuming `retries: 2` is configured:
+
+| Mode | Passes on first run | Fails, then passes on retry | Fails on every run |
+| :- | :- | :- | :- |
+| `'off'` | — | — | — |
+| `'on'` | first run | first run + retry | all three runs |
+| `'retain-on-failure'` | — | first run | all three runs |
+| `'retain-on-first-failure'` | — | first run | first run |
+| `'retain-on-failure-and-retries'` | — | first run + retry | all three runs |
+| `'on-first-retry'` | — | first retry | first retry |
+| `'on-all-retries'` | — | first retry | both retries |
### Other Options
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 2ec8436b50..437e29ffa7 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -6990,15 +6990,21 @@ export interface PlaywrightWorkerOptions {
*/
screenshot: ScreenshotMode | { mode: ScreenshotMode } & Pick<PageScreenshotOptions, 'fullPage' | 'omitBackground'>;
/**
- * Whether to record trace for each test. Defaults to `'off'`.
+ * Whether to record trace for each test. Defaults to `'off'`. The initial run of a test is the "first run";
+ * subsequent runs caused by [retries](https://playwright.dev/docs/test-retries) are "retries".
* - `'off'`: Do not record trace.
- * - `'on'`: Record trace for each test.
- * - `'on-first-retry'`: Record trace only when retrying a test for the first time.
- * - `'on-all-retries'`: Record trace only when retrying a test.
- * - `'retain-on-failure'`: Record trace for each test. When test run passes, remove the recorded trace.
- * - `'retain-on-first-failure'`: Record trace for the first run of each test, but not for retries. When test run
- * passes, remove the recorded trace.
- * - `'retain-on-failure-and-retries'`: Record trace for each test run. Retains all traces when an attempt fails.
+ * - `'on'`: Record and keep a trace for every run.
+ * - `'on-first-retry'`: Record and keep a trace only for the first retry of a test.
+ * - `'on-all-retries'`: Record and keep a trace for every retry.
+ * - `'retain-on-failure'`: Record a trace for every run, but keep it only for runs that failed. A failed run's
+ * trace is kept even when a later retry passes.
+ * - `'retain-on-first-failure'`: Record a trace only for the first run of a test (not for retries), and keep it
+ * only if that run failed.
+ * - `'retain-on-failure-and-retries'`: Record a trace for every run, and keep it for any run that failed or that is
+ * a retry.
+ *
+ * See [trace modes](https://playwright.dev/docs/test-use-options#trace-modes) for a side-by-side comparison of what each mode records and
+ * keeps.
*
* For more control, pass an object that specifies `mode` and trace features to enable.
*
@@ -7019,15 +7025,21 @@ export interface PlaywrightWorkerOptions {
*/
trace: TraceMode | /** deprecated */ 'retry-with-trace' | { mode: TraceMode, snapshots?: boolean, screenshots?: boolean, sources?: boolean, attachments?: boolean };
/**
- * Whether to record video for each test. Defaults to `'off'`.
+ * Whether to record video for each test. Defaults to `'off'`. The initial run of a test is the "first run";
+ * subsequent runs caused by [retries](https://playwright.dev/docs/test-retries) are "retries".
* - `'off'`: Do not record video.
- * - `'on'`: Record video for each test.
- * - `'on-first-retry'`: Record video only when retrying a test for the first time.
- * - `'on-all-retries'`: Record video only when retrying a test.
- * - `'retain-on-failure'`: Record video for each test. When test run passes, remove the recorded video.
- * - `'retain-on-first-failure'`: Record video for the first run of each test, but not for retries. When test run
- * passes, remove the recorded video.
- * - `'retain-on-failure-and-retries'`: Record video for each test run. Retains all videos when an attempt fails.
+ * - `'on'`: Record and keep a video for every run.
+ * - `'on-first-retry'`: Record and keep a video only for the first retry of a test.
+ * - `'on-all-retries'`: Record and keep a video for every retry.
+ * - `'retain-on-failure'`: Record a video for every run, but keep it only for runs that failed. A failed run's
+ * video is kept even when a later retry passes.
+ * - `'retain-on-first-failure'`: Record a video only for the first run of a test (not for retries), and keep it
+ * only if that run failed.
+ * - `'retain-on-failure-and-retries'`: Record a video for every run, and keep it for any run that failed or that is
+ * a retry.
+ *
+ * See [video modes](https://playwright.dev/docs/test-use-options#video-modes) for a side-by-side comparison of what each mode records and
+ * keeps.
*
* To control video size, pass an object with `mode` and `size` properties. If video size is not specified, it will be
* equal to [testOptions.viewport](https://playwright.dev/docs/api/class-testoptions#test-options-viewport) scaled