Know which page called your Node callback

A callback arrives in Node with the right payload, but the report cannot tell whether the top page or a payment iframe sent it. The test passes until two pages run in parallel, then one page's event satisfies another page's assertion. The bridge works; the attribution does not.

exposeBinding() is useful when browser code needs to call a Node callback and the callback must know where the call originated. Playwright supplies the calling BrowserContext, Page, and Frame as the callback's first argument. That metadata solves a narrow problem. It does not prove the caller is trusted, preserve a complete business chronology, or replace a product assertion.

Understand what crosses the browser boundary

The BrowserContext API says that an exposed binding becomes a function on window in every frame of every page in that context. The page-level method covers every frame in one page. When browser code calls the function, Playwright runs the Node callback and returns a browser-side Promise. If the Node callback returns a Promise, Playwright waits for it before resolving the browser call.

The callback receives source metadata before the arguments supplied by the page. In TypeScript terms, the fields are source.context, source.page, and source.frame. That first name catches people out, because the value is a BrowserContext and the property is not called browserContext. Playwright declares the shape as BindingSource = { context: BrowserContext, page: Page, frame: Frame } in playwright-core's types/structs.d.ts, and logging Object.keys(source) inside a live callback prints exactly ["context", "page", "frame"]. If you are unsure which spelling your version uses, that one-line evaluation settles it faster than reading a guide. The three values are Playwright objects, not copied strings, so you can call page.url(), frame.url(), compare the frame with page.mainFrame(), or associate the Page object with an actor record maintained by the fixture.

Choose scope from ownership. Use page.exposeBinding() when one page and its child frames need the bridge. Use context.exposeBinding() when popups, newly created pages, or several tabs in the same context should call the same callback. A popup belongs to its opener's browser context, so a context binding is usually the right choice for a checkout flow that opens an identity-provider window.

exposeFunction() looks similar but omits caller metadata. It is suitable for a deterministic utility such as hashing a string when the result does not depend on which frame called. Replacing a binding with an exposed function in a multi-frame test can leave the calculation intact while removing the evidence needed to attribute it.

The direction often causes confusion. The function appears in browser JavaScript, but its implementation runs in the Playwright process. Browser code calls Node. It is not a way for Node to call an arbitrary function already defined by the application; page.evaluate() handles that direction. Naming a binding sendToNode or recordCheckpoint is clearer than naming it after a vague business action.

Source metadata answers "where did this call originate?" It does not answer "which DOM element caused it?" or "which user intended it?" A frame can call the binding from any script executing there. Include a small event type and correlation ID in the payload, and retain the product evidence that gives that event meaning.

Keep arguments plain and small. A diagnostic event usually needs a type, case ID, and non-secret value. Passing a full response body, access token, DOM dump, or application store across the bridge increases serialization cost and can put sensitive data in test reports. Record the minimum value needed to join the browser event to the test action.

The callback can slow the page. Browser code awaiting the binding also waits for Node work to finish. A callback that uploads a file, queries a slow database, or waits on another page can change the timing of the feature under test. Prefer an in-memory record and attach or persist it after the user action. If the test is specifically about backpressure, make that delay part of the scenario rather than an accidental fixture cost.

Attribute top-page and iframe calls separately

A useful mechanism test creates one call from the main frame and one from a child frame. It asserts frame identity, not a hard-coded list that could never change. If the callback ignores source.frame and marks every event as main-frame traffic, the test fails.

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

