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

Signed-off-by: René <snooz@posteo.de>
---
 docs/src/api/class-tracing.md             | 31 +++++++++++++++++++++--
 packages/playwright-core/types/types.d.ts | 15 ++++++-----
 2 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/docs/src/api/class-tracing.md b/docs/src/api/class-tracing.md
index 7607b3c53b..7a19b9ef40 100644
--- a/docs/src/api/class-tracing.md
+++ b/docs/src/api/class-tracing.md
@@ -286,11 +286,35 @@ To specify the final trace zip file name, you need to pass `path` option to
 
 Creates a new inline group in the trace, causing any subsequent calls to belong to this group, until [`method: Tracing.groupEnd`] is called.
 
+Groups can be nested and are similar to `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`.
+:::
+
+**Usage**
+
+```js
+await context.tracing.start({ screenshots: true, snapshots: true });
+await context.tracing.group('Open Playwright.dev');
+// All actions between group and groupEnd will be shown in the trace viewer as a group.
+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();
+// This Trace will have two groups: 'Open Playwright.dev' and 'Open API Docs of Tracing'.
+```
+
 ### param: Tracing.group.name
 * since: v1.49
 - `name` <[string]>
 
-Group name shown in the trace viewer.
+Group name shown in the actions tree in trace viewer.
 
 ### option: Tracing.group.location
 * since: v1.49
@@ -299,10 +323,13 @@ Group name shown in the trace viewer.
   - `line` ?<[int]> Line number in the source file.
   - `column` ?<[int]> Column number in the source file
 
+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.
+
 ## async method: Tracing.groupEnd
 * since: v1.49
 
-Closes the last opened inline group in the trace.
+Closes the currently open inline group in the trace.
 
 ## async method: Tracing.stop
 * since: v1.12
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index e0ab9632e7..8a40902206 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -21062,16 +21062,17 @@ 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.
    *
-   * 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).
+   * Groups can be nested and are similar to `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** This API is intended for Playwright API users that can not use `test.step`.
    *
    * **Usage**
+   *
    * ```js
    * await context.tracing.start({ screenshots: true, snapshots: true });
    * await context.tracing.group('Open Playwright.dev');
+   * // All actions between group and groupEnd will be shown in the trace viewer as a group.
    * const page = await context.newPage();
    * await page.goto('https://playwright.dev/');
    * await context.tracing.groupEnd();
@@ -21079,6 +21080,7 @@ export interface Tracing {
    * await page.getByRole('link', { name: 'API' }).click();
    * await page.getByRole('link', { name: 'Tracing' }).click();
    * await context.tracing.groupEnd();
+   * // This Trace will have two groups: 'Open Playwright.dev' and 'Open API Docs of Tracing'.
    * ```
    *
    * @param name Group name shown in the actions tree in trace viewer.
@@ -21086,8 +21088,8 @@ export interface Tracing {
    */
   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.
+     * 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?: {
       /**
@@ -21109,7 +21111,6 @@ export interface Tracing {
 
   /**
    * Closes the currently open inline group in the trace.
-   *
    */
   groupEnd(): Promise<void>;