Skip to content

Instantly share code, notes, and snippets.

@hi-ogawa

hi-ogawa/NOTE.md

Created August 24, 2026 04:17
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save hi-ogawa/16903b72364acac9ce87136e61dda346 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save hi-ogawa/16903b72364acac9ce87136e61dda346 to your computer and use it in GitHub Desktop.
Download ZIP
Vitest Trace View external capture notes
Raw
NOTE.md

Trace View External Capture

Goal

Rework Vitest Trace View so Vitest-owned DOM snapshots can be captured outside browser mode and displayed by the existing Vitest UI and HTML report. The motivating case is a Vitest Node test or custom E2E setup that uses the Playwright programmatic API, potentially through an injected client script.

The initial goal is not to ingest Playwright .trace.zip files or expose a general trace interchange format. Vitest owns both capture and replay.

Current Architecture

The existing feature combines several layers that are currently tied together by browser-mode state.

Vitest's Playwright tracing feature is separate. It delegates to Playwright tracing and stores .trace.zip attachments in packages/browser-playwright/src/commands/trace.ts:10. It should remain independent from the rrweb-based Trace View.

Important Coupling

Ownership Decision

A public, versioned trace-data contract is not an initial requirement. That idea incorrectly treated external consumption as third-party trace production or interoperability.

For the intended integration, Vitest owns:

  • The script injected into the page.
  • The Node-side recorder/controller.
  • The private artifact payload and transport.
  • The rrweb rebuild implementation.
  • The Vitest UI and static HTML viewer consuming the payload.

There will still be an internal wire shape between capture and replay, but both ends can evolve together. The recorder API should return or retain opaque data rather than make the snapshot schema public.

A format version may still be useful as an internal guard. A public compatibility contract only becomes necessary if Vitest later supports third-party producers, third-party viewers, standalone trace files opened by unrelated Vitest versions, or long-lived trace archives.

Target Architecture

arbitrary browser page
  -> run Vitest-owned capture script
  -> capture an opaque snapshot payload
  -> caller records trace entries against a Vitest task
  -> artifact pipeline streams or persists it
  -> Vitest UI rebuilds the snapshots

browser.traceView should control automatic collection in browser mode. It should not decide whether an existing trace artifact can be displayed. Display should be artifact-driven.

The browser-mode implementation and any future integrations should use the same low-level capture operation rather than maintain parallel rrweb capture paths.

Capture Primitive

The core primitive is a browser-side script. It captures the current document and returns an opaque, serializable snapshot payload. It does not know about Playwright, browser providers, Vitest tasks, RPC, fixtures, retries, or page lifecycle.

Illustrative browser-side shape:

const snapshot = captureTraceSnapshot({
  element: document.querySelector('button'),
})

The host records that payload separately:

await recordBrowserTrace(context.task, {
  name: 'dashboard loaded',
  kind: 'mark',
  snapshot,
})

The exact payload remains private and opaque. The browser-mode client can call the capture function directly. External integrations can inject or evaluate the same client script however they choose.

Range timing, pass or fail status, source locations, and lifecycle policy belong to the caller or a later ergonomic wrapper. The core snapshot function only needs capture options such as a browser-side DOM element, image inlining, and canvas recording.

Why Snapshot Capture Comes First

A browser-side snapshot operation is the shared capability. Higher-level steps, assertions, and lifecycle capture can all be implemented later by invoking it at the appropriate points.

One explicit snapshot through custom injection tests the difficult boundaries first:

  • Script injection by a custom integration.
  • rrweb initialization in an arbitrary page.
  • DOM and element-highlight snapshot fidelity.
  • Cross-context transfer of potentially large snapshot payloads.
  • Association with a Vitest task.
  • Live artifact transport and HTML report persistence.
  • Replay by the existing UI.

Once those work, step ranges, automatic lifecycle capture, assertions, and automation-library ergonomics are orchestration over the same snapshot operation.

Userland Spike

