Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
feat(cdp): add 'event' and 'close' events to CDPSession (#39552)
Yury Semikhatsky2a31eea2eec7
diff --git a/.claude/skills/playwright-dev/api.md b/.claude/skills/playwright-dev/api.mdindex 06431bbe61..2ef9ecb7d4 100644--- a/.claude/skills/playwright-dev/api.md+++ b/.claude/skills/playwright-dev/api.md@@ -30,7 +30,7 @@ Description of the option.```**Key syntax rules:**-- `* since: v1.XX` — version from package.json (without -next)+- `* since: v1.XX` — always take the version from package.json (without -next)- `* langs: js, python` — language filter (optional)- `* langs: alias-java: navigate` — language-specific method name- `* deprecated: v1.XX` — deprecation marker@@ -60,6 +60,8 @@ Description.Description.```+Keep methods, events and property definitions sorted alphabetically within the file.+Watch will kick in and auto-generate:- `packages/playwright-core/types/types.d.ts` — public API types- `packages/playwright/types/test.d.ts` — test API typesdiff --git a/docs/src/api/class-cdpsession.md b/docs/src/api/class-cdpsession.mdindex a14dd58fb4..8efa8e1da7 100644--- a/docs/src/api/class-cdpsession.md+++ b/docs/src/api/class-cdpsession.md@@ -67,6 +67,30 @@ params.addProperty("playbackRate", playbackRate / 2);client.send("Animation.setPlaybackRate", params);```+## event: CDPSession.close+* since: v1.59+* langs: js++Emitted when the session is closed, either because the target was closed or `session.detach()` was called.++## event: CDPSession.event+* since: v1.59+* langs: js+- argument: <[Object]>+ - `name` <[string]> CDP event name.+ - `params` ?<[Object]> CDP event parameters.++Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+their names ahead of time.++**Usage**++```js+session.on('event', ({ name, params }) => {+ console.log(`CDP event: ${name}`, params);+});+```+## async method: CDPSession.detach* since: v1.8diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.tsindex 815eb462af..2048ef3665 100644--- a/packages/playwright-client/types/types.d.ts+++ b/packages/playwright-client/types/types.d.ts@@ -16023,11 +16023,11 @@ export interface BrowserType<Unused = {}> {**/export interface CDPSession {- on: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- addListener: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- off: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- removeListener: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- once: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;+ on<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ addListener<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ off<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ removeListener<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ once<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;/*** @param method Protocol method name.* @param params Optional method parameters.@@ -16036,6 +16036,156 @@ export interface CDPSession {method: T,params?: Protocol.CommandParameters[T]): Promise<Protocol.CommandReturnValues[T]>;+ /**+ * Emitted when the session is closed, either because the target was closed or `session.detach()` was called.+ */+ on(event: 'close', listener: () => any): this;++ /**+ * Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+ * their names ahead of time.+ *+ * **Usage**+ *+ * ```js+ * session.on('event', ({ name, params }) => {+ * console.log(`CDP event: ${name}`, params);+ * });+ * ```+ *+ */+ on(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.+ */+ once(event: 'close', listener: () => any): this;++ /**+ * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.+ */+ once(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Emitted when the session is closed, either because the target was closed or `session.detach()` was called.+ */+ addListener(event: 'close', listener: () => any): this;++ /**+ * Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+ * their names ahead of time.+ *+ * **Usage**+ *+ * ```js+ * session.on('event', ({ name, params }) => {+ * console.log(`CDP event: ${name}`, params);+ * });+ * ```+ *+ */+ addListener(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ removeListener(event: 'close', listener: () => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ removeListener(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ off(event: 'close', listener: () => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ off(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Emitted when the session is closed, either because the target was closed or `session.detach()` was called.+ */+ prependListener(event: 'close', listener: () => any): this;++ /**+ * Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+ * their names ahead of time.+ *+ * **Usage**+ *+ * ```js+ * session.on('event', ({ name, params }) => {+ * console.log(`CDP event: ${name}`, params);+ * });+ * ```+ *+ */+ prependListener(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;+/*** Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be* used to send messages.diff --git a/packages/playwright-core/src/client/cdpSession.ts b/packages/playwright-core/src/client/cdpSession.tsindex 0a58f79d27..25f374af79 100644--- a/packages/playwright-core/src/client/cdpSession.ts+++ b/packages/playwright-core/src/client/cdpSession.ts@@ -30,6 +30,11 @@ export class CDPSession extends ChannelOwner<channels.CDPSessionChannel> implemethis._channel.on('event', ({ method, params }) => {this.emit(method, params);+ this.emit('event', { name: method, params });+ });++ this._channel.on('close', () => {+ this.emit('close');});this.on = super.on;diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.tsindex 1a64a527bc..2eea4cb028 100644--- a/packages/playwright-core/src/protocol/validator.ts+++ b/packages/playwright-core/src/protocol/validator.ts@@ -2609,6 +2609,7 @@ scheme.CDPSessionEventEvent = tObject({method: tString,params: tOptional(tAny),});+scheme.CDPSessionCloseEvent = tOptional(tObject({}));scheme.CDPSessionSendParams = tObject({method: tString,params: tOptional(tAny),diff --git a/packages/playwright-core/src/server/dispatchers/cdpSessionDispatcher.ts b/packages/playwright-core/src/server/dispatchers/cdpSessionDispatcher.tsindex 58d785705e..8e16795e24 100644--- a/packages/playwright-core/src/server/dispatchers/cdpSessionDispatcher.ts+++ b/packages/playwright-core/src/server/dispatchers/cdpSessionDispatcher.ts@@ -28,7 +28,10 @@ export class CDPSessionDispatcher extends Dispatcher<CDPSession, channels.CDPSesconstructor(scope: BrowserDispatcher | BrowserContextDispatcher, cdpSession: CDPSession) {super(scope, cdpSession, 'CDPSession', {});this.addObjectListener(CDPSession.Events.Event, ({ method, params }) => this._dispatchEvent('event', { method, params }));- this.addObjectListener(CDPSession.Events.Closed, () => this._dispose());+ this.addObjectListener(CDPSession.Events.Closed, () => {+ this._dispatchEvent('close');+ this._dispose();+ });}async send(params: channels.CDPSessionSendParams, progress: Progress): Promise<channels.CDPSessionSendResult> {diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.tsindex 815eb462af..2048ef3665 100644--- a/packages/playwright-core/types/types.d.ts+++ b/packages/playwright-core/types/types.d.ts@@ -16023,11 +16023,11 @@ export interface BrowserType<Unused = {}> {**/export interface CDPSession {- on: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- addListener: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- off: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- removeListener: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- once: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;+ on<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ addListener<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ off<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ removeListener<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ once<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;/*** @param method Protocol method name.* @param params Optional method parameters.@@ -16036,6 +16036,156 @@ export interface CDPSession {method: T,params?: Protocol.CommandParameters[T]): Promise<Protocol.CommandReturnValues[T]>;+ /**+ * Emitted when the session is closed, either because the target was closed or `session.detach()` was called.+ */+ on(event: 'close', listener: () => any): this;++ /**+ * Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+ * their names ahead of time.+ *+ * **Usage**+ *+ * ```js+ * session.on('event', ({ name, params }) => {+ * console.log(`CDP event: ${name}`, params);+ * });+ * ```+ *+ */+ on(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.+ */+ once(event: 'close', listener: () => any): this;++ /**+ * Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.+ */+ once(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Emitted when the session is closed, either because the target was closed or `session.detach()` was called.+ */+ addListener(event: 'close', listener: () => any): this;++ /**+ * Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+ * their names ahead of time.+ *+ * **Usage**+ *+ * ```js+ * session.on('event', ({ name, params }) => {+ * console.log(`CDP event: ${name}`, params);+ * });+ * ```+ *+ */+ addListener(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ removeListener(event: 'close', listener: () => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ removeListener(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ off(event: 'close', listener: () => any): this;++ /**+ * Removes an event listener added by `on` or `addListener`.+ */+ off(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;++ /**+ * Emitted when the session is closed, either because the target was closed or `session.detach()` was called.+ */+ prependListener(event: 'close', listener: () => any): this;++ /**+ * Emitted for every CDP event received from the session. Allows subscribing to all CDP events at once without knowing+ * their names ahead of time.+ *+ * **Usage**+ *+ * ```js+ * session.on('event', ({ name, params }) => {+ * console.log(`CDP event: ${name}`, params);+ * });+ * ```+ *+ */+ prependListener(event: 'event', listener: (data: {+ /**+ * CDP event name.+ */+ name: string;++ /**+ * CDP event parameters.+ */+ params?: Object;+ }) => any): this;+/*** Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be* used to send messages.diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.tsindex b5b4c0407c..4773a2875e 100644--- a/packages/protocol/src/channels.d.ts+++ b/packages/protocol/src/channels.d.ts@@ -4550,6 +4550,7 @@ export interface WritableStreamEvents {export type CDPSessionInitializer = {};export interface CDPSessionEventTarget {on(event: 'event', callback: (params: CDPSessionEventEvent) => void): this;+ on(event: 'close', callback: (params: CDPSessionCloseEvent) => void): this;}export interface CDPSessionChannel extends CDPSessionEventTarget, Channel {_type_CDPSession: boolean;@@ -4560,6 +4561,7 @@ export type CDPSessionEventEvent = {method: string,params?: any,};+export type CDPSessionCloseEvent = {};export type CDPSessionSendParams = {method: string,params?: any,@@ -4576,6 +4578,7 @@ export type CDPSessionDetachResult = void;export interface CDPSessionEvents {'event': CDPSessionEventEvent;+ 'close': CDPSessionCloseEvent;}// ----------- Electron -----------diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.ymlindex 8114c4099d..d5254a0af5 100644--- a/packages/protocol/src/protocol.yml+++ b/packages/protocol/src/protocol.yml@@ -3989,6 +3989,8 @@ CDPSession:method: stringparams: json?+ close:+Electron:type: interfacediff --git a/tests/library/chromium/session.spec.ts b/tests/library/chromium/session.spec.tsindex c2069a7a3c..5e7789b7bd 100644--- a/tests/library/chromium/session.spec.ts+++ b/tests/library/chromium/session.spec.ts@@ -146,6 +146,36 @@ browserTest('should reject protocol calls when page closes', async function({ brawait context.close();});+it('should emit event for each CDP event', async function({ page, server }) {+ const client = await page.context().newCDPSession(page);+ await client.send('Network.enable');+ const events = [];+ client.on('event', event => events.push(event));+ await page.goto(server.EMPTY_PAGE);+ expect(events.length).toBeGreaterThan(0);+ const requestEvent = events.find(e => e.name === 'Network.requestWillBeSent');+ expect(requestEvent).toBeTruthy();+ expect(requestEvent.params.request.url).toBe(server.EMPTY_PAGE);+});++it('should emit close event when session is detached', async function({ page }) {+ const client = await page.context().newCDPSession(page);+ let closeFired = false;+ client.on('close', () => closeFired = true);+ await client.detach();+ expect(closeFired).toBe(true);+});++browserTest('should emit close event when page closes', async function({ browser }) {+ const context = await browser.newContext();+ const page = await context.newPage();+ const session = await context.newCDPSession(page);+ const closePromise = new Promise<void>(f => session.on('close', f));+ await page.close();+ await closePromise;+ await context.close();+});+browserTest('should work with newBrowserCDPSession', async function({ browser }) {const session = await browser.newBrowserCDPSession();diff --git a/utils/generate_types/overrides.d.ts b/utils/generate_types/overrides.d.tsindex d34403fb5d..f5677d8f61 100644--- a/utils/generate_types/overrides.d.ts+++ b/utils/generate_types/overrides.d.ts@@ -229,11 +229,11 @@ export interface BrowserType<Unused = {}> {}export interface CDPSession {- on: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- addListener: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- off: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- removeListener: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;- once: <T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void) => this;+ on<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ addListener<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ off<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ removeListener<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;+ once<T extends keyof Protocol.Events | symbol>(event: T, listener: (payload: T extends symbol ? any : Protocol.Events[T extends keyof Protocol.Events ? T : never]) => void): this;send<T extends keyof Protocol.CommandParameters>(method: T,params?: Protocol.CommandParameters[T]