Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
60327c6
feat(browser): print trace timeline on test failure
hi-ogawa Oct 15, 2026
f42afd5
refactor: drop gap rows from trace timeline
hi-ogawa Oct 15, 2026
6734c3e
refactor: show trace attempt only for retries and repeats
hi-ogawa Oct 15, 2026
3f9ad7d
refactor: drop test finished row from trace timeline
hi-ogawa Oct 15, 2026
ce5532d
refactor: add header row to trace timeline
hi-ogawa Oct 15, 2026
e4a8e37
refactor: share trace types and attempt grouping
hi-ogawa Oct 15, 2026
d504c13
Revert "refactor: share trace types and attempt grouping"
hi-ogawa Oct 15, 2026
dfc1db1
fix: print trace timeline once per test
hi-ogawa Oct 16, 2026
f49e2a9
Revert "fix: print trace timeline once per test"
hi-ogawa Oct 16, 2026
1d85bfb
docs: document trace timeline in failure output
hi-ogawa Oct 16, 2026
b0588c3
refactor: separate trace utils copied from ui
hi-ogawa Oct 16, 2026
f437e4e
test: snapshot all printed trace timelines
hi-ogawa Oct 16, 2026
6c155e0
test: add todo for per-attempt trace timeline
hi-ogawa Oct 16, 2026
d77fa40
test: use runInlineBrowserTests in trace timeline spec
hi-ogawa Oct 16, 2026
1b12f3d
feat: drop total duration from trace timeline header
hi-ogawa Oct 16, 2026
1911870
docs: link trace view guide from config intro
hi-ogawa Oct 16, 2026
0abe37d
test: remove trace timeline test without trace view
hi-ogawa Oct 16, 2026
656394a
test: remove trace timeline test without recorded steps
hi-ogawa Oct 16, 2026
fc421b2
docs: shorten trace timeline description
hi-ogawa Oct 16, 2026
63e909a
feat: show trace timeline as a step tree
hi-ogawa Oct 16, 2026
50d40cf
test: keep trace timeline snapshots aligned
hi-ogawa Oct 16, 2026
4e65964
test: cover trace timeline step cap
hi-ogawa Oct 16, 2026
b9cd11d
refactor: rename trace timeline cell color helper
hi-ogawa Oct 16, 2026
5b99c7a
feat: right-align trace timeline times in milliseconds
hi-ogawa Oct 19, 2026
16cbe97
fix: avoid trailing spaces in trace timeline rows
hi-ogawa Oct 19, 2026
7b6001b
docs: show trace timeline example with colors
hi-ogawa Oct 19, 2026
bba08db
docs: title trace timeline example and use red FAIL text
hi-ogawa Oct 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/config/browser/traceview.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ outline: deep
- **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.
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({
Expand Down
24 changes: 24 additions & 0 deletions docs/guide/browser/snippets/trace-failure.ansi
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
FAIL src/sign-in.test.ts > signs in
Error: expect(element).toHaveTextContent()

Expected element to have text content:
 Welcome
Received:
 Sign in

 ❯ src/sign-in.test.ts:11:51
 9| })
 10| await page.getByRole('button', { name: 'Sign in' }).click()
 11| await expect.element(page.getByRole('heading')).toHaveTextContent('Welcome')
 | ^
 12| })

Caused by: Error: Matcher did not succeed in time.

Trace:
 step locator start duration location
fill form -  +1ms 58ms src/sign-in.test.ts:6:14
├── fill getByLabel('Email')  +2ms 31ms src/sign-in.test.ts:7:40
└── fill getByLabel('Password')  +34ms 24ms src/sign-in.test.ts:8:43
click getByRole('button', { name: 'Sign in' }) +61ms 18ms src/sign-in.test.ts:10:55
 toHaveTextContent [ERROR] getByRole('heading')  +80ms 1003ms src/sign-in.test.ts:11:16
13 changes: 11 additions & 2 deletions docs/guide/browser/trace-view.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