test('records whether the main frame or a child frame called Node', async ({ page }) => {
  const events: Array<{
    label: string;
    pageUrl: string;
    frameUrl: string;
    isMainFrame: boolean;
  }> = [];

  const registration = await page.exposeBinding(
    '__qaReport',
    (source, label: string) => {
      events.push({
        label,
        pageUrl: source.page.url(),
        frameUrl: source.frame.url(),
        isMainFrame: source.frame === source.page.mainFrame(),
      });
      return { accepted: true };
    },
  );

  await page.setContent(`
    <main>Main document</main>
    <iframe name="payment" srcdoc="<p>Payment frame</p>"></iframe>
  `);

  await page.evaluate(() => (window as any).__qaReport('top-page'));
  const child = page.frames().find(frame => frame !== page.mainFrame());
  if (!child)
    throw new Error('Expected the payment iframe to be attached');
  await child.evaluate(() => (window as any).__qaReport('payment-frame'));

  expect(events.map(event => ({ label: event.label, isMainFrame: event.isMainFrame })))
    .toEqual([
      { label: 'top-page', isMainFrame: true },
      { label: 'payment-frame', isMainFrame: false },
    ]);

  await registration.dispose();
});

The frame URL is retained for diagnosis, but the assertion does not assume a srcdoc frame has a particular URL string across browsers. The main-frame comparison is the stronger mechanism signal. In an application test, add a stable frame name, origin, or route expectation that belongs to the product.

Capture strings before the callback awaits anything. Page and Frame objects describe live browser targets. The page may navigate, the child frame may detach, and a later frame.url() can describe a different point in the flow. Snapshot page.url() and frame.url() at callback entry, then perform slower work. That keeps the event tied to the call rather than the time the attachment was written.

An iframe's URL alone may be insufficient. about:blank, srcdoc, same-origin frames with repeated routes, and redirected embeds can produce ambiguous strings. Compare the actual Frame object with known frames when possible, and combine URL with frame name or a product-owned marker. Avoid frame-array indexes; attach and navigation can change ordering.

The mechanism test invokes the binding through evaluate() so it can control both callers. A product test should not stop there. Trigger the real button, message, or application code that calls the binding, then assert the resulting user-visible or server-visible outcome. Otherwise the test proves Playwright can cross the bridge, not that the product uses the bridge correctly.

For a payment iframe, a strong product sequence might click "Confirm payment," record a sanitized checkpoint from the iframe, wait for the application's success response, and assert the order status. The binding event is diagnostic evidence between action and outcome. It is not a substitute for the order assertion.

Cover multiple pages without using a global event bucket

Context scope is valuable when several pages legitimately call one callback. It is also where global mutable state becomes dangerous. A module-level events array shared by parallel tests can let an event from test A satisfy test B. Keep the collection inside a test-scoped fixture or a single test and associate Page objects with local actor IDs.

The next example opens two pages in one isolated context, labels each Page object in a WeakMap, and proves that calls are attributed to the right page. Changing the map to return one fixed label makes the assertion fail. No URL guessing is needed.

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

test('attributes context-level calls to the page that sent them', async ({ context, page }) => {
  const pageNames = new WeakMap<Page, string>();
  const events: Array<{ pageName: string; checkpoint: string }> = [];
  pageNames.set(page, 'catalog');

  const registration = await context.exposeBinding(
    '__qaCheckpoint',
    (source, checkpoint: string) => {
      const pageName = pageNames.get(source.page);
      if (!pageName)
        throw new Error(`Unregistered page called __qaCheckpoint: ${source.page.url()}`);
      events.push({ pageName, checkpoint });
    },
  );

  const adminPage = await context.newPage();
  pageNames.set(adminPage, 'admin');

  await page.setContent('<h1>Catalog</h1>');
  await adminPage.setContent('<h1>Admin</h1>');
  await page.evaluate(() => (window as any).__qaCheckpoint('item-opened'));
  await adminPage.evaluate(() => (window as any).__qaCheckpoint('price-approved'));

  expect(events).toEqual([
    { pageName: 'catalog', checkpoint: 'item-opened' },
    { pageName: 'admin', checkpoint: 'price-approved' },
  ]);

  await registration.dispose();
});

The unknown-page branch is important. Silently labeling an unregistered page as "other" preserves execution while destroying attribution. A newly opened popup should force the fixture or test to register its identity. That failure tells the author the flow acquired a new page boundary that the evidence model does not yet understand.

