Implementation:Microsoft Playwright Client Instrumentation

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, Observability
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for providing client-side instrumentation hooks for API call tracing, lifecycle events, and test framework integration provided by the Playwright library.

Description

This module defines the ClientInstrumentation interface and ClientInstrumentationListener interface, along with a createInstrumentation() factory function. The instrumentation system uses a Proxy-based implementation that dynamically dispatches method calls to registered listeners. Methods prefixed with on (e.g., onApiCallBegin, onApiCallEnd, onWillPause, onPage) are called synchronously on all listeners. Methods prefixed with run (e.g., runBeforeCreateBrowserContext, runAfterCreateBrowserContext, runBeforeCloseBrowserContext) are called asynchronously and awaited sequentially. The ApiCallData interface captures call metadata including API name, stack frames, user data, step ID, and error state.

Usage

Use the instrumentation system when building test runners or tools that need to observe Playwright API calls. Register a ClientInstrumentationListener to receive notifications about API call lifecycle, page creation, browser context creation/closure, and request context creation/closure.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/clientInstrumentation.ts

Signature

export interface ApiCallData {
  apiName: string;
  title?: string;
  frames: StackFrame[];
  userData: any;
  stepId?: string;
  error?: Error;
}

export interface ClientInstrumentation {
  addListener(listener: ClientInstrumentationListener): void;
  removeListener(listener: ClientInstrumentationListener): void;
  removeAllListeners(): void;
  onApiCallBegin(apiCall: ApiCallData, channel: { type: string; method: string; params?: Record<string, any> }): void;
  onApiCallEnd(apiCall: ApiCallData): void;
  onWillPause(options: { keepTestTimeout: boolean }): void;
  onPage(page: Page): void;
  runBeforeCreateBrowserContext(options: BrowserContextOptions): Promise<void>;
  runBeforeCreateRequestContext(options: NewContextOptions): Promise<void>;
  runAfterCreateBrowserContext(context: BrowserContext): Promise<void>;
  runAfterCreateRequestContext(context: APIRequestContext): Promise<void>;
  runBeforeCloseBrowserContext(context: BrowserContext): Promise<void>;
  runBeforeCloseRequestContext(context: APIRequestContext): Promise<void>;
}

export interface ClientInstrumentationListener { /* optional mirrors of ClientInstrumentation methods */ }

export function createInstrumentation(): ClientInstrumentation;

Import

import { createInstrumentation } from 'playwright-core/src/client/clientInstrumentation';
import type { ClientInstrumentation, ClientInstrumentationListener, ApiCallData } from 'playwright-core/src/client/clientInstrumentation';

I/O Contract

Inputs

Name	Type	Required	Description
listener	ClientInstrumentationListener	Yes	A listener object implementing optional instrumentation callbacks

Outputs

Name	Type	Description
createInstrumentation()	ClientInstrumentation	A Proxy-based instrumentation instance that dispatches to registered listeners

Usage Examples

const instrumentation = createInstrumentation();

instrumentation.addListener({
  onApiCallBegin(apiCall, channel) {
    console.log(`API call started: ${apiCall.apiName} -> ${channel.type}.${channel.method}`);
  },
  onApiCallEnd(apiCall) {
    if (apiCall.error) {
      console.error(`API call failed: ${apiCall.apiName}`, apiCall.error);
    } else {
      console.log(`API call completed: ${apiCall.apiName}`);
    }
  },
  async runAfterCreateBrowserContext(context) {
    console.log('New browser context created');
  },
});

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment