Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
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.mdindex 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.mdindex 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 Optionsdiff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.tsindex 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