The first experiment should require no Vitest core changes. Userland can temporarily reproduce the private browser-trace payload and record it through the existing public artifact API. Compatibility with future Vitest versions is explicitly not a goal for the spike.

Setup

  • Run a normal Vitest test in a Node environment.
  • Launch and control a page with the Playwright programmatic API.
  • Install or evaluate userland snapshot code in that page. For a repository-local spike, reuse the workspace's patched rrweb-snapshot dependency or copy the relevant current capture logic.
  • Access the current test task through the Vitest test context and call the public recordArtifact API.

Minimal Capture

Capture the fields currently consumed by TraceView.vue:

  • serialized: the rrweb DOM snapshot.
  • viewport: page width and height.
  • scroll: page scroll position.
  • pseudoClassIds: an empty object is sufficient initially.
  • selectorId: optional and omitted for the first snapshot.

Record one complete entry with the current private envelope:

await recordArtifact(context.task, {
  type: 'internal:browserTrace',
  data: {
    retry: 0,
    repeats: 0,
    recordCanvas: false,
    entries: [{
      name: 'userland snapshot',
      kind: 'mark',
      startTime: 0,
      snapshot,
    }],
  },
})

Using the reserved internal: artifact type and reproducing private data fields is acceptable only for this disposable experiment.

Validation

  1. Run the test with Vitest UI enabled.
  2. Select the test and open its Report tab.
  3. Confirm the existing Trace View artifact button appears.
  4. Open the trace and confirm the DOM snapshot rebuilds correctly.
  5. Record another snapshot after a Playwright action and confirm both steps appear in order.
  6. Run with the HTML reporter and confirm the static report contains and replays the same snapshots.

The manual artifact button already bypasses the browser.traceView.enabled check. Live artifact transport and HTML report serialization should also work without browser-mode configuration.

Incremental Experiments

  • Add an optional DOM element to capture and store its rrweb mirror ID as selectorId to validate highlighting.
  • Emit start and end entries with the same range ID to validate duration merging and in-progress display.
  • Validate source navigation through generic artifact location metadata as described below.
  • Capture final page state during normal fixture teardown.
  • Try retries with explicit retry values only after the single-attempt path works.

Location Metadata Plan

Trace recording should reuse the generic recordArtifact location mechanism rather than introduce a trace-specific stack parser or runtime RPC.

The userland recorder can use vi.defineHelper around the stock artifact call:

const recordTrace = vi.defineHelper(async (task, data) => {
  await recordArtifact(task, {
    type: 'internal:browserTrace',
    data,
  })
})

The intended metadata flow is:

  1. vi.defineHelper marks the boundary between recorder internals and the user call site.
  2. recordArtifact resolves that call site and stores it as artifact.location.
  3. Trace View uses artifact.location as the fallback for an entry without an explicit entry.location.
  4. Existing trace source navigation and editor markers consume the resulting entry location.

There is a separate generic issue to resolve first: recordArtifact currently probes its raw stack through findTestFileStackTrace, while vi.defineHelper frame removal lives in the standard parseStacktrace pipeline. Stock recordArtifact and vi.defineHelper should compose regardless of Trace View. That generic behavior is being investigated separately.

The trace-specific change should remain in UI normalization. getTraceAttemptMap currently extracts artifact.data and discards the enclosing artifact location. When flattening trace entries, it should preserve an explicit browser-mode entry.location and otherwise inherit the artifact location:

location: entry.location ?? artifact.location

This mapping relies on the current one-entry-per-artifact transport. That is also the natural model for streamed userland entries. If entries are batched later, each entry will need its own location or the batch must intentionally share one location.

Full editor integration also requires loosening the UI gutter condition. ViewEditor.vue currently configures trace gutters only when browser.traceView.enabled. Gutter availability should instead follow an active trace or available trace artifacts so a Node-environment trace can show markers.

The spike should cover location behavior in both live UI and the HTML report:

  • Call a trace recorder wrapped with vi.defineHelper from a known test line.
  • Select the corresponding trace step and verify the source editor opens at that call line.
  • Verify the trace gutter marker appears and tracks the selected step.
  • Keep browser-mode entries with explicit locations unchanged.

