microsoft / microsoft/playwright

[Feature]: Add optional params to tracing.group() for structured metadata

Open
#42,081 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

P3-collecting-feedback
Dominant language
TypeScript
Stars
96.3k
Forks
6.5k
Avg merge
1d 6h
Merged PRs (30d)
180

Description

### 🚀 Feature Request

Add an optional `params?: Record` field to `tracing.group()` so library users can attach small, structured, machine-readable metadata to a logical trace group.

Today `tracing.group()` accepts a name and optional location, while the corresponding `BeforeActionTraceEvent.params` is always recorded as `{}`. The trace event already supports a params map, and Trace Viewer's Call tab already renders action parameters. Passing optional group params through the existing channel and recorder would therefore make structured group annotations visible without requiring a new trace format or custom viewer behavior.

The proposed change is additive:

- add an optional object to the `tracingGroup` protocol command;
- expose it on the public `tracing.group()` options;
- forward it through the dispatcher and recorder into `BeforeActionTraceEvent.params`;
- document the option and add a hermetic trace assertion.

Existing callers and traces remain unchanged, and older viewers can ignore populated params.

### Example

```ts
await context.tracing.start({ screenshots: true, snapshots: true });

using group = await context.tracing.group('checkout decision', {
params: {
actor: 'shopper-42',
step: 7,
decision: 'continue',
confidence: 0.91,
},
});

await page.getByRole('button', { name: 'Continue' }).click();
```

Selecting the group in Trace Viewer would show these values in the existing Parameters section. Callers would remain responsible for keeping metadata small and excluding sensitive values, as they are for trace titles and attachments today.

### Motivation

String titles are useful for people but brittle for tools. Structured group metadata would support generic use cases such as:

- AI-assisted browser orchestration recording a safe high-level decision category and correlation identifiers;
- custom reporters attaching typed metadata to logical steps;
- observability tooling correlating trace groups with external spans or workflow stages;
- test libraries adding domain-neutral annotations without encoding JSON into group titles.

The underlying event and viewer rendering paths already exist, so this provides a small public seam instead of requiring consumers to overload titles or maintain viewer forks.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the public tracing.group() options and the tracingGroup protocol command, then follow the existing dispatcher and recorder path to BeforeActionTraceEvent.params. Update the documented API and add the requested hermetic trace assertion. Done means optional group metadata reaches the event and appears in the existing Trace Viewer Parameters section while callers without params remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
playwright, typescript
Domain
observability, testing-qa
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.