Implementation:Puppeteer Puppeteer CDPSession

Sources	packages/puppeteer-core/src/api/CDPSession.ts
Domains	Chrome DevTools Protocol, Session Management, Protocol Communication
Last Updated	2026-02-12

Overview

CDPSession is the abstract base class used to communicate with the Chrome DevTools Protocol, enabling direct protocol method calls and event subscriptions.

Description

The CDPSession class extends EventEmitter<CDPSessionEvents> and provides the low-level interface for sending raw CDP commands and receiving protocol events. Protocol methods are called with the send() method, which accepts a method name (typed against the full ProtocolMapping.Commands map), optional parameters, and an optional CommandOptions object with a timeout setting. Protocol events can be subscribed to via the inherited on() method from EventEmitter.

The class defines several session lifecycle events through the CDPSessionEvent namespace: internal symbols for Disconnected, Swapped, and Ready, plus public string events SessionAttached and SessionDetached for tracking child session attachment. The CDPSessionEvents interface extends CDPEvents (which maps all protocol event names to their payload types) and adds these session-specific events.

The connection() abstract method returns the underlying Connection instance (or undefined if detached). The detached getter indicates whether the session is still active. The detach() method disconnects the session from the target, after which no more events are emitted and no messages can be sent. The id() method returns the session's identifier. The parentSession() method returns the parent session in CDP's auto-attach mechanism (undefined by default).

Usage

CDPSession instances are created by calling Target.createCDPSession() or Page.createCDPSession(). They are used for advanced automation scenarios that require direct protocol-level access beyond Puppeteer's high-level API.

Code Reference

Source Location

packages/puppeteer-core/src/api/CDPSession.ts

Signature

export type CDPEvents = {
  [Property in keyof ProtocolMapping.Events]: ProtocolMapping.Events[Property][0];
};

export interface CommandOptions {
  timeout: number;
}

export abstract class CDPSession extends EventEmitter<CDPSessionEvents> {
  abstract connection(): Connection | undefined;
  abstract get detached(): boolean;
  parentSession(): CDPSession | undefined;
  abstract send<T extends keyof ProtocolMapping.Commands>(
    method: T,
    params?: ProtocolMapping.Commands[T]['paramsType'][0],
    options?: CommandOptions,
  ): Promise<ProtocolMapping.Commands[T]['returnType']>;
  abstract detach(): Promise<void>;
  abstract id(): string;
}

Import

import type {CDPSession, CDPSessionEvents, CommandOptions} from 'puppeteer-core/src/api/CDPSession.js';

I/O Contract

Inputs

Parameter	Type	Description
method (send)	T extends keyof ProtocolMapping.Commands	The CDP method name (e.g. 'Animation.enable')
params (send)	ProtocolMapping.Commands[T]['paramsType'][0]	Optional parameters for the CDP method
options (send)	CommandOptions	Optional command options with timeout

Outputs

Method	Return Type	Description
send()	Promise<ProtocolMapping.Commands[T]['returnType']>	The CDP method's return value
connection()	undefined	The underlying connection, or undefined if detached
detached	boolean	Whether the session has been detached
parentSession()	undefined	Parent session for auto-attach, or undefined
id()	string	The session identifier
detach()	Promise<void>	Resolves when the session is detached

Usage Examples

// Create a CDP session and interact with protocol
const client = await page.createCDPSession();
await client.send('Animation.enable');
client.on('Animation.animationCreated', () =>
  console.log('Animation created!'),
);
const response = await client.send('Animation.getPlaybackRate');
console.log('playback rate is ' + response.playbackRate);
await client.send('Animation.setPlaybackRate', {
  playbackRate: response.playbackRate / 2,
});

// Enable network monitoring via CDP
const client = await page.createCDPSession();
await client.send('Network.enable');
client.on('Network.requestWillBeSent', event => {
  console.log(`Request: ${event.request.url}`);
});
client.on('Network.responseReceived', event => {
  console.log(`Response: ${event.response.status} ${event.response.url}`);
});

// Detach the session when done
const client = await page.createCDPSession();
await client.send('Performance.enable');
const metrics = await client.send('Performance.getMetrics');
console.log(metrics);
await client.detach();
console.log(client.detached); // true

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime