Build a trustworthy timeline for Playwright context failures

A popup is visible in the trace, but the test times out waiting for a new page. The listener was registered after the click, so the context emitted its page event before the test started waiting. More timeout cannot recover an event that already happened.

Browser-context events are most useful when they are attached before the trigger, scoped to one owner, and read as evidence rather than treated as a complete browser state machine.

Read events as observations, not readiness guarantees

A BrowserContext is the session boundary around pages, cookies, permissions, routes, and other browser state. Its events let a test observe activity across every page in that context. That broader scope is useful for popups created indirectly, context-wide request failures, service workers, and teardown diagnosis.

The scope also makes careless listeners noisy. A context request listener sees requests from all pages in the context. A page listener sees popups even when they were opened by a helper rather than the page the test is currently using. A close listener sees expected fixture teardown and browser-level failure through the same event name.

Playwright 1.60 added several lifecycle observations that make context-wide timelines easier:

• browser.on('context') fires when a new browser context is created.
• browserContext.on('pageclose') fires when a page in that context closes.
• browserContext.on('pageload') fires when the JavaScript load event is dispatched in a page in that context.

Older, established events remain important. browserContext.on('page') reports a newly created page, and browserContext.on('close') reports context closure. Check the project-local version before using the newer names. A TypeScript cast cannot add an event to an older runtime.

Event occurrence is not the same as application readiness. The context's page event fires when the new page becomes available, while that page may still be loading. A pageload event says the browser dispatched load; it does not say a client-side application finished fetching data, removed its skeleton, or enabled the control the test needs.

Wait for the narrowest observable condition:

• Use page creation to obtain the Page handle.
• Use page.waitForURL() when navigation identity matters.
• Use a locator assertion when the user-facing state matters.
• Use a response wait only when that response is the contract under test.
• Use context closure evidence when diagnosing ownership or browser loss.

This keeps a test from turning event trivia into product assertions. The user does not care that a load event fired if the checkout confirmation never rendered.

Playwright does not promise that an arbitrary collection of listeners forms a universal total order for every browser and failure mode. Record the events you need, but assert only documented relationships or relationships controlled by your own code. For example, you can prove that your close-started marker was written before your own context.close() call. Avoid asserting that every page event must always appear in one hand-written order during a browser crash.

Arm one-shot waits before the action that triggers them

The most common event bug is temporal. The test performs an action, awaits its completion, and only then creates the event wait. Fast local runs may happen to leave enough time; a different browser or application build closes the gap.

Create the promise first, trigger the action second, then await the promise:

import { test, expect } from '@playwright/test';

test('opens an invoice in a new page', async ({ page, context }) => {
  await page.goto('/orders/1842');

  const invoicePagePromise = context.waitForEvent('page');
  await page.getByRole('link', { name: 'Open invoice' }).click();
  const invoicePage = await invoicePagePromise;

  await invoicePage.waitForURL('**/invoices/1842');
  await expect(invoicePage.getByRole('heading', { name: 'Invoice 1842' }))
    .toBeVisible();
});

Nothing is awaited between creating the promise and clicking. The promise subscribes immediately, so the event cannot slip through that gap. The URL and heading waits happen after the test has the new page handle.

When the new page must be a popup from one specific page, prefer the narrower source:

const popupPromise = page.waitForEvent('popup');
await page.getByRole('button', { name: 'Preview receipt' }).click();
const popup = await popupPromise;
await expect(popup.getByText('Receipt preview')).toBeVisible();

The context-level version is appropriate when the opener is indirect or unknown. The page-level version avoids accidentally accepting a page opened by unrelated application behavior.

Predicates help when several matching events can occur. They are not a substitute for setting up the wait early. This example accepts only the admin audit page and gives the wait a bounded timeout:

const auditPagePromise = context.waitForEvent('page', {
  predicate: candidate => candidate.url().includes('/admin/audit'),
  timeout: 10_000,
});

await page.getByRole('button', { name: 'View audit trail' }).click();
const auditPage = await auditPagePromise;
await expect(auditPage.getByRole('heading', { name: 'Audit trail' }))
  .toBeVisible();

The number is a configured timeout, not a claim about measured page speed. Choose it from the suite's latency budget. More importantly, confirm that candidate.url() is meaningful at the event point for your navigation. If the page is created at about:blank and navigates afterward, obtain the page first and wait for its URL instead of filtering it out prematurely.

