Skip to content

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

docs(tracing): clarify diff between test tracing and `context.tracing` (#35852)

Adam Gastineau00429efc4ac6
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' });
* ```
*