For real popups, start waiting before the click that opens them. Once Playwright returns the popup Page, add it to the map before the application can emit the checkpoint you care about. If the popup calls the binding during its earliest startup script, the test may need context-level page lifecycle handling or an application handshake before emitting events. Do not solve that race with a fixed sleep.

Multiple contexts require separate registrations or an explicit context registry. A BrowserContext object in the source lets a shared callback identify the context, but one test should not depend on events from another test's context. Playwright Test's standard test-scoped context already provides a clean boundary. Preserve it rather than moving bindings to a worker-global browser for convenience.

Event order needs care. If browser code awaits the first binding call before making the second, array order expresses that sequence. If several frames call without awaiting, callbacks can overlap. Give each event a case ID and application sequence when order is part of the requirement. Arrival order in a Node array is not automatically the product's causal order.

A timestamp can help a person scan logs, but it is not a concurrency oracle. Clocks have resolution limits, and near-simultaneous events can share a timestamp. Assert explicit state transitions or sequence values owned by the application. If you include timestamps, label them as diagnostic observations rather than proof of ordering.

Build a fixture that validates and attaches evidence

A suite fixture should register before navigation, reject malformed payloads, keep records test-local, and dispose the binding after use. Validation matters because application JavaScript, third-party scripts, and compromised content within a covered frame can call the function. Source metadata tells you which frame called, not whether its arguments are safe.

The following fixture accepts one narrow event shape. It records worker and retry metadata from Playwright Test, snapshots source URLs immediately, and attaches the event list when a test does not finish with its expected status. The callback returns a small acknowledgement so browser code can decide whether recording succeeded.

import { test as base } from '@playwright/test';

type Checkpoint = { type: 'checkpoint'; caseId: string; name: string };
type BindingEvent = Checkpoint & {
  pageUrl: string;
  frameUrl: string;
  isMainFrame: boolean;
  workerIndex: number;
  retry: number;
};

function readCheckpoint(value: unknown): Checkpoint {
  if (!value || typeof value !== 'object')
    throw new Error('Checkpoint payload must be an object');

  const candidate = value as Record<string, unknown>;
  if (candidate.type !== 'checkpoint')
    throw new Error('Checkpoint payload has an unsupported type');
  if (typeof candidate.caseId !== 'string' || candidate.caseId.length === 0)
    throw new Error('Checkpoint payload requires a caseId');
  if (typeof candidate.name !== 'string' || candidate.name.length === 0)
    throw new Error('Checkpoint payload requires a name');

  return {
    type: 'checkpoint',
    caseId: candidate.caseId,
    name: candidate.name,
  };
}

export const test = base.extend<{ bindingEvents: BindingEvent[] }>({
  bindingEvents: async ({ context }, use, testInfo) => {
    const events: BindingEvent[] = [];
    const registration = await context.exposeBinding(
      '__qaCheckpoint',
      (source, rawPayload: unknown) => {
        const checkpoint = readCheckpoint(rawPayload);
        events.push({
          ...checkpoint,
          pageUrl: source.page.url(),
          frameUrl: source.frame.url(),
          isMainFrame: source.frame === source.page.mainFrame(),
          workerIndex: testInfo.workerIndex,
          retry: testInfo.retry,
        });
        return { accepted: true };
      },
    );

    await use(events);

    if (testInfo.status !== testInfo.expectedStatus) {
      await testInfo.attach('binding-events', {
        body: JSON.stringify(events, null, 2),
        contentType: 'application/json',
      });
    }
    await registration.dispose();
  },
});

export { expect } from '@playwright/test';

Registration is a fixture precondition. Tests that request bindingEvents receive the binding before their body runs. The application navigation should happen in the test body or in a fixture that depends on bindingEvents. If an independent page fixture navigates before this fixture is set up, parameter order alone is not a safe lifecycle design. Express the fixture dependency.

The validator has branches that can fail when the page sends the wrong type, missing case ID, or missing name. It does not check a hard-coded value against an array containing that same value. Product changes that corrupt the event shape produce a rejected browser-side Promise and a test failure at the boundary.