waitForEvent throws if the context closes before the requested event arrives. That failure is useful. It says the producer disappeared, which differs from an open context that simply never emitted the event. Capture context-close and browser-disconnect evidence before deciding whether the trigger failed, the page opened elsewhere, or the browser died.

Capture a popup's first request at context scope

The new Page handle is not available early enough to observe every part of its initial navigation through page-level listeners. Playwright documents that the context page event occurs after the initial request has completed far enough for its response to start loading. If the initial request itself is the evidence you need, register a context request wait before the trigger.

import { test, expect } from '@playwright/test';

test('requests the signed invoice URL', async ({ page, context }) => {
  await page.goto('/orders/1842');

  const requestPromise = context.waitForEvent('request', {
    predicate: request => request.url().includes('/invoices/1842.pdf'),
  });
  const pagePromise = context.waitForEvent('page');

  await page.getByRole('link', { name: 'Open signed invoice' }).click();

  const [request, invoicePage] = await Promise.all([
    requestPromise,
    pagePromise,
  ]);

  expect(request.method()).toBe('GET');
  await invoicePage.waitForURL('**/invoices/1842.pdf');
});

Both promises are created before the click. Promise.all only awaits promises that already have their subscriptions armed; it does not create the waits after the action. This difference is easy to miss when refactoring code into helpers.

Context scope has a concrete cost. The predicate sees requests from every page in that session, so a loose substring can match a background request from the opener. Filter on the full behavior you know, such as URL path and method, and use page scope once the page handle exists. If the requirement is merely that the invoice page becomes usable, skip the request wait and assert the page's visible state. Network evidence should serve a test contract, not decorate it.

Keep event callbacks synchronous when they only collect evidence. An on listener is a poor place for a chain of critical assertions that the test never explicitly awaits. Capture the Page, Request, or error in a ledger, then perform awaited assertions in the test or fixture. That makes failures belong to a known step and prevents teardown from racing unfinished diagnostic work.

Add a scoped recorder without leaking listeners

A reusable recorder should preserve event names, a local sequence, and just enough identifying data. It should also return a cleanup function that removes the exact callback references it registered.

The following recorder uses the context-level pageclose and pageload events available from Playwright 1.60. It records current pages as snapshots at attachment time so nobody confuses an already-open page with a newly emitted page event.

// diagnostics/context-recorder.ts
import type { BrowserContext, Page } from '@playwright/test';

export type ContextLifecycleEntry = {
  sequence: number;
  type: 'snapshot' | 'page' | 'pageload' | 'pageclose' | 'contextclose';
  url?: string;
};

export function recordContextLifecycle(context: BrowserContext) {
  const entries: ContextLifecycleEntry[] = [];
  let sequence = 0;

  const add = (type: ContextLifecycleEntry['type'], page?: Page) => {
    entries.push({
      sequence: ++sequence,
      type,
      url: page?.url(),
    });
  };

  for (const page of context.pages()) {
    add('snapshot', page);
  }

  const onPage = (page: Page) => add('page', page);
  const onPageLoad = (page: Page) => add('pageload', page);
  const onPageClose = (page: Page) => add('pageclose', page);
  const onContextClose = () => add('contextclose');

  context.on('page', onPage);
  context.on('pageload', onPageLoad);
  context.on('pageclose', onPageClose);
  context.on('close', onContextClose);

  return {
    entries,
    dispose() {
      context.off('page', onPage);
      context.off('pageload', onPageLoad);
      context.off('pageclose', onPageClose);
      context.off('close', onContextClose);
    },
  };
}

Sequence numbers describe the callback order observed by this recorder. They are not timestamps and make no performance claim. Storing every console argument, request body, or response body would create a much larger and more sensitive artifact. Add those only for a specific investigation.

Place the recorder inside the fixture that owns the context. Attach the ledger even if close fails, then remove listeners in a nested finally block.

// fixtures/diagnosed-context.ts
import {
  test as base,
  type BrowserContext,
} from '@playwright/test';
import { recordContextLifecycle } from '../diagnostics/context-recorder';

type Fixtures = { diagnosedContext: BrowserContext };

