📖 The Story: The Flaky Checkout

A QA team had a test that passed 95% of the time but failed randomly in CI. The failure was always the same: the checkout button was clicked, but the success page never appeared. The team spent two weeks trying to reproduce it locally — it never failed on a developer’s machine.

When they added tracing, they saw the click happen. When they added a separate HAR recording, they saw the API call. But the two artifacts were in different files with different timestamps, and correlating “did the click happen before or after the API timeout?” required manual math across two tools.

The root cause turned out to be a race condition: the checkout API had a 4-second timeout, and the CI runner was slow enough that the page’s loading spinner sometimes overlapped with the API call, causing a double-submit guard to fire. The team only found this after a senior engineer manually aligned the HAR timestamps with the trace screenshots — a process that took 40 minutes per failure.

If the HAR and the trace had been one artifact, the engineer would have seen the overlap in 4 seconds.

🎯 Why It Matters

🌍 Real World Example

An e-commerce team runs a checkout test that hits 12 API endpoints. When it fails, they need to know which endpoint timed out. Before 1.60, they configured recordHar on the BrowserContext, which captured every network call including analytics pings and CDN asset fetches — the HAR file was 8 MB and took 30 seconds to open in Chrome’s HAR viewer. With tracing.startHar('trace.har', { urlFilter: '**/api/**' }), the HAR is 200 KB, contains only the 12 API calls, and opens inside the Trace Viewer alongside the DOM timeline.

🧒 Explain Like I'm 10

Imagine you’re a detective investigating a crime. You have a video camera that records what people do (the trace), and you have a microphone that records what people say (the HAR).

Before, the camera and microphone were on different clocks. When you played them back, the lip-sync was off, and you couldn’t tell if someone said “fire!” before or after the window broke.

Now, the camera and microphone are built into the same device with the same clock. When you play it back, everything lines up perfectly.

🎓 Professional Explanation

HAR (HTTP Archive) is a JSON-formatted log of all network requests a browser makes. Playwright has supported HAR recording since 1.0 via the recordHar context option, but it was configured separately from tracing. This meant network captures and DOM/action captures lived in different files with different timestamp origins, making correlation manual and error-prone.

Playwright 1.60 introduces tracing.startHar() and tracing.stopHar(), which fold HAR recording into the tracing API. They accept the same content, mode, and urlFilter options as recordHar, but the recording is scoped to a tracing context and can be used with the await using disposable pattern (requires Node 20.17+) for automatic finalization.

📊 The Flow

⚙️ The tracing.startHar() API

The API lives on context.tracing and returns a Disposable that finalizes the HAR when it goes out of scope. You need Node 20.17+ for the await using syntax; on older Node, call stopHar() explicitly.

import { test } from class="tk-str">'@playwright/test';

test(class="tk-str">'checkout API debugging', async ({ context }) => {
  class=class="tk-str">"tk-com">// Start HAR recording scoped to this test
  await using har = await context.tracing.startHar(class="tk-str">'trace.har', {
    urlFilter: class="tk-str">'**/api/**',
  });

  const page = await context.newPage();
  await page.goto(class="tk-str">'https:class="tk-com">//storedemo.testdino.com');
  await page.getByTestId(class="tk-str">'header-menu-all-products').click();

  class=class="tk-str">"tk-com">// HAR is finalized when `har` goes out of scope.
  await expect(page).toHaveURL(/.*products/);
});

class=class="tk-str">"tk-com">// Filter by URL to capture only API calls (skip static assets)
await using har = await context.tracing.startHar(class="tk-str">'api.har', {
  urlFilter: class="tk-str">'**/api/**',
  mode: class="tk-str">'minimal',  class=class="tk-str">"tk-com">// omit request/response bodies for smaller files
});

class=class="tk-str">"tk-com">// Or capture everything (default)
await using fullHar = await context.tracing.startHar(class="tk-str">'full.har', {
  content: class="tk-str">'embed',  class=class="tk-str">"tk-com">// embed response bodies in the HAR
});

class=class="tk-str">"tk-com">// Without await using (Node 18 compatible)
test(class="tk-str">'legacy node version', async ({ context }) => {
  await context.tracing.startHar(class="tk-str">'trace.har', {
    urlFilter: class="tk-str">'**/api/**',
  });

  const page = await context.newPage();
  await page.goto(class="tk-str">'https:class="tk-com">//app.example.com');

  class=class="tk-str">"tk-com">// Manually finalize the HAR
  await context.tracing.stopHar();
});

🔄 Before vs After

Before: Parallel recordHar on BrowserContext (1.59 and earlier)

