Implementation:Microsoft Playwright DebugController

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

Overview

Concrete tool for coordinating the Playwright Inspector debug UI, element inspection, and code recording provided by the Playwright library.

Description

The `DebugController` class extends `SdkObject` and serves as the central coordinator for Playwright's debugging and inspection capabilities. It manages the Recorder for code generation, tracks browser context hierarchy via an `InstrumentationListener`, and emits events for state changes, inspect requests, source code changes, and pause states. Key methods include `setReportStateChanged` for toggling hierarchy tracking, `resetForReuse` for clearing contexts, `navigate` and `setRecorderMode` for controlling the recorder, `highlight` and `hideHighlight` for element highlighting, and `ariaSnapshot` for accessibility tree snapshots. It supports multiple SDK languages for code generation.

Usage

Use DebugController when integrating with the Playwright Inspector or when building custom debugging tooling that needs to control recording, inspection, and step-through capabilities.

Code Reference

Source Location

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

Signature

export class DebugController extends SdkObject {
  static Events: {
    StateChanged: string;
    InspectRequested: string;
    SourceChanged: string;
    Paused: string;
    SetModeRequested: string;
  };
  constructor(playwright: Playwright);
  initialize(codegenId: string, sdkLanguage: Language): void;
  dispose(): void;
  setReportStateChanged(enabled: boolean): void;
  async resetForReuse(): Promise<void>;
  async navigate(progress: Progress, url: string): Promise<void>;
  async setRecorderMode(progress: Progress, params: { mode: Mode }): Promise<void>;
  async highlight(progress: Progress, selector: string): Promise<void>;
  async hideHighlight(progress: Progress): Promise<void>;
}

Import

import { DebugController } from '../server/debugController';

I/O Contract

Inputs

Name	Type	Required	Description
playwright	Playwright	Yes	The Playwright instance to control
sdkLanguage	Language	Yes	Target language for code generation (javascript, python, etc.)
progress	Progress	Yes	Progress tracker for async operations
selector	string	Yes (highlight)	CSS/Playwright selector to highlight

Outputs

Name	Type	Description
(events)	StateChanged, InspectRequested, SourceChanged, Paused	Events emitted during debug operations

Usage Examples

import { DebugController } from '../server/debugController';

const controller = new DebugController(playwright);
controller.initialize('codegen', 'javascript');
controller.setReportStateChanged(true);
controller.on(DebugController.Events.StateChanged, (state) => {
  console.log('Debug state changed:', state);
});
await controller.setRecorderMode(progress, { mode: 'recording' });

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment