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