[Feature] Ability to add custom annotations to trace files

[minhhai2209]

I would like to propose a feature for the Playwright tracing facility that allows users to add custom annotations (free text) to trace files. Currently, Playwright's tracing capabilities automatically record actions like page.navigate, page.click, etc. While this is incredibly useful, the ability to insert custom annotations would enhance the trace's usefulness and readability, especially for complex scenarios.

Use Case and Benefits

In many testing and debugging scenarios, it's beneficial to have context-specific information that explains why certain actions are taken or to mark important checkpoints in the trace. Custom annotations can serve as explanatory notes or markers within the trace file, making it easier to understand the flow, especially when sharing these traces with other team members.

For instance, a test might involve a series of steps with conditional logic, and being able to annotate the trace with information like "Starting Section A tests" or "Conditional logic X triggered" would be valuable.

Suggested Implementation

The implementation could be a simple API method, such as page.annotateTrace("Your annotation here"), which inserts the given text into the trace at the point where the method is called. These annotations should be visible when viewing the trace file in a compatible viewer.

Example:

page.annotateTrace("Starting login test sequence");
page.fill("input[name='username']", "testuser");
page.fill("input[name='password']", "password");
page.click("text='Log in'");
page.annotateTrace("Login test sequence completed");

In this example, the annotations provide clear markers that denote the beginning and end of a login test sequence, which would be reflected in the trace viewer.

[mxschmitt]

Have you tried custom annotations inside your test or wrapping your logic steps inside test.step? I think the latter would fit very well for your use-case.

[minhhai2209]

Thank you @mxschmitt. Unfortunately, we are not using the Playwright Test framework, and changing the test framework is not an option for me currently. But this is still a great hint for me - I'll take a look at the Playwright Test source code. Do you have any extra suggestions?

[mxschmitt]

Closing as per above then. We recommend annotations and then they get surfaced in HTML as well. We strongly recommend Playwright's test-runner, since you will miss features like HTML Report, retries, VS Code extension, UI Mode etc.

[coty]

Have you tried custom annotations inside your test or wrapping your logic steps inside test.step? I think the latter would fit very well for your use-case.

@mxschmitt We're trying to do this from a Java test. Any thoughts on how non-JS frameworks should work with this?

[mxschmitt]

Sounds like microsoft/playwright-java#1416, there are no plans as of today to add it but feel free to comment there / upvote it there.