Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

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

Yury Semikhatsky9335d41abac6
diff --git a/docs/src/api/class-inspector.md b/docs/src/api/class-inspector.md
new file mode 100644
index 0000000000..07a4f39503
--- /dev/null
+++ b/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();
+```
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index fa226172ac..4618253e18 100644
--- a/docs/src/api/class-page.md
+++ b/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).
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 979a929dd6..5cfbb21320 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/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
diff --git a/packages/playwright-core/src/client/api.ts b/packages/playwright-core/src/client/api.ts
index e4b0abb923..db6d504267 100644
--- a/packages/playwright-core/src/client/api.ts
+++ b/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';
diff --git a/packages/playwright-core/src/client/inspector.ts b/packages/playwright-core/src/client/inspector.ts
new file mode 100644
index 0000000000..98b81c347c
--- /dev/null
+++ b/packages/playwright-core/src/client/inspector.ts
@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { EventEmitter } from './eventEmitter';
+
+import type * as api from '../../types/types';
+import type { Page } from './page';
+
+export class Inspector extends EventEmitter implements api.Inspector {
+ private readonly _page: Page;
+
+ constructor(page: Page) {
+ super(page._platform);
+ this._page = page;
+ this._page._channel.on('screencastFrame', ({ data, width, height }) => this.emit('screencastframe', { data, width, height }));
+ }
+
+ async startScreencast(options: { size?: { width: number, height: number } } = {}): Promise<void> {
+ await this._page._channel.startScreencast(options);
+ }
+
+ async stopScreencast(): Promise<void> {
+ await this._page._channel.stopScreencast();
+ }
+}
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index 42f14dec3b..d1eaca443e 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -30,6 +30,7 @@ import { Keyboard, Mouse, Touchscreen } from './input';
import { JSHandle, assertMaxArguments, parseResult, serializeArgument } from './jsHandle';
import { Request, Response, Route, RouteHandler, WebSocket, WebSocketRoute, WebSocketRouteHandler, validateHeaders } from './network';
import { Video } from './video';
+import { Inspector } from './inspector';
import { Waiter } from './waiter';
import { Worker } from './worker';
import { TimeoutSettings } from './timeoutSettings';
@@ -100,6 +101,7 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
readonly _bindings = new Map<string, (source: structs.BindingSource, ...args: any[]) => any>();
readonly _timeoutSettings: TimeoutSettings;
private _video: Video;
+ private _inspector: Inspector;
readonly _opener: Page | null;
private _closeReason: string | undefined;
_closeWasCalled: boolean = false;
@@ -134,6 +136,7 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
this._closed = initializer.isClosed;
this._opener = Page.fromNullable(initializer.opener);
this._video = new Video(this, this._connection, initializer.video ? Artifact.from(initializer.video) : undefined);
+ this._inspector = new Inspector(this);
this._channel.on('bindingCall', ({ binding }) => this._onBinding(BindingCall.from(binding)));
this._channel.on('close', () => this._onClose());
@@ -283,6 +286,10 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
return this._video;
}
+ inspector(): Inspector {
+ return this._inspector;
+ }
+
async $(selector: string, options?: { strict?: boolean }): Promise<ElementHandle<SVGElement | HTMLElement> | null> {
return await this._mainFrame.$(selector, options);
}
diff --git a/packages/playwright-core/src/client/video.ts b/packages/playwright-core/src/client/video.ts
index 2c0d700508..47e594ae53 100644
--- a/packages/playwright-core/src/client/video.ts
+++ b/packages/playwright-core/src/client/video.ts
@@ -15,17 +15,19 @@
*/
import { Artifact } from './artifact';
+import { EventEmitter } from './eventEmitter';
import type { Connection } from './connection';
import type { Page } from './page';
import type * as api from '../../types/types';
-export class Video implements api.Video {
+export class Video extends EventEmitter implements api.Video {
private _artifact: Artifact | undefined;
private _isRemote = false;
private _page: Page;
constructor(page: Page, connection: Connection, artifact: Artifact | undefined) {
+ super(page._platform);
this._page = page;
this._isRemote = connection.isRemote();
this._artifact = artifact;
diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts
index d554ad8983..fc1fea1a46 100644
--- a/packages/playwright-core/src/protocol/validator.ts
+++ b/packages/playwright-core/src/protocol/validator.ts
@@ -1225,6 +1225,11 @@ scheme.PageLocatorHandlerTriggeredEvent = tObject({
scheme.PageRouteEvent = tObject({
route: tChannel(['Route']),
});
+scheme.PageScreencastFrameEvent = tObject({
+ data: tBinary,
+ width: tInt,
+ height: tInt,
+});
scheme.PageWebSocketRouteEvent = tObject({
webSocketRoute: tChannel(['WebSocketRoute']),
});
@@ -1536,6 +1541,15 @@ scheme.PagePickLocatorResult = tObject({
});
scheme.PageCancelPickLocatorParams = tOptional(tObject({}));
scheme.PageCancelPickLocatorResult = tOptional(tObject({}));
+scheme.PageStartScreencastParams = tObject({
+ size: tOptional(tObject({
+ width: tInt,
+ height: tInt,
+ })),
+});
+scheme.PageStartScreencastResult = tOptional(tObject({}));
+scheme.PageStopScreencastParams = tOptional(tObject({}));
+scheme.PageStopScreencastResult = tOptional(tObject({}));
scheme.PageVideoStartParams = tObject({
size: tOptional(tObject({
width: tInt,
diff --git a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
index 96875090ee..ccfde8ec5a 100644
--- a/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
+++ b/packages/playwright-core/src/server/dispatchers/pageDispatcher.ts
@@ -17,6 +17,7 @@
import { Page, Worker } from '../page';
import { Dispatcher } from './dispatcher';
import { parseError, serializeError } from '../errors';
+import { validateVideoSize } from '../browserContext';
import { ArtifactDispatcher } from './artifactDispatcher';
import { ElementHandleDispatcher } from './elementHandlerDispatcher';
import { FrameDispatcher } from './frameDispatcher';
@@ -43,6 +44,7 @@ import type { InitScript, PageBinding } from '../page';
import type * as channels from '@protocol/channels';
import type { Progress } from '@protocol/progress';
import type { URLMatch } from '../../utils/isomorphic/urlMatch';
+import type { ScreencastFrame } from '../types';
export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, BrowserContextDispatcher> implements channels.PageChannel {
_type_EventTarget = true;
@@ -82,7 +84,7 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
viewportSize: page.emulatedSize()?.viewport,
isClosed: page.isClosed(),
opener: PageDispatcher.fromNullable(parentScope, page.opener()),
- video: page.video ? createVideoDispatcher(parentScope, page.video) : undefined,
+ video: page.video ? createVideoDispatcher(parentScope, page.video) : undefined
});
this.adopt(mainFrame);
@@ -106,6 +108,7 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
// Artifact can outlive the page, so bind to the context scope.
this._dispatchEvent('download', { url: download.url, suggestedFilename: download.suggestedFilename(), artifact: ArtifactDispatcher.from(parentScope, download.artifact) });
});
+ this.addObjectListener(Page.Events.ScreencastFrame, (frame: ScreencastFrame) => this._dispatchEvent('screencastFrame', { data: frame.buffer, width: frame.width, height: frame.height }));
this.addObjectListener(Page.Events.EmulatedSizeChanged, () => this._dispatchEvent('viewportSizeChanged', { viewportSize: page.emulatedSize()?.viewport }));
this.addObjectListener(Page.Events.FileChooser, (fileChooser: FileChooser) => this._dispatchEvent('fileChooser', {
element: ElementHandleDispatcher.from(mainFrame, fileChooser.element()),
@@ -356,6 +359,15 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
await recorder?.setMode('none');
}
+ async startScreencast(params: channels.PageStartScreencastParams, progress?: Progress): Promise<channels.PageStartScreencastResult> {
+ const size = validateVideoSize(params.size, this._page.emulatedSize()?.viewport);
+ await this._page.screencast.startScreencast(this, { quality: 90, width: size.width, height: size.height });
+ }
+
+ async stopScreencast(params: channels.PageStopScreencastParams, progress?: Progress): Promise<channels.PageStopScreencastResult> {
+ return this._page.screencast.stopScreencast(this);
+ }
+
async videoStart(params: channels.PageVideoStartParams, progress: Progress): Promise<channels.PageVideoStartResult> {
const artifact = await this._page.screencast.startExplicitVideoRecording(params);
return { artifact: createVideoDispatcher(this.parentScope(), artifact) };
diff --git a/packages/playwright-core/src/server/screencast.ts b/packages/playwright-core/src/server/screencast.ts
index 38de70b9e9..42c6f44640 100644
--- a/packages/playwright-core/src/server/screencast.ts
+++ b/packages/playwright-core/src/server/screencast.ts
@@ -29,6 +29,7 @@ export class Screencast {
private _videoRecorder: VideoRecorder | null = null;
private _videoId: string | null = null;
private _screencastClients = new Set<unknown>();
+ private _screencastOptions: { width: number, height: number, quality: number } | null = null;
// Aiming at 25 fps by default - each frame is 40ms, but we give some slack with 35ms.
// When throttling for tracing, 200ms between frames, except for 10 frames around the action.
@@ -140,8 +141,13 @@ export class Screencast {
}
async startScreencast(client: unknown, options: { width: number, height: number, quality: number }) {
+ if (this._screencastOptions) {
+ if (options.width !== this._screencastOptions.width || options.height !== this._screencastOptions.height || options.quality !== this._screencastOptions.quality)
+ throw new Error(`Screencast is already running with different options (${this._screencastOptions.width}x${this._screencastOptions.height} quality=${this._screencastOptions.quality})`);
+ }
this._screencastClients.add(client);
if (this._screencastClients.size === 1) {
+ this._screencastOptions = options;
await this._page.delegate.startScreencast({
width: options.width,
height: options.height,
@@ -152,8 +158,10 @@ export class Screencast {
async stopScreencast(client: unknown) {
this._screencastClients.delete(client);
- if (!this._screencastClients.size)
+ if (!this._screencastClients.size) {
+ this._screencastOptions = null;
await this._page.delegate.stopScreencast();
+ }
}
}
diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
index 2cdbb3dec7..8b5f29d09b 100644
--- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
+++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts
@@ -148,6 +148,8 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri
['Page.bringToFront', { title: 'Bring to front', }],
['Page.pickLocator', { title: 'Pick locator', group: 'configuration', }],
['Page.cancelPickLocator', { title: 'Cancel pick locator', group: 'configuration', }],
+ ['Page.startScreencast', { title: 'Start screencast', group: 'configuration', }],
+ ['Page.stopScreencast', { title: 'Stop screencast', group: 'configuration', }],
['Page.videoStart', { title: 'Start video recording', group: 'configuration', }],
['Page.videoStop', { title: 'Stop video recording', group: 'configuration', }],
['Page.updateSubscription', { internal: true, }],
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 979a929dd6..5cfbb21320 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/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
diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts
index f7206cdc00..8f9ca58401 100644
--- a/packages/protocol/src/channels.d.ts
+++ b/packages/protocol/src/channels.d.ts
@@ -2100,6 +2100,7 @@ export interface PageEventTarget {
on(event: 'frameDetached', callback: (params: PageFrameDetachedEvent) => void): this;
on(event: 'locatorHandlerTriggered', callback: (params: PageLocatorHandlerTriggeredEvent) => void): this;
on(event: 'route', callback: (params: PageRouteEvent) => void): this;
+ on(event: 'screencastFrame', callback: (params: PageScreencastFrameEvent) => void): this;
on(event: 'webSocketRoute', callback: (params: PageWebSocketRouteEvent) => void): this;
on(event: 'webSocket', callback: (params: PageWebSocketEvent) => void): this;
on(event: 'worker', callback: (params: PageWorkerEvent) => void): this;
@@ -2148,6 +2149,8 @@ export interface PageChannel extends PageEventTarget, EventTargetChannel {
bringToFront(params?: PageBringToFrontParams, progress?: Progress): Promise<PageBringToFrontResult>;
pickLocator(params?: PagePickLocatorParams, progress?: Progress): Promise<PagePickLocatorResult>;
cancelPickLocator(params?: PageCancelPickLocatorParams, progress?: Progress): Promise<PageCancelPickLocatorResult>;
+ startScreencast(params: PageStartScreencastParams, progress?: Progress): Promise<PageStartScreencastResult>;
+ stopScreencast(params?: PageStopScreencastParams, progress?: Progress): Promise<PageStopScreencastResult>;
videoStart(params: PageVideoStartParams, progress?: Progress): Promise<PageVideoStartResult>;
videoStop(params?: PageVideoStopParams, progress?: Progress): Promise<PageVideoStopResult>;
updateSubscription(params: PageUpdateSubscriptionParams, progress?: Progress): Promise<PageUpdateSubscriptionResult>;
@@ -2186,6 +2189,11 @@ export type PageLocatorHandlerTriggeredEvent = {
export type PageRouteEvent = {
route: RouteChannel,
};
+export type PageScreencastFrameEvent = {
+ data: Binary,
+ width: number,
+ height: number,
+};
export type PageWebSocketRouteEvent = {
webSocketRoute: WebSocketRouteChannel,
};
@@ -2662,6 +2670,22 @@ export type PagePickLocatorResult = {
export type PageCancelPickLocatorParams = {};
export type PageCancelPickLocatorOptions = {};
export type PageCancelPickLocatorResult = void;
+export type PageStartScreencastParams = {
+ size?: {
+ width: number,
+ height: number,
+ },
+};
+export type PageStartScreencastOptions = {
+ size?: {
+ width: number,
+ height: number,
+ },
+};
+export type PageStartScreencastResult = void;
+export type PageStopScreencastParams = {};
+export type PageStopScreencastOptions = {};
+export type PageStopScreencastResult = void;
export type PageVideoStartParams = {
size?: {
width: number,
@@ -2742,6 +2766,7 @@ export interface PageEvents {
'frameDetached': PageFrameDetachedEvent;
'locatorHandlerTriggered': PageLocatorHandlerTriggeredEvent;
'route': PageRouteEvent;
+ 'screencastFrame': PageScreencastFrameEvent;
'webSocketRoute': PageWebSocketRouteEvent;
'webSocket': PageWebSocketEvent;
'worker': PageWorkerEvent;
diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml
index 1e27b0edbd..5add91162a 100644
--- a/packages/protocol/src/protocol.yml
+++ b/packages/protocol/src/protocol.yml
@@ -2074,6 +2074,20 @@ Page:
title: Cancel pick locator
group: configuration
+ startScreencast:
+ title: Start screencast
+ group: configuration
+ parameters:
+ size:
+ type: object?
+ properties:
+ width: int
+ height: int
+
+ stopScreencast:
+ title: Stop screencast
+ group: configuration
+
videoStart:
title: Start video recording
group: configuration
@@ -2177,6 +2191,12 @@ Page:
parameters:
route: Route
+ screencastFrame:
+ parameters:
+ data: binary
+ width: int
+ height: int
+
webSocketRoute:
parameters:
webSocketRoute: WebSocketRoute
diff --git a/tests/library/video.spec.ts b/tests/library/video.spec.ts
index 89154044bf..1a153ab89e 100644
--- a/tests/library/video.spec.ts
+++ b/tests/library/video.spec.ts
@@ -897,6 +897,69 @@ it.describe('screencast', () => {
await context.close();
expectFrames(videoPath, size, isAlmostWhite);
});
+
+ it('inspector.startScreencast emits screencastframe events', async ({ browser, server }) => {
+ const size = { width: 500, height: 400 };
+ const context = await browser.newContext({ viewport: size });
+ const page = await context.newPage();
+
+ const frames: { data: Buffer, width: number, height: number }[] = [];
+ page.inspector().on('screencastframe', frame => frames.push(frame));
+
+ await page.inspector().startScreencast({ size });
+ await page.goto(server.EMPTY_PAGE);
+ await page.evaluate(() => document.body.style.backgroundColor = 'red');
+ await rafraf(page, 100);
+ await page.inspector().stopScreencast();
+
+ expect(frames.length).toBeGreaterThan(0);
+ for (const frame of frames) {
+ // Each frame must be a valid JPEG (starts with FF D8)
+ expect(frame.data[0]).toBe(0xff);
+ expect(frame.data[1]).toBe(0xd8);
+ expect(frame.width).toBe(size.width);
+ expect(frame.height).toBe(size.height);
+ }
+
+ await context.close();
+ });
+
+ it('startScreencast throws when called with different options while running', async ({ browser }) => {
+ const size = { width: 500, height: 400 };
+ const context = await browser.newContext({ viewport: size });
+ const page = await context.newPage();
+
+ await page.inspector().startScreencast({ size });
+ await expect(page.inspector().startScreencast({ size: { width: 320, height: 240 } })).rejects.toThrow('Screencast is already running with different options');
+
+ await page.inspector().stopScreencast();
+ await context.close();
+ });
+
+ it('startScreencast allows restart with different options after stop', async ({ browser }) => {
+ const context = await browser.newContext({ viewport: { width: 500, height: 400 } });
+ const page = await context.newPage();
+
+ await page.inspector().startScreencast({ size: { width: 500, height: 400 } });
+ await page.inspector().stopScreencast();
+ // Different options should succeed once the previous screencast is stopped.
+ await expect(page.inspector().startScreencast({ size: { width: 320, height: 240 } })).resolves.toBeUndefined();
+
+ await page.inspector().stopScreencast();
+ await context.close();
+ });
+
+ it('startScreencast throws when video recording is running with different params', async ({ browser }) => {
+ const videoSize = { width: 500, height: 400 };
+ const context = await browser.newContext({ viewport: videoSize });
+ const page = await context.newPage();
+
+ await page.video().start({ size: videoSize });
+ await expect(page.inspector().startScreencast({ size: { width: 320, height: 240 } })).rejects.toThrow('Screencast is already running with different options');
+
+ await page.video().stop();
+ await context.close();
+ });
});
it('should saveAs video', async ({ browser }, testInfo) => {