fix(api): migrate Screencast from events to onFrame callback (#39714)

Author: pavelfeldman

docs/src/api/class-screencast.md

@@ -4,43 +4,28 @@
 
 Interface for capturing screencast frames from a page.
 
-## event: Screencast.screencastFrame
+## async method: Screencast.start
 * since: v1.59
-- argument: <[Object]>
-  - `data` <[Buffer]> JPEG-encoded frame data.
+- returns: <[Disposable]>
 
-Emitted for each captured JPEG screencast frame while the screencast is running.
+Starts capturing screencast frames.
 
 **Usage**
 
 ```js
-const screencast = page.screencast;
-screencast.on('screencastframe', ({ data, width, height }) => {
-  console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
-  require('fs').writeFileSync('frame.jpg', data);
-});
-await screencast.start({ maxSize: { width: 1200, height: 800 } });
+await page.screencast.start(buffer => {
+  console.log(`frame size: ${buffer.length}`);
+}, { maxSize: { width: 800, height: 600 } });
 // ... perform actions ...
-await screencast.stop();
+await page.screencast.stop();
 ```
 
-## async method: Screencast.start
+### param: Screencast.start.onFrame
 * since: v1.59
-- returns: <[Disposable]>
-
-Starts capturing screencast frames. Frames are emitted as [`event: Screencast.screencastFrame`] events.
-
-**Usage**
+* langs: js
+- `onFrame` <[function]\([Buffer]\): [Promise<any>|any]>
 
-```js
-const screencast = page.screencast;
-screencast.on('screencastframe', ({ data, width, height }) => {
-  console.log(`frame ${width}x${height}, size: ${data.length}`);
-});
-await screencast.start({ maxSize: { width: 800, height: 600 } });
-// ... perform actions ...
-await screencast.stop();
-```
+Callback that receives JPEG-encoded frame data.
 
 ### option: Screencast.start.maxSize
 * since: v1.59
@@ -50,6 +35,7 @@ await screencast.stop();
 
 Maximum screencast frame dimensions. The output frame may be smaller to preserve the page aspect ratio. Defaults to 800×800.
 
+
 ## async method: Screencast.stop
 * since: v1.59
 
@@ -58,7 +44,7 @@ Stops the screencast started with [`method: Screencast.start`].
 **Usage**
 
 ```js
-await screencast.start();
+await screencast.start(buffer => { /* handle frame */ });
 // ... perform actions ...
 await screencast.stop();
 ```

packages/playwright-client/types/types.d.ts

@@ -21644,127 +21644,22 @@ export interface Route {
  */
 export interface Screencast {
   /**
-   * Emitted for each captured JPEG screencast frame while the screencast is running.
+   * Starts capturing screencast frames.
    *
    * **Usage**
    *
    * ```js
-   * const screencast = page.screencast;
-   * screencast.on('screencastframe', ({ data, width, height }) => {
-   *   console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
-   *   require('fs').writeFileSync('frame.jpg', data);
-   * });
-   * await screencast.start({ maxSize: { width: 1200, height: 800 } });
-   * // ... perform actions ...
-   * await screencast.stop();
-   * ```
-   *
-   */
-  on(event: 'screencastframe', listener: (data: {
-    /**
-     * JPEG-encoded frame data.
-     */
-    data: Buffer;
-  }) => 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: 'screencastframe', listener: (data: {
-    /**
-     * JPEG-encoded frame data.
-     */
-    data: Buffer;
-  }) => any): this;
-
-  /**
-   * Emitted for each captured JPEG screencast frame while the screencast is running.
-   *
-   * **Usage**
-   *
-   * ```js
-   * const screencast = page.screencast;
-   * screencast.on('screencastframe', ({ data, width, height }) => {
-   *   console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
-   *   require('fs').writeFileSync('frame.jpg', data);
-   * });
-   * await screencast.start({ maxSize: { width: 1200, height: 800 } });
+   * await page.screencast.start(buffer => {
+   *   console.log(`frame size: ${buffer.length}`);
+   * }, { maxSize: { width: 800, height: 600 } });
    * // ... perform actions ...
-   * await screencast.stop();
-   * ```
-   *
-   */
-  addListener(event: 'screencastframe', listener: (data: {
-    /**
-     * JPEG-encoded frame data.
-     */
-    data: Buffer;
-  }) => any): this;
-
-  /**
-   * Removes an event listener added by `on` or `addListener`.
-   */
-  removeListener(event: 'screencastframe', listener: (data: {
-    /**
-     * JPEG-encoded frame data.
-     */
-    data: Buffer;
-  }) => any): this;
-
-  /**
-   * Removes an event listener added by `on` or `addListener`.
-   */
-  off(event: 'screencastframe', listener: (data: {
-    /**
-     * JPEG-encoded frame data.
-     */
-    data: Buffer;
-  }) => any): this;
-
-  /**
-   * Emitted for each captured JPEG screencast frame while the screencast is running.
-   *
-   * **Usage**
-   *
-   * ```js
-   * const screencast = page.screencast;
-   * screencast.on('screencastframe', ({ data, width, height }) => {
-   *   console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
-   *   require('fs').writeFileSync('frame.jpg', data);
-   * });
-   * await screencast.start({ maxSize: { width: 1200, height: 800 } });
-   * // ... perform actions ...
-   * await screencast.stop();
-   * ```
-   *
-   */
-  prependListener(event: 'screencastframe', listener: (data: {
-    /**
-     * JPEG-encoded frame data.
-     */
-    data: Buffer;
-  }) => any): this;
-
-  /**
-   * Starts capturing screencast frames. Frames are emitted as
-   * [screencast.on('screencastframe')](https://playwright.dev/docs/api/class-screencast#screencast-event-screencast-frame)
-   * events.
-   *
-   * **Usage**
-   *
-   * ```js
-   * const screencast = page.screencast;
-   * screencast.on('screencastframe', ({ data, width, height }) => {
-   *   console.log(`frame ${width}x${height}, size: ${data.length}`);
-   * });
-   * await screencast.start({ maxSize: { width: 800, height: 600 } });
-   * // ... perform actions ...
-   * await screencast.stop();
+   * await page.screencast.stop();
    * ```
    *
+   * @param onFrame Callback that receives JPEG-encoded frame data.
    * @param options
    */
-  start(options?: {
+  start(onFrame: ((buffer: Buffer) => Promise<any>|any), options?: {
     /**
      * Maximum screencast frame dimensions. The output frame may be smaller to preserve the page aspect ratio. Defaults to
      * 800×800.
@@ -21784,12 +21679,12 @@ export interface Screencast {
 
   /**
    * Stops the screencast started with
-   * [screencast.start([options])](https://playwright.dev/docs/api/class-screencast#screencast-start).
+   * [screencast.start(onFrame[, options])](https://playwright.dev/docs/api/class-screencast#screencast-start).
    *
    * **Usage**
    *
    * ```js
-   * await screencast.start();
+   * await screencast.start(buffer => { /* handle frame *\/ });
    * // ... perform actions ...
    * await screencast.stop();
    * ```

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

@@ -15,26 +15,29 @@
  */
 
 import { DisposableStub } from './disposable';
-import { EventEmitter } from './eventEmitter';
 
 import type * as api from '../../types/types';
 import type { Page } from './page';
 
-export class Screencast extends EventEmitter implements api.Screencast {
+export class Screencast implements api.Screencast {
   private readonly _page: Page;
+  private _onFrame: ((buffer: Buffer) => any) | null = null;
 
   constructor(page: Page) {
-    super(page._platform);
     this._page = page;
-    this._page._channel.on('screencastFrame', ({ data }) => this.emit('screencastframe', { data }));
+    this._page._channel.on('screencastFrame', ({ data }) => {
+      this._onFrame?.(data);
+    });
   }
 
-  async start(options: { maxSize?: { width: number, height: number } } = {}) {
+  async start(onFrame: (buffer: Buffer) => any, options: { maxSize?: { width: number, height: number } } = {}): Promise<DisposableStub> {
+    this._onFrame = onFrame;
     await this._page._channel.startScreencast(options);
     return new DisposableStub(() => this.stop());
   }
 
   async stop(): Promise<void> {
+    this._onFrame = null;
     await this._page._channel.stopScreencast();
   }
 }

packages/playwright-core/src/tools/dashboard/dashboardController.ts

@@ -199,11 +199,13 @@ export class DashboardConnection implements Transport, DashboardChannel {
           if (frame === page.mainFrame())
             this._sendTabList();
         }),
-        eventsHelper.addEventListener(page.screencast, 'screencastframe', ({ data }) => this._writeFrame(data, page.viewportSize()?.width ?? 0, page.viewportSize()?.height ?? 0))
     );
 
     const maxSize = { width: 1280, height: 800 };
-    await page.screencast.start({ maxSize });
+    await page.screencast.start(
+        data => this._writeFrame(data, page.viewportSize()?.width ?? 0, page.viewportSize()?.height ?? 0),
+        { maxSize },
+    );
   }
 
   private _deselectPage() {