feat(tracing): add tracing.startHar / tracing.stopHar

Adds on-demand HAR recording to `Tracing`, available on both
`BrowserContext.tracing` and `APIRequestContext.tracing`. Unlike
`recordHar`, this can be scoped to an individual flow via explicit
start/stop calls.

Author: dgozman

docs/src/api/class-apirequestcontext.md

@@ -896,3 +896,7 @@ Returns storage state for this request context, contains current cookies and loc
 - `indexedDB` ?<boolean>
 
 Set to `true` to include IndexedDB in the storage state snapshot.
+
+## property: APIRequestContext.tracing
+* since: v1.60
+- type: <[Tracing]>

docs/src/api/class-tracing.md

@@ -303,6 +303,74 @@ given name prefix inside the [`option: BrowserType.launch.tracesDir`] directory
 To specify the final trace zip file name, you need to pass `path` option to
 [`method: Tracing.stopChunk`] instead.
 
+## async method: Tracing.startHar
+* since: v1.60
+
+Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when [`method: Tracing.stopHar`] is called.
+
+Only one HAR recording can be active at a time per [BrowserContext].
+
+**Usage**
+
+```js
+await context.tracing.startHar('trace.har');
+const page = await context.newPage();
+await page.goto('https://playwright.dev');
+await context.tracing.stopHar();
+```
+
+```java
+context.tracing().startHar(Paths.get("trace.har"));
+Page page = context.newPage();
+page.navigate("https://playwright.dev");
+context.tracing().stopHar();
+```
+
+```python async
+await context.tracing.start_har("trace.har")
+page = await context.new_page()
+await page.goto("https://playwright.dev")
+await context.tracing.stop_har()
+```
+
+```python sync
+context.tracing.start_har("trace.har")
+page = context.new_page()
+page.goto("https://playwright.dev")
+context.tracing.stop_har()
+```
+
+```csharp
+await context.Tracing.StartHarAsync("trace.har");
+var page = await context.NewPageAsync();
+await page.GotoAsync("https://playwright.dev");
+await context.Tracing.StopHarAsync();
+```
+
+### param: Tracing.startHar.path
+* since: v1.60
+- `path` <[path]>
+
+Path on the filesystem to write the HAR file to. If the file name ends with `.zip`, the HAR is saved as a zip archive with response bodies attached as separate files.
+
+### option: Tracing.startHar.content
+* since: v1.60
+- `content` <[HarContentPolicy]<"omit"|"embed"|"attach">>
+
+Optional setting to control resource content management. If `omit` is specified, content is not persisted. If `attach` is specified, resources are persisted as separate files or entries in the ZIP archive. If `embed` is specified, content is stored inline the HAR file as per HAR specification. Defaults to `attach` for `.zip` output files and to `embed` for all other file extensions.
+
+### option: Tracing.startHar.mode
+* since: v1.60
+- `mode` <[HarMode]<"full"|"minimal">>
+
+When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`.
+
+### option: Tracing.startHar.urlFilter
+* since: v1.60
+- `urlFilter` <[string]|[RegExp]>
+
+A glob or regex pattern to filter requests that are stored in the HAR. Defaults to none.
+
 ## async method: Tracing.group
 * since: v1.49
 - returns: <[Disposable]>
@@ -400,3 +468,8 @@ Stop the trace chunk. See [`method: Tracing.startChunk`] for more details about
 - `path` <[path]>
 
 Export trace collected since the last [`method: Tracing.startChunk`] call into the file with the given path.
+
+## async method: Tracing.stopHar
+* since: v1.60
+
+Stop HAR recording and save the HAR file to the path given to [`method: Tracing.startHar`].

packages/isomorphic/protocolMetainfo.ts

@@ -96,8 +96,6 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([
   ['BrowserContext.disableRecorder', { internal: true, }],
   ['BrowserContext.exposeConsoleApi', { internal: true, }],
   ['BrowserContext.newCDPSession', { title: 'Create CDP session', group: 'configuration', }],
-  ['BrowserContext.harStart', { internal: true, }],
-  ['BrowserContext.harExport', { internal: true, }],
   ['BrowserContext.createTempFiles', { internal: true, }],
   ['BrowserContext.updateSubscription', { internal: true, }],
   ['BrowserContext.clockFastForward', { title: 'Fast forward clock "{ticksNumber|ticksString}"', }],
@@ -289,6 +287,8 @@ export const methodMetainfo = new Map<string, MethodMetainfo>([
   ['Tracing.tracingGroupEnd', { title: 'Group end', }],
   ['Tracing.tracingStopChunk', { title: 'Stop tracing', group: 'configuration', }],
   ['Tracing.tracingStop', { title: 'Stop tracing', group: 'configuration', }],
+  ['Tracing.harStart', { internal: true, }],
+  ['Tracing.harExport', { internal: true, }],
   ['Artifact.pathAfterFinished', { internal: true, }],
   ['Artifact.saveAs', { internal: true, }],
   ['Artifact.saveAsStream', { internal: true, }],

packages/playwright-client/types/types.d.ts

@@ -19116,6 +19116,8 @@ export interface APIRequestContext {
     }>;
   }>;
 
+  tracing: Tracing;
+
   [Symbol.asyncDispose](): Promise<void>;
 }
 
@@ -22148,6 +22150,47 @@ export interface Tracing {
     title?: string;
   }): Promise<void>;
 
+  /**
+   * Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when
+   * [tracing.stopHar()](https://playwright.dev/docs/api/class-tracing#tracing-stop-har) is called.
+   *
+   * Only one HAR recording can be active at a time per
+   * [BrowserContext](https://playwright.dev/docs/api/class-browsercontext).
+   *
+   * **Usage**
+   *
+   * ```js
+   * await context.tracing.startHar('trace.har');
+   * const page = await context.newPage();
+   * await page.goto('https://playwright.dev');
+   * await context.tracing.stopHar();
+   * ```
+   *
+   * @param path Path on the filesystem to write the HAR file to. If the file name ends with `.zip`, the HAR is saved as a zip
+   * archive with response bodies attached as separate files.
+   * @param options
+   */
+  startHar(path: string, options?: {
+    /**
+     * Optional setting to control resource content management. If `omit` is specified, content is not persisted. If
+     * `attach` is specified, resources are persisted as separate files or entries in the ZIP archive. If `embed` is
+     * specified, content is stored inline the HAR file as per HAR specification. Defaults to `attach` for `.zip` output
+     * files and to `embed` for all other file extensions.
+     */
+    content?: "omit"|"embed"|"attach";
+
+    /**
+     * When set to `minimal`, only record information necessary for routing from HAR. This omits sizes, timing, page,
+     * cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to `full`.
+     */
+    mode?: "full"|"minimal";
+
+    /**
+     * A glob or regex pattern to filter requests that are stored in the HAR. Defaults to none.
+     */
+    urlFilter?: string|RegExp;
+  }): Promise<void>;
+
   /**
    * Stop tracing.
    * @param options
@@ -22173,6 +22216,12 @@ export interface Tracing {
      */
     path?: string;
   }): Promise<void>;
+
+  /**
+   * Stop HAR recording and save the HAR file to the path given to
+   * [tracing.startHar(path[, options])](https://playwright.dev/docs/api/class-tracing#tracing-start-har).
+   */
+  stopHar(): Promise<void>;
 }
 
 /**

packages/playwright-core/src/client/browserContext.ts

@@ -19,7 +19,6 @@ import { headersObjectToArray } from '@isomorphic/headers';
 import { urlMatchesEqual } from '@isomorphic/urlMatch';
 import { isRegExp, isString } from '@isomorphic/rtti';
 import { rewriteErrorMessage } from '@isomorphic/stackTrace';
-import { Artifact } from './artifact';
 import { Browser } from './browser';
 import { CDPSession } from './cdpSession';
 import { ChannelOwner } from './channelOwner';
@@ -76,7 +75,6 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
   readonly clock: Clock;
 
   readonly _serviceWorkers = new Set<Worker>();
-  private _harRecorders = new Map<string, { path: string, content: 'embed' | 'attach' | 'omit' | undefined }>();
   private _closingStatus: 'none' | 'closing' | 'closed' = 'none';
   private _closeReason: string | undefined;
   private _harRouters: HarRouter[] = [];
@@ -179,7 +177,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
     if (!recordHar)
       return;
     const defaultContent = recordHar.path.endsWith('.zip') ? 'attach' : 'embed';
-    await this._recordIntoHAR(recordHar.path, null, {
+    await this.tracing._recordIntoHAR(recordHar.path, null, {
       url: recordHar.urlFilter,
       updateContent: recordHar.content ?? (recordHar.omitContent ? 'omit' : defaultContent),
       updateMode: recordHar.mode ?? 'full',
@@ -384,27 +382,12 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
     await this._updateWebSocketInterceptionPatterns({ title: 'Route WebSockets' });
   }
 
-  async _recordIntoHAR(har: string, page: Page | null, options: { url?: string | RegExp, updateContent?: 'attach' | 'embed' | 'omit', updateMode?: 'minimal' | 'full'} = {}): Promise<void> {
-    const { harId } = await this._channel.harStart({
-      page: page?._channel,
-      options: {
-        zip: har.endsWith('.zip'),
-        content: options.updateContent ?? 'attach',
-        urlGlob: isString(options.url) ? options.url : undefined,
-        urlRegexSource: isRegExp(options.url) ? options.url.source : undefined,
-        urlRegexFlags: isRegExp(options.url) ? options.url.flags : undefined,
-        mode: options.updateMode ?? 'minimal',
-      },
-    });
-    this._harRecorders.set(harId, { path: har, content: options.updateContent ?? 'attach' });
-  }
-
   async routeFromHAR(har: string, options: { url?: string | RegExp, notFound?: 'abort' | 'fallback', update?: boolean, updateContent?: 'attach' | 'embed', updateMode?: 'minimal' | 'full' } = {}): Promise<void> {
     const localUtils = this._connection.localUtils();
     if (!localUtils)
       throw new Error('Route from har is not supported in thin clients');
     if (options.update) {
-      await this._recordIntoHAR(har, null, options);
+      await this.tracing._recordIntoHAR(har, null, options);
       return;
     }
     const harRouter = await HarRouter.create(localUtils, har, options.notFound || 'abort', { urlMatch: options.url });
@@ -522,25 +505,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
     this._closingStatus = 'closing';
     await this.request.dispose(options);
     await this._instrumentation.runBeforeCloseBrowserContext(this);
-    await this._wrapApiCall(async () => {
-      for (const [harId, harParams] of this._harRecorders) {
-        const har = await this._channel.harExport({ harId });
-        const artifact = Artifact.from(har.artifact);
-        // Server side will compress artifact if content is attach or if file is .zip.
-        const isCompressed = harParams.content === 'attach' || harParams.path.endsWith('.zip');
-        const needCompressed = harParams.path.endsWith('.zip');
-        if (isCompressed && !needCompressed) {
-          const localUtils = this._connection.localUtils();
-          if (!localUtils)
-            throw new Error('Uncompressed har is not supported in thin clients');
-          await artifact.saveAs(harParams.path + '.tmp');
-          await localUtils.harUnzip({ zipFile: harParams.path + '.tmp', harFile: harParams.path });
-        } else {
-          await artifact.saveAs(harParams.path);
-        }
-        await artifact.delete();
-      }
-    }, { internal: true });
+    await this.tracing._exportAllHars();
     await this._channel.close(options);
     await this._closedPromise;
   }

packages/playwright-core/src/client/fetch.ts

@@ -80,15 +80,15 @@ export class APIRequest implements api.APIRequest {
     this._contexts.add(context);
     context._request = this;
     context._timeoutSettings.setDefaultTimeout(options.timeout ?? this._playwright._defaultContextTimeout);
-    context._tracing._tracesDir = this._playwright._defaultLaunchOptions?.tracesDir;
+    context.tracing._tracesDir = this._playwright._defaultLaunchOptions?.tracesDir;
     await context._instrumentation.runAfterCreateRequestContext(context);
     return context;
   }
 }
 
 export class APIRequestContext extends ChannelOwner<channels.APIRequestContextChannel> implements api.APIRequestContext {
   _request?: APIRequest;
-  readonly _tracing: Tracing;
+  readonly tracing: Tracing;
   private _closeReason: string | undefined;
   _timeoutSettings: TimeoutSettings;
 
@@ -98,7 +98,7 @@ export class APIRequestContext extends ChannelOwner<channels.APIRequestContextCh
 
   constructor(parent: ChannelOwner, type: string, guid: string, initializer: channels.APIRequestContextInitializer) {
     super(parent, type, guid, initializer);
-    this._tracing = Tracing.from(initializer.tracing);
+    this.tracing = Tracing.from(initializer.tracing);
     this._timeoutSettings = new TimeoutSettings(this._platform);
   }
 
@@ -109,14 +109,15 @@ export class APIRequestContext extends ChannelOwner<channels.APIRequestContextCh
   async dispose(options: { reason?: string } = {}): Promise<void> {
     this._closeReason = options.reason;
     await this._instrumentation.runBeforeCloseRequestContext(this);
+    await this.tracing._exportAllHars();
     try {
       await this._channel.dispose(options);
     } catch (e) {
       if (isTargetClosedError(e))
         return;
       throw e;
     }
-    this._tracing._resetStackCounter();
+    this.tracing._resetStackCounter();
     this._request?._contexts.delete(this);
   }
 

packages/playwright-core/src/client/page.ts

@@ -529,7 +529,7 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     if (!localUtils)
       throw new Error('Route from har is not supported in thin clients');
     if (options.update) {
-      await this._browserContext._recordIntoHAR(har, this, options);
+      await this._browserContext.tracing._recordIntoHAR(har, this, options);
       return;
     }
     const harRouter = await HarRouter.create(localUtils, har, options.notFound || 'abort', { urlMatch: options.url });