diff --git a/docs/config/browser/traceview.md b/docs/config/browser/traceview.md new file mode 100644 index 000000000000..6bfb96351622 --- /dev/null +++ b/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 `` 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 `` 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. diff --git a/docs/guide/browser/index.md b/docs/guide/browser/index.md index 990498af1f0c..e824cd06327d 100644 --- a/docs/guide/browser/index.md +++ b/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. diff --git a/docs/guide/browser/trace-view-v2.md b/docs/guide/browser/trace-view-v2.md new file mode 100644 index 000000000000..c0e12dd3e51e --- /dev/null +++ b/docs/guide/browser/trace-view-v2.md @@ -0,0 +1,184 @@ +# Trace View V2 + + + +`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 resizable panes: + +- **Step list** (left) — every recorded action, assertion, mark, and lifecycle entry, with name, timing, selector, and source location. Failed actions and assertions are highlighted in red. +- **DOM snapshot** (right) — a reconstruction of the page at the selected step. The interacted element is highlighted in blue. + +Selecting a step also opens its source location in the Editor tab when that location is available. + +Vitest UI trace viewer showing step list and DOM snapshot +Vitest UI trace viewer showing step list and DOM snapshot + +Example replay uses [Vuetify's](https://github.com/vuetifyjs/vuetify) `VDateInput` component. + +## 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 `