wip

Author: pavelfeldman

docs/src/api/class-overlay.md

@@ -0,0 +1,37 @@
+# class: Overlay
+* since: v1.59
+
+Interface for managing page overlays that display persistent visual indicators on top of the page.
+
+## async method: Overlay.add
+* since: v1.59
+- returns: <[Disposable]>
+
+Adds an overlay with the given HTML content. The overlay is displayed on top of the page until removed. Returns a disposable that removes the overlay when disposed.
+
+### param: Overlay.add.html
+* since: v1.59
+- `html` <[string]>
+
+HTML content for the overlay.
+
+## async method: Overlay.configure
+* since: v1.59
+
+Configures overlay behavior.
+
+### option: Overlay.configure.actionDelay
+* since: v1.59
+- `actionDelay` <[int]>
+
+Delay in milliseconds between actions when overlay is active.
+
+## async method: Overlay.hide
+* since: v1.59
+
+Hides all overlays without removing them. Overlays can be shown again with [`method: Overlay.show`].
+
+## async method: Overlay.show
+* since: v1.59
+
+Shows previously hidden overlays.

docs/src/api/class-page.md

@@ -2759,6 +2759,10 @@ The page's main frame. Page is guaranteed to have a main frame which persists du
 * since: v1.8
 - type: <[Mouse]>
 
+## property: Page.overlay
+* since: v1.59
+- type: <[Overlay]>
+
 ## method: Page.onceDialog
 * since: v1.10
 * langs: java

docs/src/api/class-screencast.md

@@ -42,14 +42,6 @@ If a screencast is already active (e.g. started by tracing or video recording),
 
 Defaults to 800×800.
 
-### option: Screencast.start.annotate
-* since: v1.59
-* langs: js
-- `annotate` ?<[Object]>
-  - `delay` ?<[int]> How long each annotation is displayed in milliseconds. Defaults to `500`.
-
-If specified, enables visual annotations on interacted elements during screencast. Interacted elements are highlighted with a semi-transparent blue box and click points are shown as red circles.
-
 ## async method: Screencast.stop
 * since: v1.59
 * langs: js

docs/src/api/class-video.md

@@ -144,13 +144,6 @@ Path where the video should be saved when the recording is stopped.
 
 Optional dimensions of the recorded video. If not specified the size will be equal to page viewport scaled down to fit into 800x800. Actual picture of the page will be scaled down if necessary to fit the specified size.
 
-### option: Video.start.annotate
-* since: v1.59
-- `annotate` ?<[Object]>
-  - `delay` ?<[int]> How long each annotation is displayed in milliseconds. Defaults to `500`.
-
-If specified, enables visual annotations on interacted elements during video recording. Interacted elements are highlighted with a semi-transparent blue box and click points are shown as red circles.
-
 ## async method: Video.stop
 * since: v1.59
 

docs/src/api/params.md

@@ -810,8 +810,6 @@ When set to `minimal`, only record information necessary for routing from HAR. T
     Actual picture of each page will be scaled down if necessary to fit the specified size.
     - `width` <[int]> Video frame width.
     - `height` <[int]> Video frame height.
-  - `annotate` ?<[Object]> If specified, enables visual annotations on interacted elements during video recording.
-    - `delay` ?<[int]> How long each annotation is displayed in milliseconds. Defaults to `500`.
 
 Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make
 sure to await [`method: BrowserContext.close`] for videos to be saved.

docs/src/test-api/class-testoptions.md

