Repository: microsoft/playwright
Pull request #35852: docs(tracing): clarify diff between test tracing and `context.tracing`
Author: login: agg23
Created: 2025-05-05T17:04:21Z | Merged: 2025-05-06T18:25:33Z

Explicitly document that `context.tracing` cannot trace everything that Playwright Test tracing can trace. Anything that stays local to the runner is not traced.


Diff:
diff --git a/docs/src/api/class-tracing.md b/docs/src/api/class-tracing.md
index 3b0011c7b1d3d..0528891fdcb96 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 c018ad0623b5a..a42adb176e6a5 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 c018ad0623b5a..a42adb176e6a5 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' });
    * ```
    *


Reviews:
user: login: dgozman
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-06T09:03:39Z
user: login: dgozman
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-06T15:29:14Z
user: login: dgozman
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-06T18:12:26Z

Review comments:
diff_hunk: @@ -66,12 +72,18 @@ await context.Tracing.StopAsync(new()
 
 Start tracing.
 
+:::note
+This API records browser operations and network activity, but does not capture test assertions (`expect` calls).
path: docs/src/api/class-tracing.md
user: login: dgozman
body: I think this also needs a call to action, which is "use trace" config file option.
created_at: 2025-05-06T09:01:31Z
author_association: COLLABORATOR
diff_hunk: @@ -3,6 +3,10 @@
 
 API for collecting and saving Playwright traces. Playwright traces can be opened in [Trace Viewer](../trace-viewer.md) after Playwright script runs.
 
+:::note
+The `context.tracing` API records different information than the automatic tracing enabled through [Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace). This API records browser operations and network activity, but does not capture test assertions (`expect` calls).
path: docs/src/api/class-tracing.md
user: login: dgozman
body: While I like the explanation, I think that adding a suggestion "you should use config option instead" would benefit more users, because they will immediately understand what to do.
created_at: 2025-05-06T09:02:43Z
author_association: COLLABORATOR
diff_hunk: @@ -11,6 +15,8 @@ const context = await browser.newContext();
 await context.tracing.start({ screenshots: true, snapshots: true });
 const page = await context.newPage();
 await page.goto('https://playwright.dev');
+// Not captured
path: docs/src/api/class-tracing.md
user: login: dgozman
body: Again, "not captured" is not really helpful here. Either say "see note above", or just drop it from the snippet. I think the note is enough.
created_at: 2025-05-06T09:03:28Z
author_association: COLLABORATOR
diff_hunk: @@ -66,12 +72,18 @@ await context.Tracing.StopAsync(new()
 
 Start tracing.
 
+:::note
+This API records browser operations and network activity, but does not capture test assertions (`expect` calls).
+:::
+
 **Usage**
 
 ```js
 await context.tracing.start({ screenshots: true, snapshots: true });
 const page = await context.newPage();
 await page.goto('https://playwright.dev');
+// Not captured
path: docs/src/api/class-tracing.md
user: login: dgozman
body: Same comment here.
created_at: 2025-05-06T09:03:34Z
author_association: COLLABORATOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-05-05T18:01:51Z
body: <!-- Generated by Playwright markdown reporter for tests 1 in job merge-reports -->
### [Test results](https://mspwblobreport.z1.web.core.windows.net/run-14842055219-1-2c2da8a0aa790a6412407394fd3b8f4ad2802063/index.html) for "tests 1"
**1 failed**
:x: [firefox-page] › page/page-evaluate.spec.ts:424:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18

<details>
<summary><b>7 flaky</b></summary>
:warning: [chromium-page] › page/page-request-continue.spec.ts:72:3 › should delete header with undefined value @chromium-ubuntu-22.04-node22 <br/>
:warning: [firefox-library] › library/inspector/cli-codegen-1.spec.ts:986:7 › cli codegen › should not throw csp directive violation errors @firefox-ubuntu-22.04-node18 <br/>
:warning: [webkit-library] › library/ignorehttpserrors.spec.ts:30:3 › should isolate contexts @webkit-ubuntu-22.04-node18 <br/>
:warning: [webkit-page] › page/page-event-popup.spec.ts:28:3 › should work with window features @webkit-ubuntu-22.04-node18 <br/>
:warning: [webkit-page] › page/page-screenshot.spec.ts:345:5 › page screenshot › should work while navigating @webkit-ubuntu-22.04-node18 <br/>
:warning: [playwright-test] › ui-mode-test-update.spec.ts:38:5 › should pick new / deleted files @windows-latest-node18-1 <br/>
:warning: [playwright-test] › ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1 <br/>

</details>

**39128 passed, 803 skipped**
:heavy_check_mark::heavy_check_mark::heavy_check_mark:


