vitest-dev · hi-ogawa · May 15, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
diff --git a/docs/config/browser/traceview.md b/docs/config/browser/traceview.md
@@ -5,7 +5,7 @@ outline: deep
 
 # browser.traceView <Badge type="warning" text="Experimental" /> <Version>5.0.0</Version>
 
-- **Type:** `boolean | { enabled?: boolean; recordCanvas?: boolean; inlineImages?: boolean }`
+- **Type:** `boolean | { enabled?: boolean; snapshot?: 'always' | 'on-failure'; recordCanvas?: boolean; inlineImages?: boolean }`
 - **CLI:** `--browser.traceView`
 - **Default:** `false`
 
@@ -29,6 +29,7 @@ export default defineConfig({
     browser: {
       traceView: {
         enabled: true,
+        snapshot: 'always',
         inlineImages: true,
         recordCanvas: true,
       },
@@ -40,6 +41,7 @@ export default defineConfig({
 | Option | Default | Description |
 | --- | --- | --- |
 | `enabled` | `false` | Enables Vitest trace-view artifact collection. |
+| `snapshot` | `'always'` | Controls when DOM snapshots are captured for trace-view entries. |
 | `inlineImages` | `false` | Inlines loaded `<img>` pixels into snapshots for more portable replay, useful in the HTML reporter. |
 | `recordCanvas` | `false` | Captures canvas pixels in snapshots. |
 
@@ -51,6 +53,14 @@ export default defineConfig({
 
 Enables Vitest trace-view artifact collection.
 
+## browser.traceView.snapshot {#traceview-snapshot}
+
+- **Type:** `'always' | 'on-failure'`
+- **Default:** `'always'`
+- **CLI:** `--browser.traceView.snapshot <policy>`
+
+Controls when DOM snapshots are captured for trace-view entries.
+
 ## browser.traceView.inlineImages {#traceview-inlineimages}
 
 - **Type:** `boolean`

diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md
@@ -443,6 +443,13 @@ Enable trace view mode. Supported: "on", "off", "on-first-retry", "on-all-retrie
 
 Enable Vitest trace-view collection for browser tests (default: `false`)
 
+### browser.traceView.snapshot
+
+- **CLI:** `--browser.traceView.snapshot <policy>`
+- **Config:** [browser.traceView.snapshot](/config/browser/traceview#traceview-snapshot)
+
+Control when DOM snapshots are captured for trace-view entries. Supported: "always", "on-failure" (default: `"always"`)
+
 ### browser.traceView.recordCanvas
 
 - **CLI:** `--browser.traceView.recordCanvas`

diff --git a/packages/browser/src/client/tester/runner.ts b/packages/browser/src/client/tester/runner.ts
@@ -90,7 +90,7 @@ export function createBrowserRunner(
         return
       }
       if (shouldTraceView) {
-        getBrowserState().browserTraceDomSnapshot = await import('rrweb-snapshot')
+        getBrowserState().browserTraceDomSnapshot ??= () => import('rrweb-snapshot')
         getBrowserState().browserTraceAttempts.set(test.id, { retry, repeats, startTime: now() })
       }
       else {

diff --git a/packages/browser/src/client/tester/trace.ts b/packages/browser/src/client/tester/trace.ts
@@ -35,7 +35,7 @@ export interface BrowserTraceEntry {
   // resolved server-side from stack in __vitest_recordBrowserTrace command
   location?: { file: string; line: number; column: number }
   element?: SerializedLocator
-  snapshot: TraceSnapshot
+  snapshot?: TraceSnapshot
 }
 
 interface TraceSnapshot {
@@ -89,14 +89,18 @@ export async function recordBrowserTraceEntry(
 ): Promise<void> {
   const attemptInfo = getBrowserState().browserTraceAttempts.get(task.id)!
   const relativeStartTime = now() - attemptInfo.startTime
-  const snapshot = takeSnapshot(options.element)
+  const traceView = getBrowserState().config.browser.traceView
+  const shouldTakeSnapshot
+    = traceView.snapshot === 'always'
+      || (traceView.snapshot === 'on-failure' && options.status === 'fail')
+  const snapshot = shouldTakeSnapshot ? await takeSnapshot(options.element) : undefined
   const entry: BrowserTraceEntry = {
     ...options,
     startTime: relativeStartTime,
     snapshot,
   }
   const { retry, repeats } = attemptInfo
-  const { recordCanvas } = getBrowserState().config.browser.traceView
+  const { recordCanvas } = traceView
 
   // An async lane could defer artifact recording and flush it at test-attempt end,
   // but the synchronous snapshot work is already a comparable cost, and this path
@@ -123,8 +127,8 @@ export async function recordBrowserTraceEntry(
 // selector engine inside the snapshot iframe at view time via injected script.
 // Our approach resolves at collection time (same moment as snapshot) — simpler but
 // requires Mirror plumbing. nodeId-based lookup also works across shadow DOM, unlike querySelector.
-function takeSnapshot(serializedLocator?: SerializedLocator): TraceSnapshot {
-  const { snapshot, createMirror } = getBrowserState().browserTraceDomSnapshot!
+async function takeSnapshot(serializedLocator?: SerializedLocator): Promise<TraceSnapshot> {
+  const { snapshot, createMirror } = await getBrowserState().browserTraceDomSnapshot!()
   const traceView = getBrowserState().config.browser.traceView
   const engine = getBrowserState().selectorEngine!
   const mirror = createMirror()

diff --git a/packages/browser/src/client/utils.ts b/packages/browser/src/client/utils.ts
@@ -96,8 +96,8 @@ export interface BrowserRunnerState {
   commands: CommandsManager
   activeTraceTaskIds: Set<string>
   browserTraceAttempts: Map<string, BrowserTraceAttempt>
-  // lazily loaded only when traceView is enabled
-  browserTraceDomSnapshot?: typeof import('rrweb-snapshot')
+  // lazily loaded only when traceView captures a snapshot
+  browserTraceDomSnapshot?: () => Promise<typeof import('rrweb-snapshot')>
   selectorEngine: Ivya
   traces: Traces
   cleanups: Array<() => unknown>

diff --git a/packages/ui/client/components/trace/TraceView.vue b/packages/ui/client/components/trace/TraceView.vue
@@ -32,7 +32,7 @@ function onSelectStep(index: number) {
 }
 
 watch([selectedStep, iframeEl], ([step, iframe]) => {
-  if (!step || !iframe) {
+  if (!step?.snapshot || !iframe) {
     return
   }
   const { serialized, selectorId, viewport, scroll, pseudoClassIds } = step.snapshot
@@ -189,12 +189,15 @@ function isTraceStepInProgress(step: BrowserTraceEntry) {
     <Pane :size="70" min-size="20">
       <div class="h-full min-h-0" flex="~ col" overflow-auto>
         <iframe
-          v-if="selectedStep"
+          v-if="selectedStep?.snapshot"
           ref="iframeEl"
           :key="iframeSandbox"
           :sandbox="iframeSandbox"
           style="background: white; border: none; color-scheme: normal; flex: none"
         />
+        <div v-else-if="selectedStep" class="text-sm opacity-50 p-4">
+          No DOM snapshot captured for this trace step
+        </div>
         <div v-else class="text-sm opacity-50 p-4">
           No trace step found
         </div>

diff --git a/packages/ui/client/composables/trace-view.ts b/packages/ui/client/composables/trace-view.ts
@@ -57,6 +57,7 @@ function mergeTraceRangeEntries(entries: BrowserTraceEntry[]): BrowserTraceEntry
       ...entry,
       startTime: start.startTime,
       duration: entry.startTime - start.startTime,
+      snapshot: entry.snapshot ?? start.snapshot,
     }
   }
 

diff --git a/packages/vitest/src/node/cli/cli-config.ts b/packages/vitest/src/node/cli/cli-config.ts
@@ -424,6 +424,10 @@ export const cliOptionsConfig: VitestCLIOptions = {
           enabled: {
             description: 'Enable Vitest trace-view collection for browser tests (default: `false`)',
           },
+          snapshot: {
+            description: 'Control when DOM snapshots are captured for trace-view entries. Supported: "always", "on-failure" (default: `"always"`)',
+            argument: '<policy>',
+          },
           recordCanvas: {
             description: 'Capture canvas pixels in trace-view snapshots (default: `false`)',
           },

diff --git a/packages/vitest/src/node/config/resolveConfig.ts b/packages/vitest/src/node/config/resolveConfig.ts
@@ -902,11 +902,13 @@ export function resolveConfig(
   resolved.browser.traceView = typeof traceView === 'object'
     ? {
         enabled: traceView.enabled ?? false,
+        snapshot: traceView.snapshot ?? 'always',
         recordCanvas: traceView.recordCanvas ?? false,
         inlineImages: traceView.inlineImages ?? false,
       }
     : {
         enabled: traceView ?? false,
+        snapshot: 'always',
         recordCanvas: false,
         inlineImages: false,
       }

diff --git a/packages/vitest/src/node/types/browser.ts b/packages/vitest/src/node/types/browser.ts
@@ -65,6 +65,14 @@ export interface BrowserTraceViewOptions {
    */
   enabled?: boolean
 
+  /**
+   * Control when DOM snapshots are captured for trace-view entries.
+   *
+   * @default 'always'
+   * @experimental
+   */
+  snapshot?: 'always' | 'on-failure'
+
   /**
    * Capture canvas pixels in trace view snapshots.
    *

diff --git a/packages/vitest/src/runtime/config.ts b/packages/vitest/src/runtime/config.ts
@@ -130,6 +130,7 @@ export interface SerializedConfig {
     trace: BrowserTraceViewMode
     traceView: {
       enabled: boolean
+      snapshot: 'always' | 'on-failure'
       recordCanvas: boolean
       inlineImages: boolean
     }

diff --git a/test/browser/specs/trace.test.ts b/test/browser/specs/trace.test.ts
@@ -34,8 +34,8 @@ test('trace view artifacts', async () => {
       startTime: undefined,
       duration: undefined,
       snapshot: {
-        selectorResolution: raw.snapshot.selectorResolution,
-        selectorError: raw.snapshot.selectorError,
+        selectorResolution: raw.snapshot?.selectorResolution,
+        selectorError: raw.snapshot?.selectorError,
       },
     }
     // remove noisy undefined properties

diff --git a/test/ui/fixtures/trace-bench/basic.test.ts b/test/ui/fixtures/trace-bench/basic.test.ts
diff --git a/test/ui/fixtures/trace-bench/mark.test.ts b/test/ui/fixtures/trace-bench/mark.test.ts
@@ -0,0 +1,3 @@
+import { test } from "vitest"
+
+test("marks", () => {})
diff --git a/test/ui/fixtures/trace-bench/vitest.config.ts b/test/ui/fixtures/trace-bench/vitest.config.ts
@@ -0,0 +1,22 @@
+import { playwright } from '@vitest/browser-playwright'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    ui: true,
+    browser: {
+      enabled: true,
+      provider: playwright(),
+      instances: [
+        { browser: 'chromium' },
+      ],
+      headless: true,
+      ui: false,
+      traceView: {
+        enabled: true,
+        // snapshot: 'on-failure',
+      },
+      screenshotFailures: false,
+    },
+  },
+})
diff --git a/test/ui/fixtures/trace-on-failure/basic.test.ts b/test/ui/fixtures/trace-on-failure/basic.test.ts
@@ -0,0 +1,15 @@
+import { expect, test } from 'vitest'
+import { page } from 'vitest/browser'
+
+test('basic', async () => {
+  document.body.innerHTML = '<button>hello</button>'
+  await expect
+    .element(page.getByRole('button'))
+    .toHaveTextContent('hello')
+  await expect
+    .element(page.getByRole('button'))
+    .toHaveAccessibleName('hello')
+  await expect
+    .element(page.getByRole('button'), { timeout: 100 })
+    .toHaveTextContent('world')
+})
diff --git a/test/ui/fixtures/trace-on-failure/vitest.config.ts b/test/ui/fixtures/trace-on-failure/vitest.config.ts
@@ -0,0 +1,22 @@
+import { playwright } from '@vitest/browser-playwright'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    ui: true,
+    browser: {
+      enabled: true,
+      provider: playwright(),
+      instances: [
+        { browser: 'chromium' },
+      ],
+      headless: true,
+      ui: false,
+      traceView: {
+        enabled: true,
+        snapshot: 'on-failure',
+      },
+      screenshotFailures: false,
+    },
+  },
+})
diff --git a/test/ui/test/trace-on-failure.spec.ts b/test/ui/test/trace-on-failure.spec.ts
@@ -0,0 +1,51 @@
+import type { Vitest } from 'vitest/node'
+import { expect, test } from '@playwright/test'
+import { assertTestCounts, openExplorerItem, startVitestUi } from './helper'
+
+test.describe('ui on-failure snapshots', () => {
+  let vitest: Vitest | undefined
+  let baseURL: string
+
+  test.beforeAll(async () => {
+    const root = './fixtures/trace-on-failure'
+    const server = await startVitestUi({
+      root,
+      watch: true,
+      ui: true,
+      open: false,
+    })
+    vitest = server.vitest
+    baseURL = `${server.url}/__vitest__/`
+  })
+
+  test.afterAll(async () => {
+    await vitest?.close()
+  })
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto(baseURL)
+    await assertTestCounts(page, { pass: 0, fail: 1 })
+  })
+
+  test('basic', async ({ page }) => {
+    await openExplorerItem(page, 'basic')
+
+    const traceView = page.getByTestId('trace-view')
+    await expect(traceView).toBeVisible()
+
+    const traceSteps = traceView.getByTestId('trace-step-name')
+    await expect(traceSteps).toHaveText([
+      'toHaveTextContent',
+      'toHaveAccessibleName',
+      'toHaveTextContent [ERROR]',
+      'test finished',
+    ])
+
+    await traceSteps.nth(2).click()
+    const traceFrame = traceView.frameLocator('iframe')
+    await expect(traceFrame.getByRole('button', { name: 'hello' })).toBeVisible()
+
+    await traceSteps.nth(1).click()
+    await expect(traceView.getByText('No DOM snapshot captured for this trace step')).toBeVisible()
+  })
+})
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import { test } from "vitest"

		test("marks", () => {})