`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.
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.

::: tip Trace view, browser UI, and HTML reports

Expand Down Expand Up @@ -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).
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).

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.

Expand Down Expand Up @@ -81,6 +81,7 @@ TODO: The browser UI / Vitest UI / browser driver combinations are not specific
| 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. |

## Relation to Playwright Traces

Expand All @@ -107,6 +108,14 @@ Each entry captures the DOM state at that point, along with timing information,

In Vitest UI, trace entries are streamed as the test runs, so you can inspect recorded steps before the test finishes. Long-running actions, `expect.element(...)` assertions, and callback `page.mark()` entries appear as in-progress steps first, then update with their final status and duration.

## Failure Output

When a test fails, the error in the terminal is followed by a timeline of its recorded steps:

<<< ./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.

## Custom Trace Entries

You can insert your own named entries with `page.mark()` and `locator.mark()`:
Expand Down
11 changes: 11 additions & 0 deletions packages/vitest/src/node/reporters/base.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ import {
renderBenchmarkRow,
} from './renderers/benchmark-table'
import { F_CHECK, F_DOWN_RIGHT, F_POINTER } from './renderers/figures'
import { formatTraceTimeline } from './renderers/trace-timeline'
import {
countTestErrors,
divider,
Expand Down Expand Up @@ -1527,6 +1528,16 @@ export abstract class BaseReporter implements Reporter {
screenshotPaths,
})

// TODO: print the trace of the attempt that produced this error instead of the last attempt,
// using `task.result.attempts` (https://github.com/vitest-dev/vitest/pull/11232)
for (const task of tasks) {
const timeline =
task.type === 'test' && formatTraceTimeline(task.artifacts, this.ctx.config.root)
if (timeline) {
this.error(`${timeline}\n`)
}
}

if (tasks[0].type === 'test' && tasks[0].annotations.length) {
const test = this.ctx.state.getReportedEntity(tasks[0]) as TestCase
this.printAnnotations(test, 'error', 1)
Expand Down
207 changes: 207 additions & 0 deletions packages/vitest/src/node/reporters/renderers/trace-timeline.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
import type { TestArtifact } from '../../../runtime/runner/types'
import { relative } from 'pathe'
import c from 'tinyrainbow'
import { F_TREE_NODE_END, F_TREE_NODE_MIDDLE } from './figures'

interface TimelineRow {
cells: [name: string, locator: string, start: string, duration: string, location: string]
status?: 'pass' | 'fail'
}

const MAX_STEPS = 10

export function formatTraceTimeline(artifacts: TestArtifact[], root: string): string | undefined {
const attempt = [...getTraceAttemptMap(artifacts).values()].at(-1)
if (!attempt) {
return
}

// the test end is already shown by the error location
const visible = attempt.entries.filter((step) => step.name !== 'vitest:onAfterRetryTask')
if (!visible.length) {
return
}
const shown = visible.slice(-MAX_STEPS)
const prefixes = getTreePrefixes(shown)
const headerRow: TimelineRow = { cells: ['step', 'locator', 'start', 'duration', 'location'] }
const rows = [headerRow, ...shown.map((step, i) => formatStep(step, prefixes[i], root))]

const widths = headerRow.cells.map((_, i) => Math.max(...rows.map((row) => row.cells[i].length)))
const lines = rows.map((row) => {
// the last column is left unpadded so rows have no trailing spaces inside its color codes
const [name, locator, start, duration, location] = row.cells.map((cell, i) =>
i === 4 ? cell : i === 2 || i === 3 ? cell.padStart(widths[i]) : cell.padEnd(widths[i]),
)
if (row === headerRow) {
return c.dim(` ${name} ${locator} ${start} ${duration} ${location}`)
}
const text = ` ${name} ${colorCell(locator, c.cyan)} ${start} ${colorCell(duration)} ${colorCell(location, c.dim)}`
return row.status === 'fail' ? c.red(text) : text
})
const omitted = visible.length - shown.length
if (omitted) {
lines.splice(1, 0, c.dim(` ... ${omitted} earlier ${omitted === 1 ? 'step' : 'steps'}`))
}

const header: string[] = []
if (attempt.retry) {
header.push(`retry ${attempt.retry}`)
}
if (attempt.repeats) {
header.push(`repeat ${attempt.repeats}`)
}
const title = header.length ? `Trace (${header.join(', ')}):` : 'Trace:'
return [`\n${title}`, ...lines].join('\n')
}

function getTreePrefixes(steps: NormalizedBrowserTraceEntry[]): string[] {
const hasNextSibling = steps.map((step, i) => {
const next = steps.slice(i + 1).find((other) => other.depth <= step.depth)
return next?.depth === step.depth
})
const lastAtDepth: number[] = []
return steps.map((step, i) => {
lastAtDepth[step.depth] = i
if (step.depth === 0) {
return ''
}
let prefix = ''
for (let level = 1; level < step.depth; level++) {
prefix += hasNextSibling[lastAtDepth[level]] ? '│ ' : ' '
}
return `${prefix}${hasNextSibling[i] ? F_TREE_NODE_MIDDLE : F_TREE_NODE_END} `
})
}

function formatStep(step: NormalizedBrowserTraceEntry, prefix: string, root: string): TimelineRow {
const location =
step.location &&
`${relative(root, step.location.file)}:${step.location.line}:${step.location.column}`
return {
cells: [
`${prefix}${formatStepName(step.name)}`,
step.element?.locator || '-',
`+${formatMs(step.startTime)}`,
step.duration == null ? '-' : formatMs(step.duration),
location || '-',
],
status: step.status,
}
}

function colorCell(cell: string, format = (text: string) => text): string {
return cell.trim() === '-' ? c.dim(cell) : format(cell)
}

function formatMs(ms: number): string {
return `${Math.round(ms)}ms`
}

function formatStepName(name: string): string {
return name.startsWith('vitest:') ? name.slice('vitest:'.length) : name
}

// TODO: everything below is copied from `BrowserTraceData`/`BrowserTraceEntry` in
// packages/browser/src/client/tester/trace.ts (only the fields used here) and
// `getTraceAttemptMap` in packages/ui/client/composables/trace-view.ts.
// share them instead (https://github.com/vitest-dev/vitest/pull/11604)

interface BrowserTraceData {
retry: number
repeats: number
entries: BrowserTraceEntry[]
}

interface BrowserTraceEntry {
name: string
range?: { id: string; phase: 'start' | 'end' }
status?: 'pass' | 'fail'
startTime: number
duration?: number
location?: { file: string; line: number; column: number }
element?: { locator: string }
}

interface NormalizedBrowserTraceData extends BrowserTraceData {
entries: NormalizedBrowserTraceEntry[]
}

interface NormalizedBrowserTraceEntry extends BrowserTraceEntry {
depth: number
}

function getTraceAttemptKey(trace: BrowserTraceData): string {
return `${trace.repeats}:${trace.retry}`
}

function normalizeTraceEntries(entries: BrowserTraceEntry[]): NormalizedBrowserTraceEntry[] {
const merged: NormalizedBrowserTraceEntry[] = []
const startMap = new Map<string, number>()
const parents: string[] = []

for (const entry of entries) {
const range = entry.range
if (!range) {
merged.push({
...entry,
depth: parents.length,
})
continue
}

if (range.phase === 'start') {
startMap.set(range.id, merged.length)
merged.push({
...entry,
depth: parents.length,
})
parents.push(range.id)
continue
}

// when range.phase === 'end'
const index = startMap.get(range.id)
if (index == null) {
// unpaired range shouldn't happen but just leave it there
merged.push({ ...entry, depth: 0 })
continue
}

// Keep the start timestamp for positioning, but derive display duration
// from the end event timestamp.
const start = merged[index]
merged[index] = {
...start,
...entry,
startTime: start.startTime,
duration: entry.startTime - start.startTime,
}
parents.pop()
}

return merged
}

function getTraceAttemptMap(artifacts: TestArtifact[]): Map<string, NormalizedBrowserTraceData> {
const grouped: Record<string, BrowserTraceData[]> = {}
for (const artifact of artifacts) {
if (artifact.type !== 'internal:browserTrace') {
continue
}
const trace = artifact.data as BrowserTraceData
const key = getTraceAttemptKey(trace)
grouped[key] ??= []
grouped[key].push(trace)
}

const merged = new Map<string, NormalizedBrowserTraceData>()
for (const [key, traces] of Object.entries(grouped)) {
const trace = traces[0]
const entries = traces.flatMap((trace) => trace.entries)
merged.set(key, {
...trace,
entries: normalizeTraceEntries(entries),
})
}
return merged
}
Loading