No dedicated trace runtime location API is planned. A future helper may hide the private trace artifact envelope, but call-site resolution should remain generic artifact behavior.

Success Criteria

  • A Node-environment Vitest test using programmatic Playwright can add trace entries without browser mode.
  • The existing live UI and HTML reporter replay those entries without modification.
  • Multiple snapshots preserve order and basic timing.
  • The spike identifies whether rrweb payload transfer, report size, CSP, navigation, or snapshot fidelity creates a blocker.

Expected Limitations

  • The spike depends on a private payload shape and may break on any Vitest update.
  • It uses a reserved artifact discriminator without a sanctioned public helper.
  • Injection, navigation persistence, task association, ranges, source locations, and teardown are userland responsibilities.
  • Basic snapshots may omit pseudo-state, image inlining, canvas pixels, selector highlighting, and external resources.
  • Timeouts, cancellation, worker termination, and browser crashes may lose the final snapshot.

Core Decision After The Spike

If the spike works, core changes can remain focused on productization rather than feasibility. The first decisions are whether to sanction artifact recording, make trace discovery fully artifact-driven, and extract the owned capture script. If it does not work, make only the smallest core adjustment demonstrated by the failure.

Staged Plan

This is a possible productization plan after the userland spike. It is not required to start the experiment.

Stage 1: Decouple Capture

  • Extract a self-contained browser capture runtime from the current browser-state-dependent takeSnapshot implementation.
  • Expose one browser-side snapshot operation with capture options and an optional DOM element to highlight.
  • Keep injection, evaluation, range orchestration, and task association outside the capture runtime.
  • Keep the internal snapshot representation private and reuse the patched rrweb behavior required by the current viewer.
  • Add a Vitest-side helper that accepts the opaque snapshot plus entry metadata and records the existing internal artifact.

Stage 2: Artifact-Driven Viewing

  • Let the UI recognize and open trace artifacts even when the test project did not enable browser.traceView.
  • Separate collection configuration from rendering capability.
  • Reuse the existing attempt grouping and range normalization.
  • Extract only the replay operation from TraceView.vue if needed so it consumes opaque normalized trace data without browser-mode assumptions.
  • Keep Vitest-specific selection, URL persistence, source navigation, and editor markers in the UI host layer.

Stage 3: Rebase Browser Mode On The Primitive

  • Route existing browser-mode actions, assertions, marks, and final lifecycle snapshots through the same recorder core.
  • Retain browser-mode-specific instrumentation in CommandsManager and the browser runner.
  • Remove duplicate assumptions from the generic capture layer, especially current-task lookup and direct RPC access.
  • Confirm retries, repeats, nested ranges, failures, and live in-progress entries preserve current behavior.

The core extraction ends here. Everything below is optional future ergonomics and does not shape the capture primitive.

Future Ergonomics

Rstest provides relevant prior art in @rstest/playwright. It keeps tests in the Rstest Node runner while exposing Playwright-style test, fixtures, and retrying assertions:

import { expect, test } from '@rstest/playwright'

test('page title', async ({ page }) => {
  await page.goto('https://example.com')
  await expect(page).toHaveTitle(/Example/)
  await expect(page.locator('h1')).toHaveText('Example Domain')
})

Its fixture model shares a browser within a worker and creates a context and page per test. Its expect retains normal runner assertions while recognizing Playwright Page and Locator values for retrying E2E assertions. This demonstrates that Playwright-like ergonomics can be layered onto a Vitest-style runner without adopting Playwright Test as the runner.

Rstest also keeps Playwright's official .trace.zip capture separate from its runner fixtures and assertions. That supports the same separation here: Vitest Trace View capture can remain its own rrweb feature even if a future Playwright-oriented package also offers Playwright-native tracing.

Playwright Fixture

First introduce a Playwright-specific controller only when working on ergonomic integration. It can own script injection, page.evaluate, Playwright locator resolution, step ranges, and automatic artifact submission.

