chore: devtools experiment

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
 

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

@@ -585,6 +585,14 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
       return;
     throw new Error(`File access denied: ${filePath} is outside allowed roots. Allowed roots: ${this._allowedDirectories.length ? this._allowedDirectories.join(', ') : 'none'}`);
   }
+
+  async _devtoolsStart(options: { size?: { width: number, height: number }, port?: number, host?: string } = {}): Promise<{ url: string }> {
+    return await this._channel.devtoolsStart(options);
+  }
+
+  async _devtoolsStop(): Promise<void> {
+    await this._channel.devtoolsStop();
+  }
 }
 
 async function prepareStorageState(platform: Platform, storageState: string | SetStorageState): Promise<NonNullable<channels.BrowserNewContextParams['storageState']>> {

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

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

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

@@ -35,6 +35,7 @@ import { Page, PageBinding } from './page';
 import { RecorderApp } from './recorder/recorderApp';
 import { Selectors } from './selectors';
 import { Tracing } from './trace/recorder/tracing';
+import { DevToolsController } from './devtoolsController';
 import * as rawStorageSource from '../generated/storageScriptSource';
 
 import type { Artifact } from './artifact';
@@ -64,6 +65,8 @@ const BrowserContextEvent = {
   RequestContinued: 'requestcontinued',
   BeforeClose: 'beforeclose',
   RecorderEvent: 'recorderevent',
+  PageClosed: 'pageclosed',
+  InternalFrameNavigatedToNewDocument: 'internalframenavigatedtonewdocument',
 } as const;
 
 export type BrowserContextEventMap = {
@@ -80,6 +83,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 +119,7 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk
   private _playwrightBindingExposed?: Promise<void>;
   readonly dialogManager: DialogManager;
   private _consoleApiExposed = false;
+  private _devtools: DevToolsController | undefined;
 
   constructor(browser: Browser, options: types.BrowserContextOptions, browserContextId: string | undefined) {
     super(browser, 'browser-context');
@@ -509,6 +515,22 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk
     await this.doUpdateRequestInterception();
   }
 
+  async devtoolsStart(options: { size?: types.Size, port?: number, host?: string } = {}): Promise<string> {
+    if (this._devtools)
+      throw new Error('DevTools is already running');
+    const size = validateVideoSize(options.size, undefined);
+    this._devtools = new DevToolsController(this);
+    const url = await this._devtools.start({ width: size.width, height: size.height, quality: 90, port: options.port, host: options.host });
+    return url;
+  }
+
+  async devtoolsStop(): Promise<void> {
+    if (!this._devtools)
+      throw new Error('DevTools is not running');
+    await this._devtools.stop();
+    this._devtools = undefined;
+  }
+
   isClosingOrClosed() {
     return this._closedStatus !== 'open';
   }
@@ -532,6 +554,9 @@ export abstract class BrowserContext<EM extends EventMap = EventMap> extends Sdk
       this.emit(BrowserContext.Events.BeforeClose);
       this._closedStatus = 'closing';
 
+      await this._devtools?.stop();
+      this._devtools = undefined;
+
       for (const harRecorder of this._harRecorders.values())
         await harRecorder.flush();
       await this.tracing.flush();