feat(video): add screencast mode to Video.start for JPEG frame events

docs/src/api/class-inspector.md

@@ -0,0 +1,77 @@
+# class: Inspector
+* since: v1.59
+* langs: js
+
+Interface to the Playwright inspector.
+
+**Usage**
+
+```js
+const inspector = page.inspector();
+inspector.on('screencastframe', ({ data, width, height }) => {
+  console.log(`received frame ${width}x${height}, jpeg size: ${data.length}`);
+});
+await inspector.startScreencast();
+// ... perform actions ...
+await inspector.stopScreencast();
+```
+
+## event: Inspector.screencastFrame
+* since: v1.59
+- argument: <[Object]>
+  - `data` <[Buffer]> JPEG-encoded frame data.
+  - `width` <[int]> Frame width in pixels.
+  - `height` <[int]> Frame height in pixels.
+
+Emitted for each captured JPEG screencast frame while the screencast is running.
+
+**Usage**
+
+```js
+const inspector = page.inspector();
+inspector.on('screencastframe', ({ data, width, height }) => {
+  console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
+  require('fs').writeFileSync('frame.jpg', data);
+});
+await inspector.startScreencast({ size: { width: 1280, height: 720 } });
+// ... perform actions ...
+await inspector.stopScreencast();
+```
+
+## async method: Inspector.startScreencast
+* since: v1.59
+
+Starts capturing screencast frames. Frames are emitted as [`event: Inspector.screencastFrame`] events.
+
+**Usage**
+
+```js
+const inspector = page.inspector();
+inspector.on('screencastframe', ({ data, width, height }) => {
+  console.log(`frame ${width}x${height}, size: ${data.length}`);
+});
+await inspector.startScreencast({ size: { width: 800, height: 600 } });
+// ... perform actions ...
+await inspector.stopScreencast();
+```
+
+### option: Inspector.startScreencast.size
+* since: v1.59
+- `size` ?<[Object]>
+  - `width` <[int]> Frame width in pixels.
+  - `height` <[int]> Frame height in pixels.
+
+Optional dimensions for the screencast frames. If not specified, the current page viewport size is used.
+
+## async method: Inspector.stopScreencast
+* since: v1.59
+
+Stops the screencast started with [`method: Inspector.startScreencast`].
+
+**Usage**
+
+```js
+await inspector.startScreencast();
+// ... perform actions ...
+await inspector.stopScreencast();
+```

docs/src/api/class-page.md

@@ -2597,6 +2597,25 @@ Throws for non-input elements. However, if the element is inside the `<label>` e
 ### option: Page.inputValue.timeout = %%-input-timeout-js-%%
 * since: v1.13
 
+## method: Page.inspector
+* since: v1.59
+* langs: js
+- returns: <[Inspector]>
+
+Returns the [Inspector] object associated with this page.
+
+**Usage**
+
+```js
+const inspector = page.inspector();
+inspector.on('screencastFrame', data => {
+  console.log('received frame, jpeg size:', data.length);
+});
+await inspector.startScreencast();
+// ... perform actions ...
+await inspector.stopScreencast();
+```
+
 ## async method: Page.isChecked
 * since: v1.8
 * discouraged: Use locator-based [`method: Locator.isChecked`] instead. Read more about [locators](../locators.md).

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

@@ -3508,6 +3508,24 @@ export interface Page {
     timeout?: number;
   }): Promise<string>;
 