export const test = base.extend<Fixtures>({
  diagnosedContext: async ({ browser }, use, testInfo) => {
    const context = await browser.newContext();
    const recorder = recordContextLifecycle(context);
    let closeError: unknown;

    try {
      await use(context);
    } finally {
      try {
        await context.close({ reason: 'diagnosed fixture teardown' });
      } catch (error) {
        closeError = error;
      }

      try {
        await testInfo.attach('context-lifecycle.json', {
          body: Buffer.from(JSON.stringify(recorder.entries, null, 2)),
          contentType: 'application/json',
        });
      } finally {
        recorder.dispose();
      }

      if (closeError) {
        throw closeError;
      }
    }
  },
});

Removing listeners matters most on worker-scoped objects. Playwright Test's browser fixture is worker scoped, so a browser listener added for one test can observe later contexts if it is never removed. That produces duplicate log lines, retains closures longer than intended, and makes one test's attachment contain another test's events.

Do not call removeAllListeners() on a shared object as a convenient teardown. It can remove listeners owned by Playwright integrations or other fixtures. Keep each callback reference and call off for only the subscriptions your recorder owns.

Suites that must stay below Playwright 1.60 can build the page-close part from established page-level events. Attach to pages that already exist, then attach the same callbacks whenever the context emits page:

import type { BrowserContext, Page } from '@playwright/test';

export function recordPageClosures(context: BrowserContext) {
  const closedUrls: string[] = [];
  const observedPages = new Set<Page>();

  const onPageClose = (page: Page) => {
    closedUrls.push(page.url());
  };
  const observe = (page: Page) => {
    if (observedPages.has(page)) return;
    observedPages.add(page);
    page.on('close', onPageClose);
  };
  const onNewPage = (page: Page) => observe(page);

  for (const page of context.pages()) observe(page);
  context.on('page', onNewPage);

  return {
    closedUrls,
    dispose() {
      context.off('page', onNewPage);
      for (const page of observedPages) {
        page.off('close', onPageClose);
      }
      observedPages.clear();
    },
  };
}

This compatibility layer costs more listener bookkeeping than the context-level pageclose event. It also demonstrates why a version-aware adapter is better than scattering conditional event names across tests. When the project upgrades, change the adapter and its contract tests while product tests continue consuming the same diagnostic attachment.

Do not register both approaches at once without labeling or deduplicating them. One physical page close would then produce two records and any count-based diagnosis would be misleading. During migration, select the implementation from the resolved Playwright version or move the whole diagnostic project to the newer API in one change.

Separate page loss, context loss, and browser loss

A failed action often ends with the broad message Target page, context or browser has been closed. The event ledger should tell you which layer disappeared.

One page closed while the context stayed usable

An application closes a payment popup after authorization. A later assertion still targets the popup and fails. The context ledger contains pageclose for that URL, but no contextclose. context.pages() may still contain the main application page, and context.isClosed() remains false on Playwright 1.59 or later.

That is a page ownership defect. Move post-payment assertions back to the opener, or capture the information needed before the popup closes. Closing the entire context in response would hide the real lifecycle and discard the main page.

A near-miss looks similar when a test closes its own page in afterEach, then another cleanup hook tries to take a screenshot. The application did not close the page. Hook ordering and resource ownership did. The stack in the HTML report points to cleanup code, while the ledger shows page closure before the screenshot attempt.

The context closed but the browser remained connected

An early helper calls context.close() on a context borrowed from the test. The ledger ends with page-close observations and contextclose, while browser.isConnected() remains true. A new context can still be created on that browser.

Record an intent marker in the owner immediately before the legitimate close call. If contextclose appears before that marker, another code path initiated closure. The close event itself cannot name that path, and increasing an action timeout will not reopen the context.

Do not assume the exact number of page-close entries proves a graceful context close. Some pages may have closed earlier, and a crash can interrupt event delivery. Assert the state and actions your code controls, then retain the ledger for diagnosis.

The browser disconnected and every context became invalid

Listen at the browser level when failures affect several contexts or projects in the same worker:

import type { Browser, BrowserContext } from '@playwright/test';

export function observeBrowser(browser: Browser) {
  const events: Array<{ sequence: number; type: string }> = [];
  let sequence = 0;
  const add = (type: string) => events.push({ sequence: ++sequence, type });

  const onContext = (_context: BrowserContext) => add('context-created');
  const onDisconnected = () => add('browser-disconnected');

  browser.on('context', onContext);
  browser.on('disconnected', onDisconnected);

  return {
    events,
    dispose() {
      browser.off('context', onContext);
      browser.off('disconnected', onDisconnected);
    },
  };
}