Only failure runs attach events in this example to control report size. A team investigating flakes may choose to attach every run for a limited project. That adds disk and potential data exposure. Decide retention based on actual debugging needs, and keep the schema sanitized so changing retention cannot leak tokens or personal data.

The Disposable returned by exposeBinding() is the supported removal handle in current Playwright. Disposing makes ownership explicit when a context is reused or when a binding is temporary. Closing a test-scoped context also removes its pages and state, but the explicit disposal prevents the fixture from silently depending on a broader teardown policy.

CI should run the attribution tests with parallel workers because a shared module array often stays hidden under serial execution. The job below uses the locked package manager before invoking Playwright and preserves the HTML report even when the test step fails.

name: Binding attribution checks

on:
  pull_request:

jobs:
  expose-binding:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Enable pnpm through Corepack
        run: corepack enable

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Install Chromium
        run: pnpm exec playwright install --with-deps chromium

      - name: Run binding attribution tests in parallel
        run: pnpm exec playwright test tests/binding-attribution.spec.ts --project=chromium --workers=4 --reporter=html

      - name: Upload the Playwright report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: binding-attribution-report
          path: playwright-report

Parallelism is not a claim that four workers are optimal. The value is illustrative wiring that exercises more than one test process. Choose worker count from the CI environment and suite behavior. The invariant is that every event list remains owned by one test attempt.

Distinguish wrong source, wrong timing, and wrong scope

When window.__qaCheckpoint is absent, check registration timing and scope first. Evaluate typeof window.__qaCheckpoint in the exact Page or Frame that should call it. If it is undefined in one page but present in another, the binding was probably exposed at page scope. If it is absent everywhere during initial script execution but appears later, fixture order is the likely cause.

An existing property with the same name is a different setup defect. Inventory test hooks before choosing the binding name, especially when several fixture libraries extend window. Registering two owners under one name should fail setup rather than allowing whichever fixture ran last to define the contract. A project-specific prefix reduces collisions, but the real fix is one documented owner and one disposal path.

After disposal, assert absence only when removal itself is part of the scenario. Most tests can trust the Disposable contract and context teardown. A dedicated lifecycle test can dispose the registration, check the function is no longer callable in a covered frame, then register a fresh binding under a new name. Repeating that assertion in every product test adds bridge testing without improving product coverage.

When the callback runs with an unexpected frame, retain pageUrl, frameUrl, the main-frame comparison, and a frame-tree snapshot from that point in the test. A locator aimed at the main page can trigger application code inside an iframe through postMessage, so the user action and callback source need not be the same frame. Decide which frame is supposed to own the callback based on application architecture.

When the right frame produces the wrong payload, do not relabel it as attribution failure. The source fields have done their job. Validate the payload, capture the calling route, and inspect the application code that assembled the event. A case ID copied from a module-level variable can be stale even when the callback comes from the correct page.

When events appear in another test, search for state outside the fixture. Module-level arrays, worker-scoped maps keyed only by page URL, and singleton reporters are common sources. Page URLs are not unique test identities. The same /checkout route can exist in every worker and retry. Include testInfo.testId or another attempt-owned key in the record if events must pass through a shared reporting service.

Retries deserve separate records. A failed first attempt and a passing retry can emit the same case ID. Keep testInfo.retry with every event and do not merge attempts into one unordered array. Otherwise an event from the failed attempt can make the retry appear complete before its own page produces anything.

When a test times out inside the browser call, inspect the Node callback for awaited work. Because the browser receives a Promise tied to the callback, a pending callback can hold application code. Add bounded operations and move report uploads out of the callback. Do not increase the Playwright test timeout until you know which awaited operation is slow.

When no event appears but the product succeeds, ask whether the bridge is still part of the product path. A refactor may have removed the call while preserving the user outcome. If the binding is only diagnostic, the missing event can be a test instrumentation change rather than a regression. Decide whether event presence is a release requirement or optional evidence and encode the assertion accordingly.

