[Feature]: Custom tracing marker API with selector and snapshot

[hi-ogawa]

🚀 Feature Request

page and locator methods for inserting custom markers into Playwright traces, with optional DOM snapshot capture and selector-aware element highlighting.

await page.mark(name, { snapshot?, location? })
await locator.mark(name, { snapshot?, location? })

• page.mark(name): inserts a named timeline marker visible in Trace Viewer, with optional snapshot capture.
• locator.mark(name): same timeline marker, and also resolves the locator's selector and highlights the target element in the snapshot (if it exists).

Example

// page-level marker (snapshot, no element highlight)
await page.mark('before assertion phase', {
  location: { file: testFile, line: 42 },
  snapshot: true,
})

// locator-level marker (snapshot with element highlight)
await page.locator('#submit-button').mark('assertion target', {
  snapshot: true,
})

Motivation

We are enhancing Playwright trace support in Vitest browser mode (in vitest-dev/vitest#9652). There is currently no stable way to insert custom trace markers with snapshots or element highlighting. Our workarounds today:

// page.mark workaround — snapshot without element highlight
await context.tracing.group(name, { location })
await page.evaluate(() => 0)
await context.tracing.groupEnd()

// locator.mark workaround — snapshot with element highlight (private API)
await context.tracing.group(name, { location })
await locator._expect('to.be.attached', { isNot: false, timeout: 1 })
await context.tracing.groupEnd()

The page.evaluate(() => 0) workaround is a no-op just to trigger a snapshot-eligible action, and locator._expect(...) is a private API I just happened to find usable as workaround for element highlight. Public page.mark() / locator.mark() APIs would make this a stable, first-class capability for the broader Playwright ecosystem.

[Skn0tt]

Hi! Our Trace already contains snapshots before/after each action. You'd like a capability to additionally take these snapshots at arbitrary points in time, and assign them names. Could you give an example where that's useful?

[Skn0tt]

We already have locator.describe btw, which sounds similar to the proposed mark.

[hi-ogawa]

Thanks for pointing out locator.describe(...). I had missed that API, and it is useful for Vitest. But it is not sufficient as a replacement for the feature requested here.

The remaining gap comes from execution-model differences with Vitest Browser Mode:

• We need to insert markers at points where no Playwright action/assertion is involved. In our model, end-user test code runs fully in the browser runtime, so there isn’t always a Playwright protocol call at the point we want to anchor. For example, the render helper in vitest-browser-react (Vitest Browser Mode adaptation of Testing Library) and expect.element are browser-only mechanisms, but they are valuable trace checkpoints (including snapshots).
• Playwright trace source capture relies on Node-side stack capture, while end-user code runs in the browser runtime. We can capture browser-side user callsites, but there is no general public API to attach that location to trace events (except tracing.group today).