chore(api): context.rc

Author: pavelfeldman

.claude/skills/playwright-api/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: playwright-api
+description: Explains how to add playwright API methods.
+---
+
+# API
+
+## Adding and modifying APIs
+- Before performing the implementation, go over the steps to understand and plan the work ahead. It is important to follow the steps in order, as some of them are prerequisites for others.
+- Define (or update) API in `docs/api/class-xxx.md`. For the new methods, params and options use the version from package.json (without -next).
+- Watch will kick in and re-generate types for the API
+- Implement the new API in `packages/playwright/src/client/xxx.ts`
+- Define (or update) channel for the API in `packages/protocol/src/protocol.yml` as needed
+- Watch will kick in and re-generate types for protocol channels
+- Implement dispatcher handler in `packages/playwright/src/server/dispatchers/xxxDispatcher.ts` as needed
+- Handler should just route the call into the corresponding method in `packages/playwright-core/src/server/xxx.ts`
+- Place new tests in `tests/page/xxx.spec.ts` or create new test file if needed
+
+# Build
+- Assume watch is running and everything is up to date.
+
+# Test
+- If your tests are only using page, prefer to place them in `tests/page/xxx.spec.ts` and use page fixture. If you need to use browser context, place them in `tests/library/xxx.spec.ts`.
+- Run npm test as `npm run ctest <file>`
+
+# Lint
+- In the end lint via `npm run flint`.

.claude/skills/playwright-mcp-dev/SKILL.md

@@ -30,6 +30,18 @@ description: Explains how to add and debug playwright MCP tools and CLI commands
   in `packages/playwright/src/skill/references/`
 - Place new tests in `tests/mcp/cli-<category>.spec.ts`
 
+## Adding CLI options or Config options
+When you need to add something to config.
+
+- `packages/playwright/src/mcp/program.ts`
+  - add CLI option and doc
+- `packages/playwright/src/mcp/config.d.ts`
+  - add and document the option
+- `packages/playwright/src/mcp/config.ts`
+  - modify FullConfig if needed
+  - and CLIOptions if needed
+  - add it to configFromEnv
+
 ## Building
 - Assume watch is running at all times, run lint to see type errors
 

docs/src/api/class-browsercontext.md

@@ -1007,6 +1007,12 @@ Allows to wait for async listeners to complete or to ignore subsequent errors fr
 ### option: BrowserContext.removeAllListeners.behavior = %%-remove-all-listeners-options-behavior-%%
 * since: v1.47
 
+## property: BrowserContext.rc
+* since: v1.59
+- type: <[RC]>
+
+Remote control for the browser context. Can be used to stream live screencast of all pages in the context with a tabbed UI.
+
 ## property: BrowserContext.request
 * since: v1.16
 * langs:

docs/src/api/class-rc.md

@@ -0,0 +1,47 @@
+# class: RC
+* since: v1.59
+
+Remote control allows streaming live screencast of the browser context over WebSocket.
+It shows a tabbed browser-like UI with all context pages.
+
+## async method: RC.startHttp
+* since: v1.59
+- returns: <[Object]>
+  - `url` <[string]> URL of the screencast server.
+
+Starts an HTTP server that streams live screencast frames over WebSocket. Returns an object with the server URL.
+Open the URL in a browser to see the live screencast with a tabbed UI showing all pages in the context.
+
+**Usage**
+
+```js
+const { url } = await context.rc.startHttp();
+console.log('Open to view screencast:', url);
+// ... perform actions ...
+await context.rc.stopHttp();
+```
+
+### option: RC.startHttp.size
+* since: v1.59
+- `size` ?<[Object]>
+  - `width` <[int]> Video frame width.
+  - `height` <[int]> Video frame height.
+
+Optional dimensions of the screencast frames. If not specified the size will be scaled down to fit into 800x800.
+
+### option: RC.startHttp.port
+* since: v1.59
+- `port` ?<[int]>
+
+Port to bind the HTTP server to. If not specified, a random available port will be used.
+
+### option: RC.startHttp.host
+* since: v1.59
+- `host` ?<[string]>
+
+Host to bind the HTTP server to. Default is localhost.
+
+## async method: RC.stopHttp
+* since: v1.59
+
+Stops the screencast server started with [`method: RC.startHttp`].

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

