feat(browser): support playwright tracing (#8584)

Author: sheremet-va

.gitignore

@@ -25,6 +25,7 @@ docs/public/sponsors
 docs/.vitepress/cache/
 !test/cli/fixtures/dotted-files/**/.cache
 test/**/__screenshots__/**/*
+test/**/__traces__/**/*
 test/browser/fixtures/update-snapshot/basic.test.ts
 test/cli/fixtures/browser-multiple/basic-*
 .vitest-reports

.vscode/settings.json

@@ -23,7 +23,7 @@
   // ],
 
   "vitest.ignoreWorkspace": true,
-  "vitest.configSearchPatternInclude": "test/{core,cli,config}/{vitest,vite}.config.ts",
+  "vitest.configSearchPatternInclude": "test/{core,cli,config,browser}/{vitest,vite}.{config.ts,config.unit.mts}",
   "testing.automaticallyOpenTestResults": "neverOpen",
 
   // Enable eslint for all supported languages

docs/.vitepress/config.ts

@@ -305,6 +305,11 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/browser/visual-regression-testing',
                 docFooterText: 'Visual Regression Testing | Browser Mode',
               },
+              {
+                text: 'Trace Viewer',
+                link: '/guide/browser/trace-viewer',
+                docFooterText: 'Trace Viewer | Browser Mode',
+              },
             ],
           },
           {

docs/advanced/runner.md

@@ -27,19 +27,24 @@ export interface VitestRunner {
   /**
    * Called before running a single test. Doesn't have "result" yet.
    */
-  onBeforeRunTask?: (test: TaskPopulated) => unknown
+  onBeforeRunTask?: (test: Test) => unknown
   /**
    * Called before actually running the test function. Already has "result" with "state" and "startTime".
    */
-  onBeforeTryTask?: (test: TaskPopulated, options: { retry: number; repeats: number }) => unknown
+  onBeforeTryTask?: (test: Test, options: { retry: number; repeats: number }) => unknown
   /**
    * Called after result and state are set.
    */
-  onAfterRunTask?: (test: TaskPopulated) => unknown
+  onAfterRunTask?: (test: Test) => unknown
   /**
    * Called right after running the test function. Doesn't have new state yet. Will not be called, if the test function throws.
    */
-  onAfterTryTask?: (test: TaskPopulated, options: { retry: number; repeats: number }) => unknown
+  onAfterTryTask?: (test: Test, options: { retry: number; repeats: number }) => unknown
+  /**
+   * Called after the retry resolution happend. Unlike `onAfterTryTask`, the test now has a new state.
+   * All `after` hooks were also called by this point.
+   */
+  onAfterRetryTask?: (test: Test, options: { retry: number; repeats: number }) => unknown
 
   /**
    * Called before running a single suite. Doesn't have "result" yet.

docs/config/index.md

@@ -2439,7 +2439,7 @@ Polling timeout in milliseconds
 
 Always print console traces when calling any `console` method. This is useful for debugging.
 
-### attachmentsDir <Version>3.2.0</Version>
+### attachmentsDir <Version>3.2.0</Version> {#attachmentsdir}
 
 - **Type:** `string`
 - **Default:** `'.vitest-attachments'`

docs/guide/browser/config.md

@@ -128,7 +128,7 @@ A path to the HTML entry point. Can be relative to the root of the project. This
 
 Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](#api) option. By default, Vitest assigns port `63315` to avoid conflicts with the development server, allowing you to run both in parallel.
 
-## browser.provider <Badge type="danger">advanced</Badge> {#browser-provider}
+## browser.provider {#browser-provider}
 
 - **Type:** `BrowserProviderOption`
 - **Default:** `'preview'`
@@ -154,7 +154,7 @@ export default defineConfig({
 
 To configure how provider initializes the browser, you can pass down options to the factory function:
 
-```ts{7-15,22-27}
+```ts{7-13,20-26}
 import { playwright } from '@vitest/browser/providers/playwright'
 
 export default defineConfig({
@@ -188,7 +188,7 @@ export default defineConfig({
 })
 ```
 
-### Custom Provider
+### Custom Provider <Badge type="danger">advanced</Badge>
 
 ::: danger ADVANCED API
 The custom provider API is highly experimental and can change between patches. If you just need to run tests in a browser, use the [`browser.instances`](#browser-instances) option instead.
@@ -307,6 +307,50 @@ The timeout in milliseconds. If connection to the browser takes longer, the test
 This is the time it should take for the browser to establish the WebSocket connection with the Vitest server. In normal circumstances, this timeout should never be reached.
 :::
 
+## browser.trace
+
+- **Type:** `'on' | 'off' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure' | object`
+- **CLI:** `--browser.trace=on`, `--browser.trace=retain-on-failure`
+- **Default:** `'off'`
+
+Capture a trace of your browser test runs. You can preview traces with [Playwright Trace Viewer](https://trace.playwright.dev/).
+
+This options supports the following values:
+
+- `'on'` - capture trace for all tests. (not recommended as it's performance heavy)
+- `'off'` - do not capture traces.
+- `'on-first-retry'` - capture trace only when retrying the test for the first time.
+- `'on-all-retries'` - capture trace on every retry of the test.
+- `'retain-on-failure'` - capture trace only for tests that fail. This will automatically delete traces for tests that pass.
+- `object` - an object with the following shape:
+
+```ts
+interface TraceOptions {
+  mode: 'on' | 'off' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure'
+  /**
+   * The directory where all traces will be stored. By default, Vitest
+   * stores all traces in `__traces__` folder close to the test file.
+   */
+  tracesDir?: string
+  /**
+   * Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview.
+   * @default true
+   */
+  screenshots?: boolean
+  /**
+   * If this option is true tracing will
+   * - capture DOM snapshot on every action
+   * - record network activity
+   * @default true
+   */
+  snapshots?: boolean
+}
+```
+
+::: danger WARNING
+This option is supported only by the [**playwright**](/guide/browser/playwright) provider.
+:::
+
 ## browser.trackUnhandledErrors
 
 - **Type:** `boolean`

docs/guide/browser/playwright.md

@@ -18,7 +18,7 @@ export default defineConfig({
 
 Vitest opens a single page to run all tests in the same file. You can configure the `launch`, `connect` and `context` when calling `playwright` at the top level or inside instances:
 
-```ts{7-15,22-27} [vitest.config.js]
+```ts{7-14,21-26} [vitest.config.js]
 import { playwright } from '@vitest/browser/providers/playwright'
 import { defineConfig } from 'vitest/config'
 

docs/guide/browser/trace-viewer.md

@@ -0,0 +1,74 @@
+# Trace Viewer
+
+Vitest Browser Mode supports generating Playwright's [trace files](https://playwright.dev/docs/trace-viewer#viewing-remote-traces). To enable tracing, you need to set the [`trace`](/guide/browser/config#browser-trace) option in the `test.browser` configuration.
+
+::: warning
+Generating trace files is only available when using the [Playwright provider](/guide/browser/playwright).
+:::
+
+::: code-group
+```ts [vitest.config.js]
+import { defineConfig } from 'vitest/config'
+import { playwright } from '@vitest/browser/providers/playwright'
+
+export default defineConfig({
+  test: {
+    browser: {
+      provider: playwright(),
+      trace: 'on',
+    },
+  },
+})
+```
+```bash [CLI]
+vitest --browser.trace=on
+```
+:::
+
+By default, Vitest will generate a trace file for each test. You can also configure it to only generate traces on test failures by setting `trace` to `'on-first-retry'`, `'on-all-retries'` or `'retain-on-failure'`. The files will be saved in `__traces__` folder next to your test files. The name of the trace includes the project name, the test name, the [`repeats` count and `retry` count](/api/#test-api-reference):
+
+```
+chromium-my-test-0-0.trace.zip
+^^^^^^^^ project name
+         ^^^^^^ test name
+                ^ repeat count
+                  ^ retry count
+```
+
+To change the output directory, you can set the `tracesDir` option in the `test.browser.trace` configuration. This way all traces will be stored in the same directory, grouped by the test file.
+
+```ts [vitest.config.js]
+import { defineConfig } from 'vitest/config'
+import { playwright } from '@vitest/browser/providers/playwright'
+
+export default defineConfig({
+  test: {
+    browser: {
+      provider: playwright(),
+      trace: {
+        mode: 'on',
+        // the path is relative to the root of the project
+        tracesDir: './playwright-traces',
+      },
+    },
+  },
+})
+```
+
+The traces are available in reporters as [annotations](/guide/test-annotations). For example, in the HTML reporter, you can find the link to the trace file in the test details.
+
+## Preview
+
+To open the trace file, you can use the Playwright Trace Viewer. Run the following command in your terminal:
+
+```bash
+npx playwright show-trace "path-to-trace-file"
+```
+
+This will start the Trace Viewer and load the specified trace file.
+
+Alternatively, you can open the Trace Viewer in your browser at https://trace.playwright.dev and upload the trace file there.
+
+## Limitations
+
+At the moment, Vitest cannot populate the "Sources" tab in the Trace Viewer. This means that while you can see the actions and screenshots captured during the test, you won't be able to view the source code of your tests directly within the Trace Viewer. You will need to refer back to your code editor to see the test implementation.

docs/guide/cli-generated.md

@@ -376,6 +376,13 @@ If connection to the browser takes longer, the test suite will fail (default: `6
 
 Control if Vitest catches uncaught exceptions so they can be reported (default: `true`)
 
+### browser.trace
+
+- **CLI:** `--browser.trace <mode>`
+- **Config:** [browser.trace](/guide/browser/config#browser-trace)
+
+Enable trace view mode. Supported: "on", "off", "on-first-retry", "on-all-retries", "retain-on-failure".
+
 ### pool
 
 - **CLI:** `--pool <pool>`