Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
chore: add library skills (#39422)
Pavel Feldman6ac5269669ca
diff --git a/.claude/skills/playwright-dev/SKILL.md b/.claude/skills/playwright-dev/SKILL.mdindex cd21e9dcf4..25cf694ca1 100644--- a/.claude/skills/playwright-dev/SKILL.md+++ b/.claude/skills/playwright-dev/SKILL.md@@ -7,6 +7,7 @@ description: Explains how to develop Playwright - add APIs, MCP tools, CLI comma## Table of Contents+- [Library Architecture](library.md) — client/server/dispatcher structure, protocol layer, DEPS rules- [Adding and Modifying APIs](api.md) — define API docs, implement client/server, add tests- [MCP Tools and CLI Commands](mcp-dev.md) — add MCP tools, CLI commands, config options- [Vendoring Dependencies](vendor.md) — bundle third-party npm packages into playwright-core or playwrightdiff --git a/.claude/skills/playwright-dev/library.md b/.claude/skills/playwright-dev/library.mdnew file mode 100644index 0000000000..bc4aa63fb8--- /dev/null+++ b/.claude/skills/playwright-dev/library.md@@ -0,0 +1,334 @@+# Playwright Library Architecture: Client, Server, and Dispatchers++Playwright uses a client-server architecture connected by a protocol layer. The client provides the public API, the server performs actual browser automation, and dispatchers bridge the two over an RPC channel.++## Package Layout++```+packages/protocol/src/+ protocol.yml — RPC protocol definition (source of truth)+ channels.d.ts — generated TypeScript channel interfaces+ callMetadata.d.ts — call metadata types++packages/playwright-core/src/+ client/ — public API objects (ChannelOwner subclasses)+ server/ — browser automation implementation (SdkObject subclasses)+ server/dispatchers/ — protocol bridge (Dispatcher subclasses)+ protocol/ — validators (generated + primitives)+ utils/isomorphic/ — shared code used by both client and server+ protocolMetainfo.ts — generated method metadata (flags, titles)+```++## Dependency Rules (DEPS.list)++Each directory has a `DEPS.list` constraining its imports. These are enforced by `npm run flint`.++**client/** can import from:+- `../protocol/` — validators and channel types+- `../utils/isomorphic` — shared utilities++**server/** can import from:+- `../protocol/`, `../utils/`, `../utils/isomorphic/`, `../utilsBundle.ts`+- `./` (own directory), `./codegen/`, `./isomorphic/`, `./har/`, `./recorder/`, `./registry/`, `./utils/`+- Only `playwright.ts` can import browser engines (`./chromium/`, `./firefox/`, `./webkit/`, `./bidi/`, `./android/`, `./electron/`)+- Only `devtoolsController.ts` can additionally import `./chromium/`++**server/dispatchers/** can import from:+- `../../protocol/`, `../../utils/`, `../../utils/isomorphic/`+- `../**` — all server modules++**Key rule:** Client code NEVER imports server code. Server code NEVER imports client code. They communicate only through the protocol.++## Protocol Layer++### protocol.yml++Defines all RPC interfaces, commands (methods), events, and types. Example:++```yaml+Page:+ type: interface+ extends: EventTarget+ initializer:+ mainFrame: Frame+ viewportSize: { type: object?, properties: { width: int, height: int } }+ commands:+ goto:+ parameters:+ url: string+ timeout: float+ waitUntil: LifecycleEvent?+ returns:+ response: Response?+ events:+ close: {}+ navigated:+ url: string+ name: string+```++### Code Generation++Running `node utils/generate_channels.js` (or via watch) produces:+- `packages/protocol/src/channels.d.ts` — TypeScript types: `PageChannel`, `PageGotoParams`, `PageGotoResult`, `PageInitializer`, event types+- `packages/playwright-core/src/protocol/validator.ts` — runtime validators: `scheme.PageGotoParams = tObject({...})`+- `packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts` — method flags (slowMo, snapshot, etc.)++### Wire Format++```+Client → Server (RPC call): { id, guid, method, params, metadata? }+Server → Client (response): { id, result } or { id, error, log? }+Server → Client (event): { guid, method, params }+Server → Client (lifecycle): { guid, method: '__create__'|'__adopt__'|'__dispose__', params }+```++Object references are serialized as `{ guid: "object-guid" }` and resolved by validators.++## Client Layer++### ChannelOwner — Base Class++Every client-side API object (Page, Frame, Browser, etc.) extends `ChannelOwner<T>`:++```+packages/playwright-core/src/client/channelOwner.ts+```++Key properties:+- `_connection: Connection` — the RPC connection+- `_channel: T` — Proxy that intercepts method calls and sends RPC messages+- `_guid: string` — unique identifier matching the server-side object+- `_type: string` — type name (e.g., 'Page', 'Frame')+- `_parent: ChannelOwner` — parent in the object tree+- `_objects: Map<string, ChannelOwner>` — child objects+- `_initializer` — initial state received from server on creation++How `_channel` works: It's a Proxy. When you call `this._channel.goto(params)`:+1. Proxy intercepts the `goto` property access+2. Finds the validator for `PageGotoParams`+3. Returns an async function that validates params, wraps in `_wrapApiCall`, and calls `_connection.sendMessageToServer()`++Event subscription optimization: `_eventToSubscriptionMapping` maps JS event names to protocol subscription events. When the first listener is added, calls `updateSubscription(event, true)` on the channel. When last listener is removed, calls `updateSubscription(event, false)`. This way the server only sends events that have listeners.++### Connection++```+packages/playwright-core/src/client/connection.ts+```++Manages the client-server transport:+- `_objects: Map<string, ChannelOwner>` — all live remote objects by GUID+- `_callbacks: Map<number, {resolve, reject}>` — pending RPC calls by message ID+- `sendMessageToServer(object, method, params, apiZone)` — sends RPC call, returns promise+- `dispatch(message)` — handles incoming messages:+ - Response (has `id`): resolves/rejects the matching callback+ - `__create__`: instantiates ChannelOwner subclass via factory switch+ - `__adopt__`: reparents a child object+ - `__dispose__`: disposes object and all children+ - Event (has `method`): emits on the object's `_channel`++### Representative Client Classes++| Class | File | Key delegation |+|-------|------|----------------|+| `Playwright` | `playwright.ts` | Root object; owns `chromium`, `firefox`, `webkit` BrowserTypes |+| `BrowserType` | `browserType.ts` | `launch()` → `_channel.launch()` |+| `Browser` | `browser.ts` | `newContext()` → `_channel.newContext()` |+| `BrowserContext` | `browserContext.ts` | Owns pages, routes, tracing, cookies |+| `Page` | `page.ts` | Delegates most calls to `_mainFrame`; owns keyboard/mouse/touchscreen |+| `Frame` | `frame.ts` | `goto()`, `click()`, `evaluate()` → `_channel.*` |+| `Locator` | `locator.ts` | Delegates to `Frame` methods with selector + `strict: true` |+| `ElementHandle` | `elementHandle.ts` | DOM element reference |++### Public API Exports++`packages/playwright-core/src/client/api.ts` exports all public classes.++## Server Layer++### SdkObject — Base Class++Every server-side domain object extends `SdkObject`:++```+packages/playwright-core/src/server/instrumentation.ts+```++Key properties:+- `guid: string` — unique identifier (shared with client-side ChannelOwner)+- `attribution: Attribution` — ownership chain: `{ playwright, browserType?, browser?, context?, page?, frame? }`+- `instrumentation: Instrumentation` — hooks for tracing, debugging, test runner integration++Attribution is inherited from parent on construction. Instrumentation hooks include:+`onBeforeCall`, `onAfterCall`, `onBeforeInputAction`, `onCallLog`, `onPageOpen/Close`, `onBrowserOpen/Close`, `onDialog`, `onDownload`.++### Key Server Classes++| Class | File | Purpose |+|-------|------|---------|+| `Playwright` | `playwright.ts` | Root entry point; creates BrowserTypes |+| `BrowserType` | `browserType.ts` | Launches browser processes |+| `Browser` | `browser.ts` | Abstract base; owns BrowserContexts |+| `BrowserContext` | `browserContext.ts` | Isolation boundary; owns pages, cookies, routes |+| `Page` | `page.ts` | Owns FrameManager, workers; delegates to `PageDelegate` |+| `FrameManager` | `frames.ts` | Manages frame hierarchy |+| `Frame` | `frames.ts` | Navigation, DOM queries, JavaScript evaluation |+| `ElementHandle` | `dom.ts` | DOM element operations |+| `ProgressController` | `progress.ts` | Wraps async operations with timeout/cancellation/logging |++### PageDelegate Pattern++`Page` delegates browser-specific operations to a `PageDelegate` interface:++```typescript+interface PageDelegate {+ navigateFrame(frame, url, referer): Promise<GotoResult>;+ takeScreenshot(progress, format, ...): Promise<Buffer>;+ adoptElementHandle(handle, to): Promise<ElementHandle>;+ // ... more browser-specific operations+}+```++Implementations:+- `packages/playwright-core/src/server/chromium/crPage.ts` — uses CDP+- `packages/playwright-core/src/server/firefox/ffPage.ts`+- `packages/playwright-core/src/server/webkit/wkPage.ts`++### Browser Engine Directories++| Directory | Protocol | Key files |+|-----------|----------|-----------|+| `chromium/` | Chrome DevTools Protocol (CDP) | `crBrowser.ts`, `crPage.ts`, `crConnection.ts` |+| `firefox/` | Firefox internal protocol | `ffBrowser.ts`, `ffPage.ts`, `ffConnection.ts` |+| `webkit/` | WebKit internal protocol | `wkBrowser.ts`, `wkPage.ts`, `wkConnection.ts` |+| `bidi/` | WebDriver BiDi | `bidiChromium.ts`, `bidiFirefox.ts` |+| `android/` | ADB | `android.ts` |+| `electron/` | Electron/CDP | `electron.ts` |++## Dispatcher Layer++### Dispatcher — Base Class++```+packages/playwright-core/src/server/dispatchers/dispatcher.ts+```++Dispatchers bridge server objects to the protocol. Each wraps an `SdkObject` and exposes methods matching the protocol channel.++```typescript+class Dispatcher<Type extends SdkObject, ChannelType, ParentScopeType extends DispatcherScope>+```++Key properties:+- `connection: DispatcherConnection` — the server-side connection+- `_object: Type` — the wrapped server object+- `_guid: string` — same GUID as the server object+- `_type: string` — type name matching protocol+- `_parent: ParentScopeType` — parent dispatcher+- `_dispatchers: Map<string, DispatcherScope>` — child dispatchers++Key methods:+- `_dispatchEvent(method, params)` — sends event to client via `connection.sendEvent()`+- `_runCommand(callMetadata, method, params)` — wraps method call in `ProgressController`, calls `this[method](params, progress)`+- `_dispose()` — recursively disposes self and children, sends `__dispose__` to client+- `adopt(child)` — reparents child dispatcher, sends `__adopt__` to client+- `addObjectListener(event, handler)` — listens on wrapped server object, auto-cleaned on dispose++### Dispatcher Creation Pattern++Dispatchers use a static factory to ensure one-dispatcher-per-object:++```typescript+static from(parentScope, object): XxxDispatcher {+ return parentScope.connection.existingDispatcher<XxxDispatcher>(object) || new XxxDispatcher(parentScope, object);+}+```++The constructor sends `__create__` to the client with the initializer data.++### DispatcherConnection++Server-side counterpart to client's `Connection`:+- `_dispatcherByGuid` — all dispatchers by GUID+- `_dispatcherByObject` — maps server objects to their dispatchers (ensures 1:1)+- `dispatch(message)` — validates params, creates `CallMetadata`, calls instrumentation hooks, runs dispatcher method, validates result, sends response+- `sendCreate/sendAdopt/sendDispose/sendEvent` — lifecycle messages to client+- GC: buckets with limits (JSHandle/ElementHandle: 100k, others: 10k); oldest 10% disposed when exceeded++### Dispatcher Hierarchy++```+RootDispatcher+└── PlaywrightDispatcher+ ├── BrowserTypeDispatcher (per engine)+ │ └── BrowserDispatcher+ │ └── BrowserContextDispatcher+ │ ├── PageDispatcher+ │ │ ├── FrameDispatcher (main + child frames)+ │ │ ├── WorkerDispatcher+ │ │ └── ...+ │ ├── TracingDispatcher+ │ └── APIRequestContextDispatcher+ ├── AndroidDispatcher+ ├── ElectronDispatcher+ └── LocalUtilsDispatcher+```++### Key Dispatcher Files++| File | Dispatches for |+|------|---------------|+| `playwrightDispatcher.ts` | Playwright, BrowserType registration |+| `browserTypeDispatcher.ts` | BrowserType (launch, connect) |+| `browserDispatcher.ts` | Browser |+| `browserContextDispatcher.ts` | BrowserContext |+| `pageDispatcher.ts` | Page, Worker, BindingCall |+| `frameDispatcher.ts` | Frame |+| `networkDispatchers.ts` | Request, Response, Route, WebSocket, APIRequestContext |+| `elementHandlerDispatcher.ts` | ElementHandle |+| `jsHandleDispatcher.ts` | JSHandle |+| `dialogDispatcher.ts` | Dialog |+| `tracingDispatcher.ts` | Tracing |+| `artifactDispatcher.ts` | Artifact |++## End-to-End Flow Example++`await page.goto('https://example.com')`:++```+CLIENT:+ Page.goto()+ → _wrapApiCall() captures stack trace, creates ApiZone+ → _channel.goto({ url, timeout })+ → Proxy validates PageGotoParams+ → connection.sendMessageToServer(page, 'goto', params)+ → sends { id: 1, guid: 'page@abc', method: 'goto', params: {...} }+ → waits on callback promise++SERVER:+ DispatcherConnection.dispatch(message)+ → validates PageGotoParams (wire → objects)+ → creates CallMetadata+ → instrumentation.onBeforeCall()+ → PageDispatcher._runCommand('goto', params)+ → ProgressController.run(progress => this.goto(params, progress))+ → PageDispatcher.goto(): this._object.mainFrame().goto(progress, url, params)+ → Frame.goto() → PageDelegate.navigateFrame() → CDP/protocol call+ → validates PageGotoResult (objects → wire)+ → instrumentation.onAfterCall()+ → sends { id: 1, result: { response: { guid: 'response@xyz' } } }++CLIENT:+ connection.dispatch(response)+ → validates PageGotoResult (wire → objects)+ → resolves callback promise+ → _wrapApiCall completes, returns Response object+```++## Object Lifecycle++1. **Creation**: Server creates SdkObject → dispatcher constructor sends `__create__` → client `Connection.dispatch()` instantiates `ChannelOwner` subclass+2. **Adoption**: `dispatcher.adopt(child)` sends `__adopt__` → client reparents the `ChannelOwner`+3. **Disposal**: `dispatcher._dispose()` recursively disposes children → sends `__dispose__` → client removes `ChannelOwner` from maps+4. **GC**: Server-side `maybeDisposeStaleDispatchers()` evicts oldest dispatchers per bucket when limits exceeded