[pull] main from microsoft:main

.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 types

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.8
 

docs/src/aria-snapshots.md

@@ -307,6 +307,25 @@ Following snapshot will fail due to Feature C not being in the template:
   - listitem: Feature B
 ```
 
+#### Setting `children` mode globally
+
+Instead of adding a `/children` property to every snapshot, you can set the default children matching mode for all
+`toMatchAriaSnapshot` calls in the configuration file:
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  expect: {
+    toMatchAriaSnapshot: {
+      children: 'equal',
+    },
+  },
+});
+```
+
+Individual snapshots can still override the global setting by including an explicit `/children` property in the template.
+
 ### Matching with regular expressions
 
 Regular expressions allow flexible matching for elements with dynamic or variable text. Accessible names and text can

docs/src/test-api/class-testconfig.md

@@ -83,6 +83,7 @@ The structure of the git commit metadata is subject to change.
     - `pathTemplate` ?<[string]> A template controlling location of the screenshots. See [`property: TestConfig.snapshotPathTemplate`] for details.
   - `toMatchAriaSnapshot` ?<[Object]> Configuration for the [`method: LocatorAssertions.toMatchAriaSnapshot#2`] method.
     - `pathTemplate` ?<[string]> A template controlling location of the aria snapshots. See [`property: TestConfig.snapshotPathTemplate`] for details.
+    - `children` ?<["contain" | "equal" | "deep-equal"]> Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by including an explicit `/children` property.
   - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
     - `maxDiffPixels` ?<[int]> An acceptable amount of pixels that could be different, unset by default.
     - `maxDiffPixelRatio` ?<[float]> An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.

docs/src/test-api/class-testproject.md

@@ -101,6 +101,7 @@ export default defineConfig({
     - `pathTemplate` ?<[string]> A template controlling location of the screenshots. See [`property: TestProject.snapshotPathTemplate`] for details.
   - `toMatchAriaSnapshot` ?<[Object]> Configuration for the [`method: LocatorAssertions.toMatchAriaSnapshot#2`] method.
     - `pathTemplate` ?<[string]> A template controlling location of the aria snapshots. See [`property: TestProject.snapshotPathTemplate`] for details.
+    - `children` ?<["contain" | "equal" | "deep-equal"]> Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by including an explicit `/children` property.
   - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
     - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`.
     - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.

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.

packages/playwright-core/src/client/cdpSession.ts

@@ -30,6 +30,11 @@ export class CDPSession extends ChannelOwner<channels.CDPSessionChannel> impleme
 
     this._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;

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),

packages/playwright-core/src/server/dispatchers/cdpSessionDispatcher.ts

@@ -28,7 +28,10 @@ export class CDPSessionDispatcher extends Dispatcher<CDPSession, channels.CDPSes
   constructor(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> {