browser.on('context') requires Playwright 1.60. The disconnected event is older and can follow an explicit browser.close() as well as a closed or crashed browser application. Pair it with your own shutdown marker. If framework code intentionally closes the browser, the marker should precede the call. If disconnection arrives with no marker, investigate process exit, resource pressure, or external termination using the runner and operating-system logs.

The ledger cannot distinguish every browser crash from an external kill because both can look like disconnection to the client. Describe only what the evidence establishes. A disconnected browser plus no intended close is an unexpected browser loss; the process logs are where the lower-level cause belongs.

Nothing closed, but the expected event never occurred

An open context, connected browser, and expired page wait point back to the trigger or predicate. Verify that the click happened, that it was not blocked by a dialog, and that the new surface was actually a page. An iframe navigation does not create a new Page. A same-tab navigation does not create one either.

The trace should show the action and resulting navigation or popup. If it shows a popup before the wait was installed, fix the race. If it shows no popup, inspect application conditions rather than adding an event listener at a broader scope.

The test watched a different context

A second failure can end with the same event timeout even though the subscription was armed before the click. This happens when a custom authenticated-page fixture creates its own context, while the test or helper waits on the built-in context fixture. Both objects are valid, both remain open, and the trace for the authenticated page can show the popup. The awaited context never owned the opener, so it had no relevant page event to emit.

Check object ownership before investigating timing. page.context() === context should be true when that context is supposed to receive events from the page. This comparison is stronger than matching URLs, project names, or cookie values. Two independent contexts can open the same URL and hold similar authentication state without becoming the same owner.

Inspect both page inventories when the comparison is false. The context returned by page.context() should contain the opener and, while it remains open, its popup. The unrelated context will retain its own pages and show no change around the click. A popup created by a page stays in that page's browser context, so moving the wait to the actual owner repairs this failure. Moving the click or raising the timeout does not.

This evidence also separates the wrong-context defect from a late subscription. In a late-subscription case, the opener belongs to the watched context and the newly created page can already be present in that same context's inventory when the wait expires. In the ownership defect, the identity comparison is false before the trigger and the watched inventory never gains the popup. Capture that comparison before teardown, since closing both contexts afterward erases the useful distinction.

Do not force every helper to use one global context. Multi-user and multi-tenant tests legitimately operate several contexts. Pass the owning page and context together, or derive the context from the page when the helper only needs that relationship. The cost is a slightly wider helper contract and explicit labeling in multi-context tests. That cost is preferable to a helper that silently listens to whichever fixture happens to be in lexical scope.

Read lifecycle output as a boundary check

The most useful field in context-lifecycle.json is type. Read it with sequence and url, not as an isolated line. For a healthy popup path, the opener appears as a snapshot, a later entry has type page, and a later load observation may appear if the page reaches that browser event. A contextclose should appear only when the owner begins fixture teardown or another recorded close path runs.

A broken wrong-context run has a different shape. The watched attachment contains its original snapshots but no page entry for the popup. An inventory taken from page.context() contains the opener and popup instead. Add a small ownership fact beside the ledger for the failing action: whether the action page's context was the watched object, the number of pages in each object before the trigger, and the number present when the wait failed. A healthy ownership value is true. A false value is decisive evidence that the wait observed the wrong boundary.

Several values look reassuring but are not proof. browser.isConnected() can be true in both healthy and wrong-context runs because the browser transport is fine. context.isClosed() can be false while the test waits forever on an unrelated open context. A page count taken only after the failure can also mislead when a short-lived popup has already closed. The event entries and the before-trigger ownership fact preserve information that a late snapshot cannot reconstruct.

The url field is diagnostic context, not a stable page identifier. A callback can observe an initial URL that changes through navigation, and two pages can have the same URL. Use the page object relationship, event type, and action stack to establish ownership. Use the URL to help a reviewer recognize the surface after that boundary is known.

Use traces and ledgers together in CI

Trace Viewer records browser actions, DOM snapshots, network activity, console output, and errors for the configured attempt. A small Node-side lifecycle ledger adds fixture ownership and event scope that a page-centric trace may not answer.

Configure failure retention without automatically retaining every artifact:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['line'], ['html', { open: 'never' }]],
  use: {
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
  },
});

Run the smallest failing target with the project-local CLI and confirm event availability:

npx playwright --version
npx playwright test tests/invoice-popup.spec.ts \
  --project=chromium \
  --reporter=line \
  --trace=retain-on-failure

Read the artifacts in this order:

