Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(api): return Disposable from Tracing.start and Tracing.startChunk (#42970)

Pavel Feldman716a5d37cd8f
diff --git a/docs/src/api/class-tracing.md b/docs/src/api/class-tracing.md
index 906aece296..c00debbb4a 100644
--- a/docs/src/api/class-tracing.md
+++ b/docs/src/api/class-tracing.md
@@ -70,8 +70,9 @@ await context.Tracing.StopAsync(new()
## async method: Tracing.start
* since: v1.12
+- returns: <[Disposable]>
-Start tracing.
+Start tracing. Disposing the returned [Disposable] stops tracing without saving the trace, similarly to calling [`method: Tracing.stop`] without a path.
:::note
You probably want to [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead of using `Tracing.start`.
@@ -216,8 +217,9 @@ viewing during test execution.
## async method: Tracing.startChunk
* since: v1.15
+- returns: <[Disposable]>
-Start a new trace chunk. If you'd like to record multiple traces on the same [BrowserContext], use [`method: Tracing.start`] once, and then create multiple trace chunks with [`method: Tracing.startChunk`] and [`method: Tracing.stopChunk`].
+Start a new trace chunk. Disposing the returned [Disposable] stops the chunk without saving it, similarly to calling [`method: Tracing.stopChunk`] without a path. If you'd like to record multiple traces on the same [BrowserContext], use [`method: Tracing.start`] once, and then create multiple trace chunks with [`method: Tracing.startChunk`] and [`method: Tracing.stopChunk`].
**Usage**
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 21a79474f3..4e8094bfe5 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -23381,7 +23381,9 @@ export interface Tracing {
groupEnd(): Promise<void>;
/**
- * Start tracing.
+ * Start tracing. Disposing the returned [Disposable](https://playwright.dev/docs/api/class-disposable) stops tracing
+ * without saving the trace, similarly to calling
+ * [tracing.stop([options])](https://playwright.dev/docs/api/class-tracing#tracing-stop) without a path.
*
* **NOTE** You probably want to
* [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead
@@ -23466,10 +23468,13 @@ export interface Tracing {
* Trace name to be shown in the Trace Viewer.
*/
title?: string;
- }): Promise<void>;
+ }): Promise<Disposable>;
/**
- * Start a new trace chunk. If you'd like to record multiple traces on the same
+ * Start a new trace chunk. Disposing the returned [Disposable](https://playwright.dev/docs/api/class-disposable)
+ * stops the chunk without saving it, similarly to calling
+ * [tracing.stopChunk([options])](https://playwright.dev/docs/api/class-tracing#tracing-stop-chunk) without a path. If
+ * you'd like to record multiple traces on the same
* [BrowserContext](https://playwright.dev/docs/api/class-browsercontext), use
* [tracing.start([options])](https://playwright.dev/docs/api/class-tracing#tracing-start) once, and then create
* multiple trace chunks with
@@ -23511,7 +23516,7 @@ export interface Tracing {
* Trace name to be shown in the Trace Viewer.
*/
title?: string;
- }): Promise<void>;
+ }): Promise<Disposable>;
/**
* Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when
diff --git a/packages/playwright-core/src/client/tracing.ts b/packages/playwright-core/src/client/tracing.ts
index 928f8615e8..b191bc99db 100644
--- a/packages/playwright-core/src/client/tracing.ts
+++ b/packages/playwright-core/src/client/tracing.ts
@@ -59,6 +59,7 @@ export class Tracing extends ChannelOwner<channels.TracingChannel> implements ap
const { traceName } = await this._channel.tracingStartChunk({ name: options.name, title: options.title }, kNoTimeout);
await this._startCollectingStacks(traceName, this._isLive);
});
+ return new DisposableStub(() => this.stop());
}
async startChunk(options: { name?: string, title?: string } = {}) {
@@ -66,6 +67,7 @@ export class Tracing extends ChannelOwner<channels.TracingChannel> implements ap
const { traceName } = await this._channel.tracingStartChunk(options, kNoTimeout);
await this._startCollectingStacks(traceName, this._isLive);
});
+ return new DisposableStub(() => this.stopChunk());
}
async group(name: string, options: { location?: { file: string, line?: number, column?: number } } = {}) {
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 21a79474f3..4e8094bfe5 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -23381,7 +23381,9 @@ export interface Tracing {
groupEnd(): Promise<void>;
/**
- * Start tracing.
+ * Start tracing. Disposing the returned [Disposable](https://playwright.dev/docs/api/class-disposable) stops tracing
+ * without saving the trace, similarly to calling
+ * [tracing.stop([options])](https://playwright.dev/docs/api/class-tracing#tracing-stop) without a path.
*
* **NOTE** You probably want to
* [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead
@@ -23466,10 +23468,13 @@ export interface Tracing {
* Trace name to be shown in the Trace Viewer.
*/
title?: string;
- }): Promise<void>;
+ }): Promise<Disposable>;
/**
- * Start a new trace chunk. If you'd like to record multiple traces on the same
+ * Start a new trace chunk. Disposing the returned [Disposable](https://playwright.dev/docs/api/class-disposable)
+ * stops the chunk without saving it, similarly to calling
+ * [tracing.stopChunk([options])](https://playwright.dev/docs/api/class-tracing#tracing-stop-chunk) without a path. If
+ * you'd like to record multiple traces on the same
* [BrowserContext](https://playwright.dev/docs/api/class-browsercontext), use
* [tracing.start([options])](https://playwright.dev/docs/api/class-tracing#tracing-start) once, and then create
* multiple trace chunks with
@@ -23511,7 +23516,7 @@ export interface Tracing {
* Trace name to be shown in the Trace Viewer.
*/
title?: string;
- }): Promise<void>;
+ }): Promise<Disposable>;
/**
* Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when
diff --git a/tests/library/tracing.spec.ts b/tests/library/tracing.spec.ts
index 184bb34c0d..ad29ab0de5 100644
--- a/tests/library/tracing.spec.ts
+++ b/tests/library/tracing.spec.ts
@@ -606,6 +606,23 @@ test('should not throw when stopping without start but not exporting', async ({
await context.tracing.stop();
});
+test('start should return a disposable that discards the trace', async ({ context, page, server }, testInfo) => {
+ const disposable = await context.tracing.start();
+ await page.goto(server.EMPTY_PAGE);
+ await disposable.dispose();
+ const error = await context.tracing.stop({ path: testInfo.outputPath('trace.zip') }).catch(e => e);
+ expect(error.message).toContain('Must start tracing before stopping');
+});
+
+test('startChunk should return a disposable that discards the chunk', async ({ context, page, server }, testInfo) => {
+ await context.tracing.start();
+ const disposable = await context.tracing.startChunk();
+ await page.goto(server.EMPTY_PAGE);
+ await disposable.dispose();
+ const error = await context.tracing.stopChunk({ path: testInfo.outputPath('trace.zip') }).catch(e => e);
+ expect(error.message).toContain('Must start tracing before stopping');
+});
+
test('should work with multiple chunks', async ({ context, page, server }, testInfo) => {
await context.tracing.start({ screenshots: true, snapshots: true });
await page.goto(server.PREFIX + '/frames/frame.html');