class=class="tk-str">"tk-com">// playwright.config.ts (Playwright 1.59 and earlier)
export default defineConfig({
  use: {
    contextOptions: {
      recordHar: { path: class="tk-str">'network.har', urlFilter: class="tk-str">'**/api/**' },
    },
  },
});

After: tracing.startHar() with await using (1.60+)

import { test } from class="tk-str">'@playwright/test';

test(class="tk-str">'checkout API debugging', async ({ context }) => {
  await using har = await context.tracing.startHar(class="tk-str">'trace.har', {
    urlFilter: class="tk-str">'**/api/**',
  });

  const page = await context.newPage();
  await page.goto(class="tk-str">'https:class="tk-com">//storedemo.testdino.com');
  await page.getByTestId(class="tk-str">'header-menu-all-products').click();

  class=class="tk-str">"tk-com">// HAR is finalized when `har` goes out of scope.
  await expect(page).toHaveURL(/.*products/);
});

⚠️ Common Mistakes

Mistake 1: Using await using on Node 18

The await using keyword is a Node 20.17+ feature. On Node 18, the test will fail with a syntax error. Either upgrade Node or use the explicit startHar() / stopHar() form.

class=class="tk-str">"tk-com">// Node 18 — will throw SyntaxError
await using har = await context.tracing.startHar(class="tk-str">'trace.har');

class=class="tk-str">"tk-com">// Node 18 compatible
await context.tracing.startHar(class="tk-str">'trace.har');
class=class="tk-str">"tk-com">// ... test body ...
await context.tracing.stopHar();

Mistake 2: Forgetting to start tracing itself

startHar() records network calls, but it does not start the trace. If you want DOM actions and screenshots in the same artifact, you also need context.tracing.start({ snapshots: true, screenshots: true }). The HAR recording layers on top of the trace.

class=class="tk-str">"tk-com">// Start tracing FIRST, then layer HAR on top
await context.tracing.start({ snapshots: true, screenshots: true });
await using har = await context.tracing.startHar(class="tk-str">'trace.har', {
  urlFilter: class="tk-str">'**/api/**',
});

Mistake 3: Not filtering the HAR

Without urlFilter, the HAR captures every network call including analytics pings, CDN asset fetches, and WebSocket handshakes. A 200 KB API-only HAR becomes an 8 MB mess that takes 30 seconds to open. Always filter: urlFilter: '**/api/**'.

✅ Best Practices

1. Always pass urlFilter to capture only the API calls you care about. A filtered HAR is 10–40x smaller and opens instantly.
2. Use await using (Node 20.17+) for auto-finalization — it prevents leaked recordings when tests throw.
3. Start tracing first, then layer HAR on top. startHar() records network; start() records DOM actions. You need both for full debugging.
4. Use mode: 'minimal' for CI runs to omit request/response bodies and keep the HAR small.
5. Use content: 'embed' for local debugging to include response bodies inline (useful for inspecting JSON API responses).
6. Combine with --trace=retain-on-failure so the HAR + trace is only kept for failing runs.

🏗️ Senior Engineer Deep Dive

Why HAR and trace were separate before 1.60

Playwright’s tracing system and its HAR recording system evolved independently. Tracing was built for DOM/action forensics — screenshots, click coordinates, console logs. HAR recording was bolted on via the BrowserContext’s recordHar option, which predated tracing. The two systems used different timestamp origins and different file formats, so correlating “did the API call happen before or after the click?” required manual math. tracing.startHar() unifies the timestamp origin so network calls appear on the same timeline as DOM actions in Trace Viewer.

When to use HAR tracing vs route interception

page.route() is for mocking network calls — you intercept a request and return a fake response. tracing.startHar() is for recording real network calls for later debugging. They are complementary: use route() to make tests deterministic, use startHar() to debug why a test that should pass is failing. You can combine them — route-mocked calls appear in the HAR with a note that they were fulfilled by Playwright.

💼 Interview Questions

🏋️ Practical Exercise

🚀 Mini Project

📝 Quiz

❓ FAQ

Q: Can I use tracing.startHar() with the HTML reporter?

A: Yes. The HAR is embedded in the trace.zip, and the HTML reporter links to the trace for each test. When you click a failing test in the HTML report, the trace opens in Trace Viewer with network calls visible inline.

Q: Does startHar() capture WebSocket frames?

A: Yes. Since Playwright 1.61, HAR and trace recordings include WebSocket requests. Earlier versions captured only HTTP. If you need WebSocket debugging, ensure you’re on 1.61+.

Q: Can I start and stop HAR recording multiple times in one test?

A: Yes. Each startHar() call returns a new Disposable. You can start, finalize, then start again with different urlFilters. Each recording writes to its own file. This is useful for isolating network calls per test phase (e.g., “auth phase” vs “checkout phase”).

📦 Summary