Trace View: Failure-Only Snapshot Capture

• Part of https://github.com/vitest-dev/vitest/issues/10156

Vitest browser trace view currently captures DOM snapshots as trace entries are recorded. This gives a useful step timeline for debugging, but it also means enabling trace view has a non-zero happy-path cost: every captured step pays for DOM snapshot serialization even when the test passes.

This is a proposal to add a capture policy where lightweight trace metadata is still recorded for the full timeline, but DOM snapshots are taken only when a failure is known. This is different from "retain on failure". The goal is not to record full snapshots throughout the test and discard them on pass. The goal is to keep the happy path low-cost by recording metadata only, then capture diagnostic DOM state at the point where a command/assertion/test fails.

Motivation

Browser trace view is client-driven, unlike Playwright tracing. There is no browser/provider-level tracing session to start just for turning the feature on. The meaningful local cost is snapshot capture.

There is still one global-ish cost today: trace view imports rrweb-snapshot when enabled for the attempt. For failure-gated snapshots, this can become lazy and move to the snapshot recording path so passing tests do not import the snapshot library at all.

Manual timing suggests artifact recording is mostly plumbing after snapshot capture, while takeSnapshot is often a comparable or dominant part of recordBrowserTraceEntry. A failure-gated snapshot mode is attractive because:

• passing tests avoid DOM snapshot serialization
• passing tests can avoid loading rrweb-snapshot
• failures still get high-value DOM state for replay and selector highlighting
• the model follows the same general principle as default-on failureScreenshot, but with richer trace metadata

Proposal

Initial config shape:

browser: {
  traceView: {
    enabled: true,
    snapshots: 'always' | 'on-failure',
  },
}

always preserves the current trace-view behavior.

on-failure records trace metadata for the timeline, but attaches DOM snapshots only when a failure state is known. Successful actions/assertions should not take snapshots.

This is a snapshot capture policy, not an artifact retention policy:

• retain-on-failure: record everything, keep only if the test fails. This saves artifact/UI noise, but not runtime cost.
• on-failure: record lightweight metadata during successful execution, but do not capture DOM snapshots. Capture snapshots only when failure is observed. This saves happy-path snapshot cost while preserving the timeline.

User Experience

The trace view remains useful even when snapshots are failure-gated:

• successful steps still appear in the timeline with metadata, timing, location, and selector information
• failed steps include a replayable DOM snapshot and selector highlight
• a failed test can also include a final lifecycle snapshot as fallback/final-state context

In the UI:

• full snapshot entry: show replay iframe and timing
• metadata-only entry: show step/timing and a "no snapshot captured" empty state

Future Direction

This could make default trace-view diagnostics more plausible. Browser failureScreenshot is already default-on and follows a similar cost model: capture only when a test fails. Failure-gated trace snapshots would extend that idea from pixels to replayable DOM state plus trace metadata.

Potential longer-term default:

browser: {
  traceView: {
    enabled: true,
    snapshots: 'on-failure',
  },
}

That would provide richer failure artifacts than screenshots alone while avoiding full snapshot recording cost for passing tests. Before making this default, metadata-only command overhead should be measured with the async lane in place.

Longer term, the capture policy may need more knobs:

• Metadata policy: if metadata-only entries cause noticeable RPC/server backpressure, add a way to skip successful metadata too. For example, a future metadata: 'always' | 'on-failure' option could trade timeline completeness for lower happy-path overhead.
• Snapshot filters/overrides: custom page.mark users or integrations may want specific spans to always capture snapshots even when the global policy is snapshots: 'on-failure'. This could be modeled by mark options, labels, names, or kind-based rules.

Possible future shapes:

browser: {
  traceView: {
    snapshots: 'always' | 'on-failure',
    metadata: 'always' | 'on-failure',
    capture: [
      { kind: 'mark', name: 'checkout', snapshots: 'always' },
      { label: 'critical-flow', snapshots: 'always' },
    ],
  },
}

await page.mark('checkout', { snapshot: 'always' }, async () => {
  // ...
})

These should stay out of the initial implementation unless a concrete integration needs them.

interface BrowserTraceEntry {
  // ...
  snapshot?: TraceSnapshot
}

getBrowserState().browserTraceDomSnapshot = await import('rrweb-snapshot')

async function loadBrowserTraceDomSnapshot() {
  return getBrowserState().browserTraceDomSnapshot
    ??= await import('rrweb-snapshot')
}

class AsyncLane {
  promise: Promise<void> = Promise.resolve()

  run<T>(fn: () => Promise<T>): Promise<T> {
    const result = this.promise.then(fn)
    this.promise = result.then(
      () => {},
      () => {},
    )
    return result
  }

  flush(): Promise<void> {
    return this.promise
  }
}