feat(browser): enable failure-only trace view by default (#11766)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: hi-ogawa

docs/config/browser/traceview.md

@@ -7,27 +7,17 @@ outline: deep
 
 - **Type:** `boolean | 'off' | 'on' | 'failure-only' | { mode?: 'off' | 'on' | 'failure-only'; recordCanvas?: boolean; inlineImages?: boolean; ariaSnapshot?: boolean }`
 - **CLI:** `--browser.traceView`
-- **Default:** `false`
+- **Default:** `'failure-only'`
 
 Enable [trace view](/guide/browser/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. When a test fails, the terminal output also includes a [timeline of its recorded steps](/guide/browser/trace-view#failure-output).
 
-```ts
-export default defineConfig({
-  test: {
-    browser: {
-      traceView: true,
-    },
-  },
-})
-```
-
-To keep traces only for failed tests, use the `'failure-only'` mode:
+By default, trace view keeps traces only for failed tests. Set it to `true` (the same as [`mode: 'on'`](#traceview-mode)) to record every test, or `false` to turn it off:
 
 ```ts
 export default defineConfig({
   test: {
     browser: {
-      traceView: 'failure-only',
+      traceView: true,
     },
   },
 })
@@ -49,13 +39,13 @@ export default defineConfig({
 })
 ```
 
-| Option         | Default | Description                                                                                          |
-| -------------- | ------- | ---------------------------------------------------------------------------------------------------- |
-| `mode`         | `'off'` | How trace view records tests: `'on'` (every test), `'failure-only'` (only failed tests), or `'off'`. |
-| `inlineImages` | `false` | Inlines loaded `<img>` pixels into snapshots for more portable replay, useful in the HTML reporter.  |
-| `recordCanvas` | `false` | Captures canvas pixels in snapshots.                                                                 |
-| `ariaSnapshot` | `true`  | Captures the accessibility tree alongside each snapshot.                                             |
-| `enabled`      | `false` | Deprecated. Use `mode` instead.                                                                      |
+| Option         | Default          | Description                                                                                          |
+| -------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
+| `mode`         | `'failure-only'` | How trace view records tests: `'on'` (every test), `'failure-only'` (only failed tests), or `'off'`. |
+| `inlineImages` | `false`          | Inlines loaded `<img>` pixels into snapshots for more portable replay, useful in the HTML reporter.  |
+| `recordCanvas` | `false`          | Captures canvas pixels in snapshots.                                                                 |
+| `ariaSnapshot` | `true`           | Captures the accessibility tree alongside each snapshot.                                             |
+| `enabled`      | `false`          | Deprecated. Use `mode` instead.                                                                      |
 
 ## browser.traceView.enabled <Deprecated /> {#traceview-enabled}
 
@@ -68,7 +58,7 @@ Use [`mode`](#traceview-mode) instead. `true` is the same as `mode: 'on'`.
 ## browser.traceView.mode <Version>5.1.0</Version> {#traceview-mode}
 
 - **Type:** `'off' | 'on' | 'failure-only'`
-- **Default:** `'off'`
+- **Default:** `'failure-only'`
 - **CLI:** `--browser.traceView.mode <mode>`
 
 How trace view records tests. Takes precedence over the deprecated `enabled`.

docs/guide/browser/trace-view.md

@@ -2,13 +2,13 @@
 
 `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. When a test fails, the terminal output also includes a text timeline of its recorded steps.
+By default, Vitest records traces only for failed tests, so every browser test failure prints a [timeline of its recorded steps](#failure-output) in the terminal. The trace keeps a DOM snapshot of the page when the test failed, which you can open in the browser UI, Vitest UI, or HTML reporter. To snapshot every step, set [`browser.traceView.mode`](/config/browser/traceview#traceview-mode) to `'on'`. Trace view works with your existing debugging setup, whether that is the normal local browser UI, a headless browser with Vitest UI, or 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.
+`browser.traceView` keeps a replayable record for each recorded 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.
 
@@ -22,7 +22,7 @@ This page now documents Vitest's built-in `browser.traceView` feature. The previ
 
 ## Quick Start
 
-Enable trace view with the [`browser.traceView`](/config/browser/traceview) option:
+Failed tests are recorded without any configuration. To record passing tests too, set the [`browser.traceView`](/config/browser/traceview) option to `true`, or set it to `false` to turn trace view off:
 
 ::: code-group
 
@@ -44,7 +44,7 @@ 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). Failed tests also print their recorded steps in the terminal, as described in [Failure Output](#failure-output).
+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). Failed tests also print their recorded steps in the terminal, as described in [Failure Output](#failure-output).
 
 With the HTML reporter enabled, the [Vitest VS Code extension](https://github.com/vitest-dev/vscode#trace-view) adds an **Open Trace View** action to tests in the Testing view and editor gutter.
 
@@ -66,11 +66,11 @@ Selecting a step also opens its source location in the Editor tab when that loca
 
 | 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.                       |
+| Add trace replay to the normal local browser UI           | `vitest --browser.traceView`                                                  | Uses the default local headed browser UI and adds trace replay for every test.                           |
 | 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.                                            |
-| See failure steps in CI logs or from a coding agent       | `vitest run --browser.traceView`                                              | The failure summary in the terminal includes a timeline of the steps that led to each failure.           |
+| See failure steps in CI logs or from a coding agent       | `vitest run`                                                                  | The failure summary in the terminal includes a timeline of the steps that led to each failure.           |
+| Inspect failures in CI or run mode                        | `vitest run --reporter=html`                                                  | The HTML report shows the full step list with the page when the test failed.                             |
 
 ## Relation to Playwright Traces
 
@@ -103,7 +103,7 @@ When a test fails, the error in the terminal is followed by a timeline of its re
 
 <<< ./snippets/trace-failure.ansi [Error report]
 
-These are the same steps the trace viewer lists, without DOM snapshots. Only the last 10 steps are printed, so open the trace viewer to see the full trace.
+These are the last 10 steps the trace viewer lists, without DOM snapshots. To inspect the full step list and the page when the test failed, add the [HTML reporter](/guide/reporters#html-reporter). Set [`browser.traceView.mode`](/config/browser/traceview#traceview-mode) to `'on'` to snapshot every step.
 
 ## Custom Trace Entries
 
@@ -166,7 +166,7 @@ export default defineConfig({
   test: {
     browser: {
       traceView: {
-        enabled: true,
+        mode: 'on',
         inlineImages: true,
         recordCanvas: true,
       },

docs/guide/cli-generated.md

@@ -414,14 +414,14 @@ Enable trace view mode. Supported: "on", "off", "on-first-retry", "on-all-retrie
 - **CLI:** `--browser.traceView.enabled`
 - **Config:** [browser.traceView.enabled](/config/browser/traceview#traceview-enabled)
 
-Deprecated, use `--browser.traceView.mode` instead. Enable Vitest trace-view collection for browser tests (default: `false`)
+Deprecated, use `--browser.traceView.mode` instead. `true` is the same as `--browser.traceView.mode=on`
 
 ### browser.traceView.mode
 
 - **CLI:** `--browser.traceView.mode <mode>`
 - **Config:** [browser.traceView.mode](/config/browser/traceview#traceview-mode)
 
-How trace view records tests. Supported: "on" (every test), "failure-only" (only failed tests), "off" (default: `"off"`)
+How trace view records tests. Supported: "on" (every test), "failure-only" (only failed tests), "off" (default: `"failure-only"`)
 
 ### browser.traceView.recordCanvas
 

packages/vitest/src/node/cli/cli-config.ts

@@ -415,7 +415,8 @@ export const cliOptionsConfig: VitestCLIOptions = {
         },
       },
       traceView: {
-        description: 'Enable Vitest trace-view collection for browser tests (default: `false`)',
+        description:
+          'Enable Vitest trace-view collection for browser tests. `true` records every test, and `false` turns it off (default: `"failure-only"`)',
         argument: '',
         transform(value) {
           if (typeof value === 'boolean') {
@@ -426,11 +427,11 @@ export const cliOptionsConfig: VitestCLIOptions = {
         subcommands: {
           enabled: {
             description:
-              'Deprecated, use `--browser.traceView.mode` instead. Enable Vitest trace-view collection for browser tests (default: `false`)',
+              'Deprecated, use `--browser.traceView.mode` instead. `true` is the same as `--browser.traceView.mode=on`',
           },
           mode: {
             description:
-              'How trace view records tests. Supported: "on" (every test), "failure-only" (only failed tests), "off" (default: `"off"`)',
+              'How trace view records tests. Supported: "on" (every test), "failure-only" (only failed tests), "off" (default: `"failure-only"`)',
             argument: '<mode>',
           },
           recordCanvas: {

packages/vitest/src/node/config/resolveConfig.ts

@@ -964,18 +964,21 @@ export function resolveTestConfig(
     typeof traceView === 'string'
       ? traceView
       : typeof traceView === 'object'
-        ? (traceView.mode ?? (traceView.enabled ? 'on' : 'off'))
-        : traceView
-          ? 'on'
-          : 'off'
+        ? (traceView.mode ??
+          (traceView.enabled === undefined ? 'failure-only' : traceView.enabled ? 'on' : 'off'))
+        : traceView === undefined
+          ? 'failure-only'
+          : traceView
+            ? 'on'
+            : 'off'
   resolved.browser.traceView = {
     enabled: traceViewMode !== 'off',
     mode: traceViewMode,
     recordCanvas: traceViewOptions?.recordCanvas ?? false,
     inlineImages: traceViewOptions?.inlineImages ?? false,
     ariaSnapshot: traceViewOptions?.ariaSnapshot ?? true,
   }
-  if (resolved.browser.enabled && resolved.browser.traceView.enabled) {
+  if (resolved.browser.enabled && resolved.browser.traceView.mode === 'on') {
     resolved.browser.detailsPanelPosition = 'bottom'
   }
   if (resolved.browser.trace.tracesDir != null) {

packages/vitest/src/node/types/browser.ts

@@ -92,7 +92,7 @@ export interface BrowserTraceViewOptions {
    *
    * Takes precedence over `enabled`.
    *
-   * @default 'off'
+   * @default 'failure-only'
    * @experimental
    */
   mode?: BrowserTraceViewRecordingMode
@@ -297,7 +297,7 @@ export interface BrowserConfigOptions {
    *
    * This option controls Vitest's own trace-view pipeline, independently from provider-specific trace retention.
    *
-   * @default false
+   * @default 'failure-only'
    */
   traceView?: boolean | BrowserTraceViewRecordingMode | BrowserTraceViewOptions
 

test/browser/specs/trace-timeline.test.ts

@@ -8,7 +8,6 @@ async function runBrowserTests(structure: TestFsStructure) {
     browser: {
       ui: false,
       instances: instances.slice(0, 1),
-      traceView: true,
       screenshotFailures: false,
     },
   })

test/e2e/test/config/browser-configs.test.ts

@@ -817,6 +817,33 @@ test('detailsPanelPosition defaults to right', async () => {
   expect(projects[0].projectConfig.browser.detailsPanelPosition).toBe('right')
 })
 
+test('traceView defaults to failure-only', async () => {
+  const resolveMode = async (traceView?: NonNullable<TestUserConfig['browser']>['traceView']) => {
+    const projects = await config({
+      browser: {
+        enabled: true,
+        provider: preview(),
+        instances: [{ browser: 'chromium' }],
+        ...(traceView === undefined ? {} : { traceView }),
+      },
+    })
+    return projects[0].projectConfig.browser.traceView.mode
+  }
+  expect({
+    default: await resolveMode(),
+    true: await resolveMode(true),
+    false: await resolveMode(false),
+    object: await resolveMode({ inlineImages: true }),
+    enabled: await resolveMode({ enabled: true }),
+  }).toEqual({
+    default: 'failure-only',
+    true: 'on',
+    false: 'off',
+    object: 'failure-only',
+    enabled: 'on',
+  })
+})
+
 test('detailsPanelPosition from config file is respected', async () => {
   const projects = await config({
     browser: {