Implementation:Microsoft Playwright Debugger

Knowledge Sources	Microsoft_Playwright
Domains	Server, Debugging
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for implementing step-by-step debugging and pause/resume control for Playwright actions provided by the Playwright library.

Description

The `Debugger` class extends `EventEmitter` and implements `InstrumentationListener` to provide pause/resume functionality during Playwright test execution. It intercepts method calls via `onBeforeCall` and can pause execution based on explicit `page.pause()` calls or when `_pauseOnNextStatement` is enabled (activated by `PWDEBUG=inspector` or programmatically). Paused calls are tracked in a map of `_pausedCallsMetadata`, and the debugger emits `PausedStateChanged` events. The `resume` method releases all paused calls, while `pauseOnNextStatement` sets the flag for the next pausable action. The debugger can be muted to temporarily disable pause behavior.

Usage

Use Debugger when implementing the `page.pause()` API or the Playwright Inspector's step-through debugging, where test execution needs to be paused at specific Playwright actions.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/server/debugger.ts

Signature

export class Debugger extends EventEmitter implements InstrumentationListener {
  static Events: { PausedStateChanged: string };
  constructor(context: BrowserContext);
  async setMuted(muted: boolean): Promise<void>;
  async onBeforeCall(sdkObject: SdkObject, metadata: CallMetadata): Promise<void>;
  async onAfterCall(sdkObject: SdkObject, metadata: CallMetadata): Promise<void>;
  async pause(sdkObject: SdkObject, metadata: CallMetadata): Promise<void>;
  resume(step: boolean): void;
  pauseOnNextStatement(): void;
  isPaused(metadata?: CallMetadata): boolean;
}

Import

import { Debugger } from '../server/debugger';

I/O Contract

Inputs

Name	Type	Required	Description
context	BrowserContext	Yes	The browser context to attach the debugger to
sdkObject	SdkObject	Yes (pause)	The SDK object being acted upon
metadata	CallMetadata	Yes (pause)	Metadata about the call being paused

Outputs

Name	Type	Description
isPaused	boolean	Whether the debugger is currently in a paused state
(events)	PausedStateChanged	Event emitted when pause state changes

Usage Examples

import { Debugger } from '../server/debugger';

const debugger_ = new Debugger(browserContext);
debugger_.on(Debugger.Events.PausedStateChanged, () => {
  console.log('Paused:', debugger_.isPaused());
});
debugger_.pauseOnNextStatement();
// Next Playwright action will pause execution
debugger_.resume(false); // Resume all paused calls

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment