From 00429efc4ac67ece5d9ba220d7470ea97c0ca265 Mon Sep 17 00:00:00 2001 From: Adam Gastineau Date: Tue, 6 May 2025 11:25:33 -0700 Subject: [PATCH] docs(tracing): clarify diff between test tracing and `context.tracing` (#35852) --- docs/src/api/class-tracing.md | 14 ++++++++++++++ packages/playwright-client/types/types.d.ts | 20 ++++++++++++++++++++ packages/playwright-core/types/types.d.ts | 20 ++++++++++++++++++++ 3 files changed, 54 insertions(+) diff --git a/docs/src/api/class-tracing.md b/docs/src/api/class-tracing.md index 3b0011c7b1..0528891fdc 100644 --- a/docs/src/api/class-tracing.md +++ b/docs/src/api/class-tracing.md @@ -3,6 +3,12 @@ API for collecting and saving Playwright traces. Playwright traces can be opened in [Trace Viewer](../trace-viewer.md) after Playwright script runs. +:::note +You probably want to [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead of using `context.tracing`. + +The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions (like `expect` calls). We recommend [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), which includes those assertions and provides a more complete trace for debugging test failures. +::: + Start recording a trace before performing actions. At the end, stop tracing and save it to a file. ```js @@ -11,6 +17,7 @@ const context = await browser.newContext(); await context.tracing.start({ screenshots: true, snapshots: true }); const page = await context.newPage(); await page.goto('https://playwright.dev'); +expect(page.url()).toBe('https://playwright.dev'); await context.tracing.stop({ path: 'trace.zip' }); ``` @@ -66,12 +73,19 @@ await context.Tracing.StopAsync(new() Start tracing. +:::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`. + +The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions (like `expect` calls). We recommend [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), which includes those assertions and provides a more complete trace for debugging test failures. +::: + **Usage** ```js await context.tracing.start({ screenshots: true, snapshots: true }); const page = await context.newPage(); await page.goto('https://playwright.dev'); +expect(page.url()).toBe('https://playwright.dev'); await context.tracing.stop({ path: 'trace.zip' }); ``` diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts index c018ad0623..a42adb176e 100644 --- a/packages/playwright-client/types/types.d.ts +++ b/packages/playwright-client/types/types.d.ts @@ -21175,6 +21175,15 @@ export interface Touchscreen { * API for collecting and saving Playwright traces. Playwright traces can be opened in * [Trace Viewer](https://playwright.dev/docs/trace-viewer) after Playwright script runs. * + * **NOTE** You probably want to + * [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead + * of using `context.tracing`. + * + * The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions + * (like `expect` calls). We recommend + * [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), + * which includes those assertions and provides a more complete trace for debugging test failures. + * * Start recording a trace before performing actions. At the end, stop tracing and save it to a file. * * ```js @@ -21183,6 +21192,7 @@ export interface Touchscreen { * await context.tracing.start({ screenshots: true, snapshots: true }); * const page = await context.newPage(); * await page.goto('https://playwright.dev'); + * expect(page.url()).toBe('https://playwright.dev'); * await context.tracing.stop({ path: 'trace.zip' }); * ``` * @@ -21230,12 +21240,22 @@ export interface Tracing { /** * Start tracing. * + * **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`. + * + * The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions + * (like `expect` calls). We recommend + * [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), + * which includes those assertions and provides a more complete trace for debugging test failures. + * * **Usage** * * ```js * await context.tracing.start({ screenshots: true, snapshots: true }); * const page = await context.newPage(); * await page.goto('https://playwright.dev'); + * expect(page.url()).toBe('https://playwright.dev'); * await context.tracing.stop({ path: 'trace.zip' }); * ``` * diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index c018ad0623..a42adb176e 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -21175,6 +21175,15 @@ export interface Touchscreen { * API for collecting and saving Playwright traces. Playwright traces can be opened in * [Trace Viewer](https://playwright.dev/docs/trace-viewer) after Playwright script runs. * + * **NOTE** You probably want to + * [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead + * of using `context.tracing`. + * + * The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions + * (like `expect` calls). We recommend + * [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), + * which includes those assertions and provides a more complete trace for debugging test failures. + * * Start recording a trace before performing actions. At the end, stop tracing and save it to a file. * * ```js @@ -21183,6 +21192,7 @@ export interface Touchscreen { * await context.tracing.start({ screenshots: true, snapshots: true }); * const page = await context.newPage(); * await page.goto('https://playwright.dev'); + * expect(page.url()).toBe('https://playwright.dev'); * await context.tracing.stop({ path: 'trace.zip' }); * ``` * @@ -21230,12 +21240,22 @@ export interface Tracing { /** * Start tracing. * + * **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`. + * + * The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions + * (like `expect` calls). We recommend + * [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), + * which includes those assertions and provides a more complete trace for debugging test failures. + * * **Usage** * * ```js * await context.tracing.start({ screenshots: true, snapshots: true }); * const page = await context.newPage(); * await page.goto('https://playwright.dev'); + * expect(page.url()).toBe('https://playwright.dev'); * await context.tracing.stop({ path: 'trace.zip' }); * ``` *