Then provide a Vitest fixture that mirrors the familiar Playwright page fixture while initializing and finalizing the controller automatically.

Illustrative shape:

const test = base.extend({
  page: async ({ page }, use, context) => {
    const tracedPage = await createTracedPage(page, context.task)
    await use(tracedPage)
    await tracedPage.trace.finish()
  },
})

The fixture can provide automatic final snapshots and attachment during teardown without requiring a custom runner. Its limits around hard timeouts, crashes, interrupted teardown, and retries should be evaluated before promising complete lifecycle coverage.

E2E Assertions

  • Add page and locator assertions suited to Node-side Playwright E2E tests.
  • Record assertion start and end snapshots, status, timing, highlighted locator, and source location.
  • Model the ergonomics after browser-mode expect.element, but emit through the generic recorder.
  • Avoid coupling the recorder core to a particular assertion library.

Runner Integration

Consider a dedicated Vitest runner or runner extension if fixtures cannot reliably cover test start, retries, final snapshots, failures, timeouts, cancellation, browser crashes, and unfinished trace operations.

The runner should orchestrate the same recorder primitive. It should not introduce a second capture or artifact format.

Optional Action Instrumentation

Evaluate selective wrapping of common Playwright Page and Locator operations after the explicit and assertion APIs establish expected behavior. Full transparent wrapping should not be an initial requirement because it would closely track Playwright's surface and internals.

Potential Core Vertical Slice

  1. Extract an injectable browser capture script with no Playwright or runner dependency.
  2. Use a small test-only custom injection to capture one explicit snapshot from a normal Vitest Node test.
  3. Record the opaque result against context.task using a dedicated helper over recordArtifact.
  4. Make the Vitest UI display the artifact without browser configuration.
  5. Verify the same result in the static HTML reporter.
  6. Verify browser mode can call the same capture operation without changing existing trace behavior.

This vertical slice productizes the path already validated by the userland spike while leaving step orchestration, Playwright adapters, fixtures, assertions, and runner ergonomics for later iterations.

Initial Decisions

Client Script First

The core is an injectable browser-side capture script. It has no Playwright Page assumption and no generic automation-host abstraction. Each caller decides how to load and invoke it.

Stream Existing Artifacts

Record each completed entry through the existing one-artifact-per-entry path. This preserves live UI updates and avoids introducing a second assembly model. The capture script only returns snapshot data; the caller decides when an entry is complete.

Defer Page Lifecycle

The core has no recorder-to-page lifecycle. Navigation persistence, page replacement, popups, additional tabs, frames, and browser-context-wide traces belong to custom injection code or the later Playwright controller.

Caller Owns Entry Metadata

The capture script produces snapshot data only. The caller supplies names, kinds, range IDs, timing, status, and optional stacks or locations when recording an entry. Future wrappers should capture stacks at the user-facing API call and resolve them through Vitest's existing source-map machinery.

Accept Browser DOM Elements

The capture script accepts an optional browser-side DOM element and records its rrweb mirror ID. Translating Ivya selectors, Playwright locators, or another host's locator objects into that element belongs outside the core. The replay UI continues to highlight by mirror ID and remains provider-independent.

Defer Teardown Guarantees

The capture script has no teardown responsibility. Normal completion, hard timeouts, cancellation, worker termination, browser crashes, and emergency flushing belong to custom integration code, fixtures, or the later runner integration.

Keep Inline Storage

Keep snapshots inline in trace artifacts until report size or transport measurements demonstrate a problem. Do not introduce a trace bundle, binary attachment, or resource store in the first implementation.

Non-Goals For The Primitive

  • Parsing or translating Playwright .trace.zip files.
  • Replacing Playwright Trace Viewer.
  • Exposing rrweb's serialized representation as a stable public API.
  • Supporting third-party trace renderers.
  • Automatically intercepting every Playwright operation.
  • Solving general network and external-resource replay in the first iteration.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment