feat(browser): support dom snapshot trace view

docs/.vitepress/config.ts

@@ -806,6 +806,11 @@ export default ({ mode }: { mode: string }) => {
                 link: '/guide/browser/trace-view',
                 docFooterText: 'Trace View | Browser Mode',
               },
+              {
+                text: 'Playwright Traces',
+                link: '/guide/browser/playwright-traces',
+                docFooterText: 'Playwright Traces | Browser Mode',
+              },
               {
                 text: 'ARIA Snapshots',
                 link: '/guide/browser/aria-snapshots',

docs/config/browser/trace.md

@@ -11,6 +11,8 @@ outline: deep
 
 Capture a trace of your browser test runs. You can preview traces with [Playwright Trace Viewer](https://trace.playwright.dev/).
 
+See [Playwright Traces](/guide/browser/playwright-traces) for the full workflow.
+
 This options supports the following values:
 
 - `'on'` - capture trace for all tests. (not recommended as it's performance heavy)

docs/config/browser/traceview.md

@@ -0,0 +1,70 @@
+---
+title: browser.traceView | Config
+outline: deep
+---
+
+# browser.traceView <Badge type="warning" text="Experimental" /> <Version>5.0.0</Version>
+
+- **Type:** `boolean | { enabled?: boolean; recordCanvas?: boolean; inlineImages?: boolean }`
+- **CLI:** `--browser.traceView`
+- **Default:** `false`
+
+Enable trace-view collection for browser tests. Vitest captures DOM snapshots for browser interactions and can show them in the browser UI, Vitest UI, or HTML reporter when those surfaces are enabled — no external tools required.
+
+```ts
+export default defineConfig({
+  test: {
+    browser: {
+      traceView: true,
+    },
+  },
+})
+```
+
+Use the object form to enable additional snapshot fidelity options:
+
+```ts
+export default defineConfig({
+  test: {
+    browser: {
+      traceView: {
+        enabled: true,
+        inlineImages: true,
+        recordCanvas: true,
+      },
+    },
+  },
+})
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `enabled` | `false` | Enables Vitest trace-view artifact collection. |
+| `inlineImages` | `false` | Inlines loaded `<img>` pixels into snapshots for more portable replay, useful in the HTML reporter. |
+| `recordCanvas` | `false` | Captures canvas pixels in snapshots. |
+
+## browser.traceView.enabled {#traceview-enabled}
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **CLI:** `--browser.traceView.enabled`
+
+Enables Vitest trace-view artifact collection.
+
+## browser.traceView.inlineImages {#traceview-inlineimages}
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **CLI:** `--browser.traceView.inlineImages`
+
+Inlines loaded `<img>` pixels into snapshots for more portable replay, useful in the HTML reporter.
+
+## browser.traceView.recordCanvas {#traceview-recordcanvas}
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **CLI:** `--browser.traceView.recordCanvas`
+
+Captures canvas pixels in snapshots. This enables a weaker replay iframe sandbox because rrweb needs scripts to redraw canvas data.
+
+See [Trace View](/guide/browser/trace-view) for full documentation.

docs/guide/browser/index.md

@@ -330,6 +330,8 @@ Since Vitest 3.2, if you don't have the `browser` option in your config but spec
 
 By default, Vitest will automatically open the browser UI for development. Your tests will run inside an iframe in the center. You can configure the viewport by selecting the preferred dimensions, calling `page.viewport` inside the test, or setting default values in [the config](/config/browser/viewport).
 
+For an alternative debugging model that captures DOM snapshots for every test instead of showing a live iframe, see [Trace View](/guide/browser/trace-view).
+
 ## Headless
 
 Headless mode is another option available in the browser mode. In headless mode, the browser runs in the background without a user interface, which makes it useful for running automated tests. The headless option in Vitest can be set to a boolean value to enable or disable headless mode.

docs/guide/browser/playwright-traces.md

@@ -0,0 +1,126 @@
+# Playwright Traces
+
+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`](/config/browser/trace) option in the `test.browser` configuration.
+
+::: warning
+Generating trace files is only available when using the [Playwright provider](/config/browser/playwright).
+:::
+
+::: code-group
+```ts [vitest.config.js]
+import { defineConfig } from 'vitest/config'
+import { playwright } from '@vitest/browser-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`](/api/test#repeats) count and [`retry`](/api/test#retry) count:
+
+```
+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-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.
+
+## Trace markers
+
+You can add explicit named markers to make the trace timeline easier to read:
+
+```ts
+import { page } from 'vitest/browser'
+
+document.body.innerHTML = `
+  <button type="button">Sign in</button>
+`
+
+await page.getByRole('button', { name: 'Sign in' }).mark('sign in button rendered')
+```
+
+Both `page.mark(name)` and `locator.mark(name)` are available.
+
+You can also group multiple operations under one marker with `page.mark(name, callback)`:
+
+```ts
+await page.mark('sign in flow', async () => {
+  await page.getByRole('textbox', { name: 'Email' }).fill('john@example.com')
+  await page.getByRole('textbox', { name: 'Password' }).fill('secret')
+  await page.getByRole('button', { name: 'Sign in' }).click()
+})
+```
+
+You can also wrap reusable helpers with [`vi.defineHelper()`](/api/vi#vi-defineHelper) so trace entries point to where the helper is called, not its internals:
+
+```ts
+import { vi } from 'vitest'
+import { page } from 'vitest/browser'
+
+const myRender = vi.defineHelper(async (content: string) => {
+  document.body.innerHTML = content
+  await page.elementLocator(document.body).mark('render helper')
+})
+
+test('renders content', async () => {
+  await myRender('<button>Hello</button>') // trace points to this line
+})
+```
+
+## 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.
+
+<img alt="Trace Viewer showing the trace timeline and rendered component" img-light src="/trace-viewer-light.png">
+<img alt="Trace Viewer showing the trace timeline and rendered component" img-dark src="/trace-viewer-dark.png">
+
+## Source Location
+
+When you open a trace, you'll notice that Vitest groups browser interactions and links them back to the exact line in your test that triggered them. This happens automatically for:
+
+- `expect.element(...)` assertions
+- Interactive actions like `click`, `fill`, `type`, `hover`, `selectOptions`, `upload`, `dragAndDrop`, `tab`, `keyboard`, `wheel`, and screenshots
+
+Under the hood, Playwright still records its own low-level action events as usual. Vitest wraps them with source-location groups so you can jump straight from the trace timeline to the relevant line in your test.
+
+For anything not covered automatically, you can use `page.mark()` or `locator.mark()` to add your own trace groups — see [Trace markers](#trace-markers) above.