+  /**
+   * Returns the [Inspector](https://playwright.dev/docs/api/class-inspector) object associated with this page.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const inspector = page.inspector();
+   * inspector.on('screencastFrame', data => {
+   *   console.log('received frame, jpeg size:', data.length);
+   * });
+   * await inspector.startScreencast();
+   * // ... perform actions ...
+   * await inspector.stopScreencast();
+   * ```
+   *
+   */
+  inspector(): Inspector;
+
   /**
    * **NOTE** Use locator-based [locator.isChecked([options])](https://playwright.dev/docs/api/class-locator#locator-is-checked)
    * instead. Read more about [locators](https://playwright.dev/docs/locators).
@@ -20418,6 +20436,237 @@ export interface FrameLocator {
   owner(): Locator;
 }
 
+/**
+ * Interface to the Playwright inspector.
+ *
+ * **Usage**
+ *
+ * ```js
+ * const inspector = page.inspector();
+ * inspector.on('screencastframe', ({ data, width, height }) => {
+ *   console.log(`received frame ${width}x${height}, jpeg size: ${data.length}`);
+ * });
+ * await inspector.startScreencast();
+ * // ... perform actions ...
+ * await inspector.stopScreencast();
+ * ```
+ *
+ */
+export interface Inspector {
+  /**
+   * Emitted for each captured JPEG screencast frame while the screencast is running.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const inspector = page.inspector();
+   * inspector.on('screencastframe', ({ data, width, height }) => {
+   *   console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
+   *   require('fs').writeFileSync('frame.jpg', data);
+   * });
+   * await inspector.startScreencast({ size: { width: 1280, height: 720 } });
+   * // ... perform actions ...
+   * await inspector.stopScreencast();
+   * ```
+   *
+   */
+  on(event: 'screencastframe', listener: (data: {
+    /**
+     * JPEG-encoded frame data.
+     */
+    data: Buffer;
+
+    /**
+     * Frame width in pixels.
+     */
+    width: number;
+
+    /**
+     * Frame height in pixels.
+     */
+    height: number;
+  }) => 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;
+
+    /**
+     * Frame width in pixels.
+     */
+    width: number;
+
+    /**
+     * Frame height in pixels.
+     */
+    height: number;
+  }) => any): this;
+
+  /**
+   * Emitted for each captured JPEG screencast frame while the screencast is running.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const inspector = page.inspector();
+   * inspector.on('screencastframe', ({ data, width, height }) => {
+   *   console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
+   *   require('fs').writeFileSync('frame.jpg', data);
+   * });
+   * await inspector.startScreencast({ size: { width: 1280, height: 720 } });
+   * // ... perform actions ...
+   * await inspector.stopScreencast();
+   * ```
+   *
+   */
+  addListener(event: 'screencastframe', listener: (data: {
+    /**
+     * JPEG-encoded frame data.
+     */
+    data: Buffer;
+
+    /**
+     * Frame width in pixels.
+     */
+    width: number;
+
+    /**
+     * Frame height in pixels.
+     */
+    height: number;
+  }) => any): this;
+
+  /**
+   * Removes an event listener added by `on` or `addListener`.
+   */
+  removeListener(event: 'screencastframe', listener: (data: {
+    /**
+     * JPEG-encoded frame data.
+     */
+    data: Buffer;
+
+    /**
+     * Frame width in pixels.
+     */
+    width: number;
+
+    /**
+     * Frame height in pixels.
+     */
+    height: number;
+  }) => any): this;
+
+  /**
+   * Removes an event listener added by `on` or `addListener`.
+   */
+  off(event: 'screencastframe', listener: (data: {
+    /**
+     * JPEG-encoded frame data.
+     */
+    data: Buffer;
+
+    /**
+     * Frame width in pixels.
+     */
+    width: number;
+
+    /**
+     * Frame height in pixels.
+     */
+    height: number;
+  }) => any): this;
+
+  /**
+   * Emitted for each captured JPEG screencast frame while the screencast is running.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const inspector = page.inspector();
+   * inspector.on('screencastframe', ({ data, width, height }) => {
+   *   console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
+   *   require('fs').writeFileSync('frame.jpg', data);
+   * });
+   * await inspector.startScreencast({ size: { width: 1280, height: 720 } });
+   * // ... perform actions ...
+   * await inspector.stopScreencast();
+   * ```
+   *
+   */
+  prependListener(event: 'screencastframe', listener: (data: {
+    /**
+     * JPEG-encoded frame data.
+     */
+    data: Buffer;
+
+    /**
+     * Frame width in pixels.
+     */
+    width: number;
+
+    /**
+     * Frame height in pixels.
+     */
+    height: number;
+  }) => any): this;
+
+  /**
+   * Starts capturing screencast frames. Frames are emitted as
+   * [inspector.on('screencastframe')](https://playwright.dev/docs/api/class-inspector#inspector-event-screencast-frame)
+   * events.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const inspector = page.inspector();
+   * inspector.on('screencastframe', ({ data, width, height }) => {
+   *   console.log(`frame ${width}x${height}, size: ${data.length}`);
+   * });
+   * await inspector.startScreencast({ size: { width: 800, height: 600 } });
+   * // ... perform actions ...
+   * await inspector.stopScreencast();
+   * ```
+   *
+   * @param options
+   */
+  startScreencast(options?: {
+    /**
+     * Optional dimensions for the screencast frames. If not specified, the current page viewport size is used.
+     */
+    size?: {
+      /**
+       * Frame width in pixels.
+       */
+      width: number;
+
+      /**
+       * Frame height in pixels.
+       */
+      height: number;
+    };
+  }): Promise<void>;
+
+  /**
+   * Stops the screencast started with
+   * [inspector.startScreencast([options])](https://playwright.dev/docs/api/class-inspector#inspector-start-screencast).
+   *
+   * **Usage**
+   *
+   * ```js
+   * await inspector.startScreencast();
+   * // ... perform actions ...
+   * await inspector.stopScreencast();
+   * ```
+   *
+   */
+  stopScreencast(): Promise<void>;
+}
+
 /**
  * Keyboard provides an api for managing a virtual keyboard. The high level api is
  * [keyboard.type(text[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-type), which takes raw

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

@@ -28,6 +28,7 @@ export { Electron, ElectronApplication } from './electron';
 export { FrameLocator, Locator } from './locator';
 export { ElementHandle } from './elementHandle';
 export { FileChooser } from './fileChooser';
+export type { Inspector } from './inspector';
 export type { Logger } from './types';
 export { TimeoutError } from './errors';
 export { Frame } from './frame';