feat(browser): support dom snapshot trace view

docs/config/browser/traceview.md

@@ -0,0 +1,70 @@
+---
+title: browser.traceView | Config
+outline: deep
+---
+
+# browser.traceView
+
+- **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, especially in the HTML reporter. |
+| `recordCanvas` | `false` | Captures readable canvas pixels in snapshots. This enables a weaker replay iframe sandbox because rrweb needs scripts to redraw canvas data. |
+
+## 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, especially in the HTML reporter.
+
+## browser.traceView.recordCanvas {#traceview-recordcanvas}
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **CLI:** `--browser.traceView.recordCanvas`
+
+Captures readable 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-v2) 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-v2).
+
 ## 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/trace-view-v2.md

@@ -0,0 +1,180 @@
+# Trace View V2 <Badge type="warning" text="Experimental" />
+
+<!-- TODO: experimental version, rename md, better cross link -->
+
+`browser.traceView` records browser interactions as DOM snapshots and lets you replay them step by step in Vitest's built-in trace viewer. It is useful when the live browser view is not enough: you can inspect earlier tests, failed retries, screenshots, assertions, and user actions after the browser has already moved on.
+
+Trace view is additive to the current browser testing workflow. Enabling it does not force a single debugging mode. You can use it with the normal local browser UI, with a headless browser and Vitest UI, or with the HTML reporter in CI.
+
+::: tip Trace view, browser UI, and HTML reports
+
+The normal local browser mode opens the [browser UI](/config/browser/ui), where tests run in a visible iframe. This is useful while developing, but the iframe only shows the current browser state. When another test runs, the previous rendered state is gone.
+
+`browser.traceView` keeps a replayable record for each test. In local browser UI mode, the trace viewer appears alongside the existing live view so you can keep using the browser UI while also inspecting recorded steps.
+
+For static output, add the [HTML reporter](/guide/reporters#html-reporter). The same trace viewer can then be opened from the generated report, which is useful for run-mode and CI failures.
+
+:::
+
+## Quick Start
+
+Enable trace view with the [`browser.traceView`](/config/browser/traceview) option:
+
+::: code-group
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    browser: {
+      traceView: true,
+    },
+  },
+})
+```
+
+```bash [CLI]
+vitest --browser.traceView
+```
+
+:::
+
+When `browser.traceView` is enabled, tests with recorded traces can be opened in the trace viewer from the [browser UI](/config/browser/ui), [Vitest UI](/guide/ui), and [HTML reporter](/guide/reporters#html-reporter). The viewer has two panes:
+
+- **Step list** (left) — every recorded interaction and assertion, with name, selector, and source location. Click a step to navigate to it.
+- **DOM snapshot** (right) — a reconstruction of the page at the selected step. The interacted element is highlighted in blue.
+
+Clicking on a step's source location jumps to that line in the Editor tab.
+
+<img alt="Vitest UI trace viewer showing step list and DOM snapshot" img-light src="/browser/trace-view-light.png">
+<img alt="Vitest UI trace viewer showing step list and DOM snapshot" img-dark src="/browser/trace-view-dark.png">
+
+## Snapshot Fidelity
+
+By default, trace view captures the DOM tree, attributes, form values, same-origin readable CSS, element scroll positions, viewport size, and window scroll position. Images and canvas pixels are not inlined by default.
+
+Stylesheets are captured through the browser's CSSOM. Readable `<style>` tags and same-origin `<link rel="stylesheet">` files are serialized into the snapshot and replayed as inline styles, so normal component styles keep working in the trace viewer and HTML reporter. This captures the parsed CSS rules the browser applied, not the exact original stylesheet bytes: comments, formatting, invalid rules, and CSS resource files such as background images or fonts are not bundled this way.
+
+Enable additional fidelity options with the object form:
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    browser: {
+      traceView: {
+        enabled: true,
+        inlineImages: true,
+        recordCanvas: true,
+      },
+    },
+  },
+})
+```
+
+`inlineImages` stores loaded `<img>` pixels in the trace snapshot. This is mostly useful for the HTML reporter, where the report should be portable without depending on external image URLs. This is pixel capture, not original resource capture: SVGs are rasterized, animated images are not preserved as animations, and CSS background images or fonts are not covered. Cross-origin images need CORS-readable pixels to be inlined; otherwise they can still render from the external URL if it remains reachable.
+
+`recordCanvas` stores readable canvas pixels in the trace snapshot. This is useful for charts and simple 2D canvas output, but it is not a full canvas drawing timeline and does not provide complete WebGL replay.
+
+### External Resource Limits
+
+Trace view does not currently provide a general resource store. Resources that are not captured into the snapshot remain URL-backed.
+
+This means CSS background images and `@font-face` files referenced from serialized CSS still depend on their original URLs. External images can still render in the viewer when the browser can load the URL, but they are not portable in the HTML reporter unless `inlineImages` can capture their pixels. Cross-origin images need CORS-readable pixels for that capture; otherwise the browser can display them, but rrweb cannot safely draw them into a canvas data URL.
+
+Use `inlineImages` for loaded `<img>` elements that need to be portable in the HTML reporter. CSS subresources, fonts, non-CORS cross-origin images, videos, and other external files remain limitations of the current snapshot-based trace format.
+
+::: warning Canvas replay sandbox
+
+`recordCanvas` enables a weaker iframe sandbox in the trace viewer. rrweb replays canvas data through an image load handler, so Vitest allows scripts inside the replay iframe for traces recorded with `recordCanvas`. Keep this option enabled only when canvas pixels are useful for debugging.
+
+:::
+
+## Common Setups
+
+`browser.traceView` records traces. The browser mode, UI, and reporter options determine where you inspect them.
+
+<!--
+TODO: The browser UI / Vitest UI / browser driver combinations are not specific to trace view and might be better documented in the Browser Mode guide.  Something like:
+
+  | top-level --ui | browser.ui | browser.headless | Result |
+  | --- | --- | --- | --- |
+  | off | true | false | browser UI/live iframe in headed browser |
+  | on | false | true | pure Vitest UI, tests in headless browser |
+  | on | false | false | pure Vitest UI, tests in separate headed browser window |
+
+-->
+
+| Goal | Configuration | Result |
+| --- | --- | --- |
+| Add trace replay to the normal local browser UI | `vitest --browser.traceView` | Uses the default local headed browser UI and adds trace replay for recorded tests. |
+| Debug locally with a headless browser | `vitest --browser.traceView --browser.headless --ui` | The browser runs headless, while Vitest UI shows recorded trace steps and snapshots. |
+| Debug locally with a visible browser window and Vitest UI | `vitest --browser.traceView --browser.headless=false --browser.ui=false --ui` | Vitest UI shows recorded trace steps and snapshots, while tests run in a separate headed browser window. |
+| Generate a static report for CI or run mode | `vitest run --browser.traceView --reporter=html` | The HTML report includes the trace viewer for recorded tests. |
+
+## Relation to Playwright Traces
+
+`browser.traceView` and [`browser.trace`](/config/browser/trace) are independent features:
+
+|                        | `browser.traceView`                                       | `browser.trace`                                |
+| ---------------------- | --------------------------------------------------------- | ---------------------------------------------- |
+| Provider support       | All providers (playwright, webdriverio, preview)          | Playwright only                                |
+| Viewer                 | Browser UI / Vitest UI / HTML reporter                    | Playwright Trace Viewer / trace.playwright.dev |
+| Format                 | [rrweb](https://github.com/rrweb-io/rrweb) DOM snapshots | Playwright `.trace.zip`                        |
+| Requires external tool | No                                                        | Yes (`npx playwright show-trace`)              |
+
+You can enable both at the same time. See [Playwright Trace Files](./trace-view.md) for the `browser.trace` workflow.
+
+## Recorded Steps
+
+Trace entries are recorded automatically for:
+
+- `expect.element(...)` assertions
+- Interactive actions like `click`, `fill`, `type`, `hover`, `selectOptions`, `upload`, `dragAndDrop`, `tab`, `keyboard`, `wheel`
+- Test runner lifecycle event (e.g. `vitest:onAfterRetryTask` is recorded after each test and retry run)
+
+Each entry captures the DOM state at that point, along with the selector and the source location that triggered it.
+
+## Custom Trace Entries
+
+You can insert your own named entries with `page.mark()` and `locator.mark()`:
+
+```ts
+import { page } from 'vitest/browser'
+
+await page.mark('content rendered')
+
+await page.getByRole('button', { name: 'Sign in' }).mark('sign in button')
+```
+
+You can also pass a callback to `page.mark()`. Note that grouping is not currently supported — each inner action is recorded individually, and the mark entry appears at the end:
+
+```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()
+})
+```
+
+Use [`vi.defineHelper()`](/api/vi#vi-defineHelper) to make entries from reusable helpers point to the call site rather than the helper's internals:
+
+```ts
+import { vi } from 'vitest'
+import { page } from 'vitest/browser'
+
+const renderContent = vi.defineHelper(async (html: string) => {
+  document.body.innerHTML = html
+  await page.elementLocator(document.body).mark('render')
+})
+
+test('shows button', async () => {
+  await renderContent('<button>Hello</button>') // trace entry points here
+})
+```
+
+## Retries and Repeats
+
+Each attempt — retry or repeat — is recorded as a separate trace. When a test has multiple attempts, the viewer opens the most recent one by default. You can switch between attempts in the Report tab.

docs/guide/cli-generated.md

@@ -429,6 +429,27 @@ Control if Vitest catches uncaught exceptions so they can be reported (default:
 
 Enable trace view mode. Supported: "on", "off", "on-first-retry", "on-all-retries", "retain-on-failure".
 
+### browser.traceView.enabled
+
+- **CLI:** `--browser.traceView.enabled`
+- **Config:** [browser.traceView.enabled](/config/browser/traceview#traceview-enabled)
+
+Enable Vitest trace-view collection for browser tests (default: `false`)
+
+### browser.traceView.recordCanvas
+
+- **CLI:** `--browser.traceView.recordCanvas`
+- **Config:** [browser.traceView.recordCanvas](/config/browser/traceview#traceview-recordcanvas)
+
+Capture canvas pixels in trace-view snapshots (default: `false`)
+
+### browser.traceView.inlineImages
+
+- **CLI:** `--browser.traceView.inlineImages`
+- **Config:** [browser.traceView.inlineImages](/config/browser/traceview#traceview-inlineimages)
+
+Inline loaded image pixels in trace-view snapshots (default: `false`)
+
 ### browser.locators.exact
 
 - **CLI:** `--browser.locators.exact`

examples/lit/.gitignore

@@ -1,2 +1,3 @@
 __traces__
 __screenshots__
+html

packages/browser/package.json

@@ -90,6 +90,7 @@
     "ivya": "^1.8.0",
     "mime": "^4.1.0",
     "pathe": "catalog:",
+    "rrweb-snapshot": "2.0.0-alpha.20",
     "vitest": "workspace:*"
   }
 }

packages/browser/src/client/tester/context.ts

@@ -16,10 +16,12 @@ import type { StringifyOptions } from 'vitest/internal/browser'
 import type { IframeViewportEvent } from '../client'
 import type { BrowserRunnerState } from '../utils'
 import type { Locator as LocatorAPI } from './locators/index'
+import type { BrowserTraceEntryStatus } from './trace'
 import { vi } from 'vitest'
 import { __INTERNAL, stringify } from 'vitest/internal/browser'
-import { ensureAwaited, getBrowserState, getWorkerState } from '../utils'
+import { ensureAwaited, getBrowserState, getWorkerState, now } from '../utils'
 import { convertToSelector, isLocator, processTimeoutOptions, resolveUserEventWheelOptions } from './tester-utils'
+import { recordBrowserTraceEntry } from './trace'
 
 // this file should not import anything directly, only types and utils
 
@@ -361,9 +363,12 @@ export const page: BrowserPage = {
   ): any {
     const currentTest = getWorkerState().current
     const hasActiveTrace = !!currentTest && getBrowserState().activeTraceTaskIds.has(currentTest.id)
+    const hasActiveTraceView = !!currentTest && getBrowserState().browserTraceAttempts.has(currentTest.id)
 
     if (typeof bodyOrOptions === 'function') {
       return ensureAwaited(async (error) => {
+        let status: BrowserTraceEntryStatus = 'pass'
+        const startTime = now()
         if (hasActiveTrace) {
           await triggerCommand(
             '__vitest_groupTraceStart',
@@ -377,26 +382,53 @@ export const page: BrowserPage = {
         try {
           return await bodyOrOptions()
         }
+        catch (err) {
+          status = 'fail'
+          throw err
+        }
         finally {
+          if (hasActiveTraceView) {
+            // TODO: support nested trace
+            recordBrowserTraceEntry(currentTest, {
+              name,
+              kind: 'mark',
+              status,
+              startTime,
+              duration: now() - startTime,
+              stack: options?.stack ?? error?.stack,
+            })
+          }
           if (hasActiveTrace) {
             await triggerCommand('__vitest_groupTraceEnd', [], error)
           }
         }
       })
     }
 
-    if (!hasActiveTrace) {
+    if (!hasActiveTrace && !hasActiveTraceView) {
       return Promise.resolve()
     }
 
-    return ensureAwaited(error => triggerCommand(
-      '__vitest_markTrace',
-      [{
-        name,
-        stack: bodyOrOptions?.stack ?? error?.stack,
-      }],
-      error,
-    ))
+    return ensureAwaited((error) => {
+      if (hasActiveTraceView) {
+        recordBrowserTraceEntry(currentTest, {
+          name,
+          kind: 'mark',
+          stack: bodyOrOptions?.stack ?? error?.stack,
+        })
+      }
+      if (!hasActiveTrace) {
+        return Promise.resolve()
+      }
+      return triggerCommand(
+        '__vitest_markTrace',
+        [{
+          name,
+          stack: bodyOrOptions?.stack ?? error?.stack,
+        }],
+        error,
+      )
+    })
   },
   getByRole() {
     throw new Error(`Method "getByRole" is not supported by the "${provider}" provider.`)