From 159bdb031297f0f6d31e8b9205294367f1dcca65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rene=CC=81?= <snooz@posteo.de>
Date: Thu, 17 Oct 2024 00:34:57 +0200
Subject: [PATCH] improved docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: René <snooz@posteo.de>
---
 .../src/server/trace/recorder/tracing.ts      |  1 +
 packages/playwright-core/types/types.d.ts     | 29 +++++++++++++++++--
 packages/protocol/src/protocol.yml            |  1 +
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/packages/playwright-core/src/server/trace/recorder/tracing.ts b/packages/playwright-core/src/server/trace/recorder/tracing.ts
index 6566ab8f2f..0184c1a2a5 100644
--- a/packages/playwright-core/src/server/trace/recorder/tracing.ts
+++ b/packages/playwright-core/src/server/trace/recorder/tracing.ts
@@ -280,6 +280,7 @@ export class Tracing extends SdkObject implements InstrumentationListener, Snaps
       throw new Error(`Tracing is already stopping`);
     if (this._state.recording)
       throw new Error(`Must stop trace file before stopping tracing`);
+    await this._closeAllGroups();
     this._harTracer.stop();
     this.flushHarEntries();
     await this._fs.syncAndGetError();
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 3c8bf3061d..e0ab9632e7 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -21061,10 +21061,34 @@ export interface Tracing {
   /**
    * Creates a new inline group in the trace, causing any subsequent calls to belong to this group, until
    * [tracing.groupEnd()](https://playwright.dev/docs/api/class-tracing#tracing-group-end) is called.
-   * @param name Group name shown in the trace viewer.
+   *
+   * Groups can be nested and are similar to [test.step()](https://playwright.dev/docs/api/class-test#test-step) in trace.
+   * However, groups are only visualized in the trace viewer and, unlike test.step, have no effect on the test reports.
+   *
+   * **NOTE** Groups should not be used with Playwright Test! This API is intended for Playwright API users that can not use [test.step()](https://playwright.dev/docs/api/class-test#test-step).
+   *
+   *
+   * **Usage**
+   * ```js
+   * await context.tracing.start({ screenshots: true, snapshots: true });
+   * await context.tracing.group('Open Playwright.dev');
+   * const page = await context.newPage();
+   * await page.goto('https://playwright.dev/');
+   * await context.tracing.groupEnd();
+   * await context.tracing.group('Open API Docs of Tracing');
+   * await page.getByRole('link', { name: 'API' }).click();
+   * await page.getByRole('link', { name: 'Tracing' }).click();
+   * await context.tracing.groupEnd();
+   * ```
+   *
+   * @param name Group name shown in the actions tree in trace viewer.
    * @param options
    */
   group(name: string, options?: {
+    /**
+     * Specifies a custom location for the group start to be shown in source tab in trace viewer.
+     * By default, location of the tracing.group() call is shown.
+     */
     location?: {
       /**
        * Source file path to be shown in the trace viewer source tab.
@@ -21084,7 +21108,8 @@ export interface Tracing {
   }): Promise<void>;
 
   /**
-   * Closes the last opened inline group in the trace.
+   * Closes the currently open inline group in the trace.
+   *
    */
   groupEnd(): Promise<void>;
 
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index 95c2d6f8bb..f46e973a7b 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -3176,6 +3176,7 @@ Dialog:
 
     dismiss:
 
+
 Tracing:
   type: interface