improved docs

Signed-off-by: René <snooz@posteo.de>

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();

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>;
 

packages/protocol/src/protocol.yml

@@ -3176,6 +3176,7 @@ Dialog:
 
     dismiss:
 
+
 Tracing:
   type: interface