1. Find the first failed operation and its stack in the HTML report.
2. Check the trace to see whether the user action produced a popup, navigation, or closure.
3. Read context-lifecycle.json to determine whether the page, context, or browser lifecycle changed around that action.
4. Inspect worker and process logs if the browser disconnected without an intended close.

That sequence avoids overinterpreting the ledger. An event list says what callbacks observed, while the trace shows the application interaction that surrounded them.

Roll the recorder out behind an environment switch when the suite is large. Enable it for one project or a tag associated with target-closed flakes. Once ownership is repaired, keep a focused fixture contract test and remove broad collection from unrelated tests. Lifecycle attachments consume report space and can include URLs that your retention policy treats as sensitive.

When retries are enabled, compare attempts separately. A passing retry has new pages and usually a fresh test context. It cannot fill an event that the failed attempt missed. Retain the first failure and label each ledger with the test attempt or retry index through its attachment association in the report.

Introduce context evidence into an existing suite

Land a fixture contract test before attaching the recorder to product tests. The contract should create a page through each supported custom page fixture, verify which context owns it, open one controlled child page, and dispose every listener. This exposes fixture variants that return a page from one context while exporting another context under a familiar name. Those variants are usually the first break during rollout.

Next, enable the recorder for one browser project and one failure-prone directory. Keep product assertions and retry settings unchanged during that comparison. If failures suddenly move, the instrumentation changed behavior or listener lifetime rather than merely observing it. Check for duplicated event rows and attachments that contain activity from later tests, since those signal a listener left on a worker-scoped browser.

Once the contract is stable, migrate shared popup helpers. Make their ownership requirement explicit, then move call sites in small groups. Multi-context scenarios should label each ledger by role, such as buyer or administrator, instead of merging all entries into one stream. Expand collection to other projects only after the project-local Playwright versions support the event names the adapter uses.

The change is working when a failed page wait can be placed into one evidence-backed bucket: late subscription, wrong context, page closure, context closure, browser disconnection, or no qualifying page creation. It is also working when a passing test leaves no recorder listener behind. Do not use a falling retry rate alone as proof, since test order or application latency may have changed at the same time.

Collection has a concrete cost. Every subscribed event executes a callback, every retained entry occupies memory until attachment, and every URL increases report size and may enter sensitive retention. A focused lifecycle ledger costs far less than a context-wide network transcript, but it is not free. Keep it on failure-prone scopes, cap the fields to boundary evidence, and remove broad capture after the ownership defect is repaired.

Fixture-platform maintainers own context construction, recorder disposal, and the contract tests. The feature-test owner owns the trigger, predicate, and decision to use page or context scope. A browser-infrastructure owner takes over only when the evidence shows unexpected disconnection or process loss. The handoff should contain the test ID and attempt, project and browser version, failing action stack, the ownership comparison, both relevant page inventories, the lifecycle attachment, and any intended-close marker. It should not contain an entire browser profile or unredacted request data.

This technique does not catch a page that remains open but stops making progress. A renderer hang, an application deadlock, or a request that never settles can leave the page, context, and browser looking healthy in the lifecycle ledger. Diagnose that class with the stalled action's call log, trace, application logs, and a condition tied to the user-visible state. More close listeners add no evidence when nothing closes.

Know when an event listener makes the test worse

Do not subscribe to every context event as a default framework feature. A full request, response, console, page, frame, download, service-worker, and error recorder creates more evidence than a reviewer can use. It also increases memory, report size, and the chance of capturing secrets.

Prefer direct state when the state is what matters. If the question is whether the settings page is visible, use a locator assertion. A pageload listener is both broader and less meaningful. If the question is whether a specific request completed, use a one-shot response wait around the action rather than a permanent context listener.

Avoid context scope when page scope expresses the relationship. page.waitForEvent('popup') ties a popup to its opener. A context page listener can accidentally accept an unrelated tab. Broader scope is not stronger evidence.

Do not use event counts as performance metrics. Callback volume depends on application behavior, browser implementation, redirects, frames, service workers, and which listeners were installed when. Measure a documented user-facing duration with a purpose-built approach if performance is the requirement.

Finally, never leave diagnostic listeners attached to a worker-scoped browser after the owning fixture ends. The immediate cost is noisy artifacts. The deeper cost is broken isolation: later tests are now observed by state created for an earlier test. A recorder that cannot cleanly dispose its subscriptions is itself a lifecycle bug.