@@ -625,8 +625,11 @@ export default defineConfig({
   - `size` ?<[Object]> Size of the recorded video. Optional.
     - `width` <[int]>
     - `height` <[int]>
-  - `annotate` ?<[Object]> If specified, visually annotates actions in the video with element highlights and action title subtitles.
-    - `delay` ?<[int]> How long each annotation is displayed in milliseconds. Defaults to `500`.
+  - `annotate` ?<[Object]> If specified, visually annotates the video with test information and action highlights.
+    - `action` ?<[Object]> Controls visual annotations on interacted elements.
+      - `delay` ?<[int]> How long each annotation is displayed in milliseconds. Defaults to `500`.
+    - `test` ?<[Object]> Controls test information displayed as a status overlay in the video.
+      - `level` ?<[TestAnnotationLevel]<"file"|"test"|"step">> Level of the detail to include about the current test.
 
 Whether to record video for each test. Defaults to `'off'`.
 * `'off'`: Do not record video.
@@ -636,7 +639,7 @@ Whether to record video for each test. Defaults to `'off'`.
 
 To control video size, pass an object with `mode` and `size` properties. If video size is not specified, it will be equal to [`property: TestOptions.viewport`] scaled down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size.
 
-To annotate actions in the video with element highlights and action title subtitles, pass `annotate` with an optional `delay` in milliseconds (defaults to `500`).
+To annotate actions in the video, pass `annotate` with `action` and/or `test` sub-options. The `action` option controls visual highlights on interacted elements with an optional `delay` in milliseconds (defaults to `500`). The `test` option controls which test information is displayed as a status overlay.
 
 **Usage**
 

docs/src/videos.md

@@ -38,7 +38,7 @@ await context.close();
 
 You can also specify video size and annotation. The video size defaults to the viewport size scaled down to fit 800x800. The video of the viewport is placed in the top-left corner of the output video, scaled down to fit if necessary. You may need to set the viewport size to match your desired video size.
 
-When `annotate` is specified, each action will be visually highlighted in the video with the element outline and action title subtitle. The optional `delay` property controls how long each annotation is displayed (defaults to `500`ms).
+When `action` is specified, each action can be visually highlighted in the video with the element outline and action title subtitle, and test information can be shown as a status overlay. The `action` sub-option controls element highlights with an optional `delay` (defaults to `500`ms). The `test` sub-option controls which test information components are displayed.
 
 ```js tab=js-test title="playwright.config.ts"
 import { defineConfig } from '@playwright/test';
@@ -47,8 +47,11 @@ export default defineConfig({
     video: {
       mode: 'on-first-retry',
       size: { width: 640, height: 480 },
-      annotate: { delay: 500 },
-    }
+      annotate: {
+        action: { delay: 500 },
+        test: { level: 'step' },
+      },
+    },
   },
 });
 ```
@@ -58,7 +61,6 @@ const context = await browser.newContext({
   recordVideo: {
     dir: 'videos/',
     size: { width: 640, height: 480 },
-    annotate: { delay: 500 },
   }
 });
 ```

examples/todomvc/playwright.config.ts

@@ -47,7 +47,7 @@ export default defineConfig({
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: 'on-first-retry',
-    video: { mode: 'on', annotate: { delay: 500 } },
+    video: { mode: 'on', annotate: { action: { delay: 500 }, test: { level: 'step' } } },
   },
 
   /* Configure projects for major browsers */

examples/todomvc/tests/todo-creation/add-multiple-todos.spec.ts

@@ -7,30 +7,38 @@ test.describe('Todo Creation', () => {
     // 1. Navigate to the TodoMVC application
     // Expect: The page loads with an empty todo list
     await expect(page.getByRole('textbox', { name: 'What needs to be done?' })).toBeVisible();
-
-    // 2. Add first todo 'Buy groceries' by typing and pressing Enter
     const newTodoInput = page.getByRole('textbox', { name: 'What needs to be done?' });
-    await newTodoInput.fill('Buy groceries');
-    await newTodoInput.press('Enter');
-    // Expect: The first todo appears in the list
-    await expect(page.getByText('Buy groceries')).toBeVisible();
+
+    await test.step('Add first todo', async () => {
+      // 2. Add first todo 'Buy groceries' by typing and pressing Enter
+      await newTodoInput.fill('Buy groceries');
+      await newTodoInput.press('Enter');
+      // Expect: The first todo appears in the list
+      await expect(page.getByText('Buy groceries')).toBeVisible();
+    });
 
     // 3. Add second todo 'Walk the dog' by typing and pressing Enter
-    await newTodoInput.fill('Walk the dog');
-    await newTodoInput.press('Enter');
-    // Expect: The second todo appears in the list below the first
-    await expect(page.getByText('Walk the dog')).toBeVisible();
+    await test.step('Add second todo', async () => {
+      await newTodoInput.fill('Walk the dog');
+      await newTodoInput.press('Enter');
+      // Expect: The second todo appears in the list below the first
+      await expect(page.getByText('Walk the dog')).toBeVisible();
+    });
 
     // 4. Add third todo 'Read a book' by typing and pressing Enter
-    await newTodoInput.fill('Read a book');
-    await newTodoInput.press('Enter');
-    // Expect: The third todo appears in the list below the second
-    await expect(page.getByText('Read a book')).toBeVisible();
+    await test.step('Add third todo', async () => {
+      await newTodoInput.fill('Read a book');
+      await newTodoInput.press('Enter');
+      // Expect: The third todo appears in the list below the second
+      await expect(page.getByText('Read a book')).toBeVisible();
+    });
 
     // Post Conditions: All three todos are visible in the list
-    await expect(page.getByText('Buy groceries')).toBeVisible();
-    await expect(page.getByText('Walk the dog')).toBeVisible();
-    await expect(page.getByText('Read a book')).toBeVisible();
+    await test.step('Post Conditions: Verify all todos are visible', async () => {
+      await expect(page.getByText('Buy groceries')).toBeVisible();
+      await expect(page.getByText('Walk the dog')).toBeVisible();
+      await expect(page.getByText('Read a book')).toBeVisible();
+    });
 
     // Post Conditions: The todo counter shows '3 items left'
     await expect(page.getByText('3 items left')).toBeVisible();

packages/injected/src/highlight.css

@@ -107,23 +107,27 @@ x-pw-action-point {
   z-index: 2;
 }
 
-x-pw-subtitle {
+x-pw-title {
   position: absolute;
-  bottom: 55px;
-  left: 50%;
-  transform: translateX(-50%);
+  top: 6px;
+  right: 6px;
   backdrop-filter: blur(5px);
-  background-color: rgba(0, 0, 0, 0.7);
+  background-color: rgba(0, 0, 0, 0.5);
   color: white;
   border-radius: 6px;
-  padding: 6px 14px;
-  font-size: 14px;
+  padding: 6px;
+  font-size: 24px;
   line-height: 1.4;
   white-space: nowrap;
   user-select: none;
   z-index: 3;
 }
 
+x-pw-user-overlays, x-pw-user-overlay {
+  position: absolute;
+  inset: 0;
+}
+
 @keyframes pw-fade-out {
   from { opacity: 1; }
   to { opacity: 0; }