Browser console output is a useful companion. A page-side rejected Promise can be caught and logged by application code, hiding the binding error from the final UI assertion. Listen for relevant console errors or expose a visible test-only status during development. Do not make every unrelated console warning fail the suite; filter to the binding contract you own.

The trace can show the user action and resulting page state, but do not assume it automatically provides your custom Node event schema. Attach the sanitized binding records yourself, as the fixture does. Then a reviewer can compare action timing, frame identity, payload, and final assertion without inferring the callback from unrelated network traffic.

Roll out the bridge without turning it into a back door

Start with a single event whose value is hard to obtain from existing Playwright signals. Good candidates include an application-owned checkpoint emitted inside a third-party iframe integration or a deterministic callback from a canvas workflow. If a locator, response event, or application API already exposes the same result, prefer that existing boundary.

Prefix test-only binding names and install them only in test contexts. Application code should feature-detect the function and have a clear non-test path. Do not ship a production flow that fails because window.__qaCheckpoint is absent. The bridge belongs to observability, not core business execution.

Review the callback as if browser input were external input. Allow-list event types, constrain string sizes, reject unexpected fields when they matter, and redact before attachment. Never expose a generic file reader, shell runner, database client, environment lookup, or arbitrary HTTP proxy. A compromised page or third-party frame within scope could call it.

Move from page scope to context scope only when a real popup or second page requires it. That expansion lets every frame in every page in the context call the function. Update the source allow-list and add an unknown-page rejection test before broadening. Convenience is not enough reason to enlarge the caller set.

Measure overhead from real tests if callback volume grows. A checkpoint per business milestone is easier to reason about than a callback for every DOM mutation or network event. High-frequency telemetry belongs in browser-native logging or an application telemetry pipeline designed for volume. The binding crosses processes and can perturb timing.

During migration, keep old and new evidence paths side by side for a small set of scenarios. Compare whether both identify the same case and outcome. Remove the old hook only after the new callback has distinct rejection tests for wrong frame, wrong payload, missing registration, and cross-test leakage. Do not publish invented reliability percentages; retain actual mismatches and their causes.

Document who owns the binding name, schema, and retention. Test authors own assertions. Application teams own the point where the event is emitted. Framework owners own fixture scope and cleanup. Security or privacy reviewers should approve any payload that can contain user data. Clear ownership prevents a small callback from becoming an undocumented internal API.

Avoid exposeBinding when a simpler signal is stronger

Use page.evaluate() for a one-time read or invocation controlled entirely by the test. It avoids placing a callable function on every covered frame. Use exposeFunction() when browser code needs a Node utility but caller page and frame do not affect the result.

Prefer Playwright's request, response, console, download, dialog, and page events when those are the actual product boundaries. A binding that duplicates a network response adds another source of truth. If the two disagree, the suite must decide which one defines success. Usually the user-visible state or server response should remain authoritative.

Do not use a binding to bypass the UI action the test claims to cover. Calling a Node database helper from the page to mark an order paid may make the final screen green while skipping payment behavior. Prepare data through owned API fixtures before the test, then drive and assert the product path honestly.

Avoid it for untrusted browsing sessions that can reach arbitrary sites. Context-level exposure gives every frame in those pages a callable path into Node. If the scenario navigates user-supplied URLs, keep privileged callbacks out of that context and use external observation instead.

Skip source metadata when all calls intentionally come from one known page and no child frame can invoke the function. The extra event model, validation, attachments, and mapping may not earn their maintenance cost. A narrow exposed function or direct evaluation can be clearer.

Finally, do not preserve a binding merely because tests already depend on it. Ask what defect its source-aware evidence can catch. Wrong-frame callbacks, popup attribution, retry leakage, and cross-test contamination are defensible answers. "The callback returned" is not. The bridge is valuable when it makes a real failure attributable and still leaves the final product assertion capable of failing.