@@ -9911,6 +9911,12 @@ export interface BrowserContext {
    */
   clock: Clock;
 
+  /**
+   * Remote control for the browser context. Can be used to stream live screencast of all pages in the context with a
+   * tabbed UI.
+   */
+  rc: RC;
+
   /**
    * API testing helper associated with this context. Requests made with this API will use context cookies.
    */
@@ -20748,6 +20754,65 @@ export const selectors: Selectors;
  */
 export const webkit: BrowserType;
 
+/**
+ * Remote control allows streaming live screencast of the browser context over WebSocket. It shows a tabbed
+ * browser-like UI with all context pages.
+ */
+export interface RC {
+  /**
+   * Starts an HTTP server that streams live screencast frames over WebSocket. Returns an object with the server URL.
+   * Open the URL in a browser to see the live screencast with a tabbed UI showing all pages in the context.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const { url } = await context.rc.startHttp();
+   * console.log('Open to view screencast:', url);
+   * // ... perform actions ...
+   * await context.rc.stopHttp();
+   * ```
+   *
+   * @param options
+   */
+  startHttp(options?: {
+    /**
+     * Host to bind the HTTP server to. Default is localhost.
+     */
+    host?: string;
+
+    /**
+     * Port to bind the HTTP server to. If not specified, a random available port will be used.
+     */
+    port?: number;
+
+    /**
+     * Optional dimensions of the screencast frames. If not specified the size will be scaled down to fit into 800x800.
+     */
+    size?: {
+      /**
+       * Video frame width.
+       */
+      width: number;
+
+      /**
+       * Video frame height.
+       */
+      height: number;
+    };
+  }): Promise<{
+    /**
+     * URL of the screencast server.
+     */
+    url: string;
+  }>;
+
+  /**
+   * Stops the screencast server started with
+   * [rC.startHttp([options])](https://playwright.dev/docs/api/class-rc#rc-start-http).
+   */
+  stopHttp(): Promise<void>;
+}
+
 /**
  * Whenever the page sends a request for a network resource the following sequence of events are emitted by
  * [Page](https://playwright.dev/docs/api/class-page):

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

@@ -37,6 +37,7 @@ export { Request, Response, Route, WebSocket, WebSocketRoute } from './network';
 export { APIRequest, APIRequestContext, APIResponse } from './fetch';
 export { Page } from './page';
 export { PageAgent } from './pageAgent';
+export { RC } from './rc';
 export { Selectors } from './selectors';
 export { Tracing } from './tracing';
 export { Video } from './video';

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

@@ -30,6 +30,7 @@ import { Frame } from './frame';
 import { HarRouter } from './harRouter';
 import * as network from './network';
 import { BindingCall, Page } from './page';
+import { RC } from './rc';
 import { Tracing } from './tracing';
 import { Waiter } from './waiter';
 import { WebError } from './webError';
@@ -68,6 +69,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
   private _closedPromise: Promise<void>;
   readonly _options: channels.BrowserNewContextParams;
 
+  readonly rc: RC;
   readonly request: APIRequestContext;
   readonly tracing: Tracing;
   readonly clock: Clock;
@@ -93,6 +95,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
     super(parent, type, guid, initializer);
     this._options = initializer.options;
     this._timeoutSettings = new TimeoutSettings(this._platform);
+    this.rc = new RC(this._channel);
     this.tracing = Tracing.from(initializer.tracing);
     this.request = APIRequestContext.from(initializer.requestContext);
     this.request._timeoutSettings = this._timeoutSettings;

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

@@ -0,0 +1,34 @@
+/**
+ * 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 type * as api from '../../types/types';
+import type * as channels from '@protocol/channels';
+
+export class RC implements api.RC {
+  private _channel: channels.BrowserContextChannel;
+
+  constructor(channel: channels.BrowserContextChannel) {
+    this._channel = channel;
+  }
+
+  async startHttp(options: { size?: { width: number, height: number }, port?: number, host?: string } = {}): Promise<{ url: string }> {
+    return await this._channel.rcStartHttp(options);
+  }
+
+  async stopHttp(): Promise<void> {
+    await this._channel.rcStopHttp();
+  }
+}

packages/playwright-core/src/protocol/validator.ts

@@ -1157,6 +1157,19 @@ scheme.BrowserContextClockSetSystemTimeParams = tObject({
   timeString: tOptional(tString),
 });
 scheme.BrowserContextClockSetSystemTimeResult = tOptional(tObject({}));
+scheme.BrowserContextRcStartHttpParams = tObject({
+  size: tOptional(tObject({
+    width: tInt,
+    height: tInt,
+  })),
+  port: tOptional(tInt),
+  host: tOptional(tString),
+});
+scheme.BrowserContextRcStartHttpResult = tObject({
+  url: tString,
+});
+scheme.BrowserContextRcStopHttpParams = tOptional(tObject({}));
+scheme.BrowserContextRcStopHttpResult = tOptional(tObject({}));
 scheme.PageInitializer = tObject({
   mainFrame: tChannel(['Frame']),
   viewportSize: tOptional(tObject({

packages/playwright-core/src/server/browserContext.ts

@@ -37,6 +37,8 @@ import { Selectors } from './selectors';
 import { Tracing } from './trace/recorder/tracing';
 import * as rawStorageSource from '../generated/storageScriptSource';
 
+import { RemoteControl } from './remoteControl';
+
 import type { Artifact } from './artifact';
 import type { Browser, BrowserOptions } from './browser';
 import type { ConsoleMessage } from './console';
@@ -64,6 +66,8 @@ const BrowserContextEvent = {
   RequestContinued: 'requestcontinued',
   BeforeClose: 'beforeclose',
   RecorderEvent: 'recorderevent',
+  PageClosed: 'pageclosed',
+  InternalFrameNavigatedToNewDocument: 'internalframenavigatedtonewdocument',
 } as const;
 
 export type BrowserContextEventMap = {
@@ -80,6 +84,8 @@ export type BrowserContextEventMap = {
   [BrowserContextEvent.RequestContinued]: [request: network.Request];
   [BrowserContextEvent.BeforeClose]: [];
   [BrowserContextEvent.RecorderEvent]: [event: { event: 'actionAdded' | 'actionUpdated' | 'signalAdded', data: any, page: Page, code: string }];
+  [BrowserContextEvent.PageClosed]: [page: Page];
+  [BrowserContextEvent.InternalFrameNavigatedToNewDocument]: [frame: frames.Frame, page: Page];
 };
 
 export abstract class BrowserContext<EM extends EventMap = EventMap> extends SdkObject<BrowserContextEventMap | EM> {
@@ -114,6 +120,7 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk
   private _playwrightBindingExposed?: Promise<void>;
   readonly dialogManager: DialogManager;
   private _consoleApiExposed = false;
+  private _remoteControl: RemoteControl | null = null;
 
   constructor(browser: Browser, options: types.BrowserContextOptions, browserContextId: string | undefined) {
     super(browser, 'browser-context');
@@ -509,6 +516,23 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk
     await this.doUpdateRequestInterception();
   }
 
+  async startRemoteControl(options: { size?: types.Size, port?: number, host?: string } = {}): Promise<string> {
+    if (this._remoteControl)
+      throw new Error('Remote control is already running');
+    const size = validateVideoSize(options.size, undefined);
+    this._remoteControl = new RemoteControl(this);
+    const url = await this._remoteControl.start({ width: size.width, height: size.height, quality: 90, port: options.port, host: options.host });
+    return url;
+  }
+
+  async stopRemoteControl(): Promise<void> {
+    if (!this._remoteControl)
+      throw new Error('Remote control is not running');
+    const remoteControl = this._remoteControl;
+    this._remoteControl = null;
+    await remoteControl.stop();
+  }
+
   isClosingOrClosed() {
     return this._closedStatus !== 'open';
   }
@@ -532,6 +556,11 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk
       this.emit(BrowserContext.Events.BeforeClose);
       this._closedStatus = 'closing';
 
+      if (this._remoteControl) {
+        await this._remoteControl.stop();
+        this._remoteControl = null;
+      }
+
       for (const harRecorder of this._harRecorders.values())
         await harRecorder.flush();
       await this.tracing.flush();