[Feature]: Ability to add custom annotations to trace files

[Donaim]

🚀 Feature Request

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.

Example

with page.annotate("Login test sequence"):
    page.locator("input[name='username']").fill("testuser")
    page.locator("input[name='password']").fill("password")
    page.locator("text='Log in'").click()

Motivation

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.

[Donaim]

Feature originally proposed here: #28206

That issue's log also suggests that the only way to have custom annotations currently is to use javascripts' test framework.
Nevertheless, that means that in Javascript we can have them, but not in Python.

[yury-s]

That issue's log also suggests that the only way to have custom annotations currently is to use javascripts' test framework.
Nevertheless, that means that in Javascript we can have them, but not in Python.

Is your request about particular non-JS Playwright versions or about support for such annotations in the playwright js library (as opposed to Playwright Test where you can already achieve it)?

[Donaim]

@yury-s it is about particular non-JS Playwright, specifically playwright-python.

[DetachHead]

this has been raised on playwright-python: microsoft/playwright-python#1949

[yury-s]

Folding into microsoft/playwright-python#1949