Merge [workflow run](https://github.com/microsoft/playwright/actions/runs/14842935290).
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-06T13:46:54Z
body: <!-- Generated by Playwright markdown reporter for tests 1 in job merge-reports -->
### [Test results](https://mspwblobreport.z1.web.core.windows.net/run-14861023631-1-8e08fdb52c27bb75de9bf87627bf740fadab2122/index.html) for "tests 1"
**5633 passed, 29 skipped**
:heavy_check_mark::heavy_check_mark::heavy_check_mark:


Merge [workflow run](https://github.com/microsoft/playwright/actions/runs/14861305215).
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-06T14:35:14Z
body: <!-- Generated by Playwright markdown reporter for tests 1 in job merge-reports -->
### [Test results](https://mspwblobreport.z1.web.core.windows.net/run-14861295667-1-8e08fdb52c27bb75de9bf87627bf740fadab2122/index.html) for "tests 1"
**3 failed**
:x: [firefox-page] › page/page-evaluate.spec.ts:424:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
:x: [default-reuse] › run-tests.spec.ts:295:5 › should show soft error messages @vscode-extension
:x: [default-reuse] › run-tests.spec.ts:340:5 › should only create test run if file belongs to context @vscode-extension

<details>
<summary><b>7 flaky</b></summary>
:warning: [firefox-library] › library/inspector/cli-codegen-1.spec.ts:986:7 › cli codegen › should not throw csp directive violation errors @firefox-ubuntu-22.04-node18 <br/>
:warning: [firefox-library] › library/tracing.spec.ts:432:14 › should produce screencast frames crop @firefox-ubuntu-22.04-node18 <br/>
:warning: [chromium] › headerView.spec.tsx:46:1 › should toggle filters @web-components-html-reporter <br/>
:warning: [webkit-library] › library/ignorehttpserrors.spec.ts:30:3 › should isolate contexts @webkit-ubuntu-22.04-node18 <br/>
:warning: [webkit-library] › library/video.spec.ts:411:5 › screencast › should capture css transformation @webkit-ubuntu-22.04-node18 <br/>
:warning: [webkit-page] › page/page-event-popup.spec.ts:28:3 › should work with window features @webkit-ubuntu-22.04-node18 <br/>
:warning: [webkit-page] › page/page-screenshot.spec.ts:345:5 › page screenshot › should work while navigating @webkit-ubuntu-22.04-node18 <br/>

</details>

**39126 passed, 803 skipped**
:heavy_check_mark::heavy_check_mark::heavy_check_mark:


Merge [workflow run](https://github.com/microsoft/playwright/actions/runs/14862396028).
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-06T17:22:28Z
body: <!-- Generated by Playwright markdown reporter for tests 1 in job merge-reports -->
### [Test results](https://mspwblobreport.z1.web.core.windows.net/run-14864860093-1-8e08fdb52c27bb75de9bf87627bf740fadab2122/index.html) for "tests 1"
**1 failed**
:x: [firefox-page] › page/page-evaluate.spec.ts:424:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18

<details>
<summary><b>5 flaky</b></summary>
:warning: [firefox-library] › library/inspector/cli-codegen-1.spec.ts:986:7 › cli codegen › should not throw csp directive violation errors @firefox-ubuntu-22.04-node18 <br/>
:warning: [chromium-library] › library/client-certificates.spec.ts:400:3 › browser › should not hang on tls errors during TLS 1.2 handshake @ubuntu-22.04-chromium-tip-of-tree <br/>
:warning: [chromium] › headerView.spec.tsx:46:1 › should toggle filters @web-components-html-reporter <br/>
:warning: [webkit-library] › library/ignorehttpserrors.spec.ts:30:3 › should isolate contexts @webkit-ubuntu-22.04-node18 <br/>
:warning: [playwright-test] › ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1 <br/>

</details>

**39130 passed, 803 skipped**
:heavy_check_mark::heavy_check_mark::heavy_check_mark:


Merge [workflow run](https://github.com/microsoft/playwright/actions/runs/14865801420).
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-06T18:37:28Z
body: <!-- Generated by Playwright markdown reporter for tests 1 in job merge-reports -->
### [Test results](https://mspwblobreport.z1.web.core.windows.net/run-14866286939-1-00429efc4ac67ece5d9ba220d7470ea97c0ca265/index.html) for "tests 1"
**1 failed**
:x: [firefox-page] › page/page-evaluate.spec.ts:424:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18

<details>
<summary><b>3 flaky</b></summary>
:warning: [firefox-library] › library/inspector/cli-codegen-1.spec.ts:986:7 › cli codegen › should not throw csp directive violation errors @firefox-ubuntu-22.04-node18 <br/>
:warning: [webkit-library] › library/ignorehttpserrors.spec.ts:30:3 › should isolate contexts @webkit-ubuntu-22.04-node18 <br/>
:warning: [playwright-test] › ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1 <br/>

</details>

**39132 passed, 803 skipped**
:heavy_check_mark::heavy_check_mark::heavy_check_mark:


Merge [workflow run](https://github.com/microsoft/playwright/actions/runs/14867166814).
author_association: CONTRIBUTOR