API documentation format for methods
Method definitions in `docs/src/api/class-xxx.md` use the format: `## async method: Page.methodName` with metadata `* since: v1.XX` (version from package.json without -next), return type as `- returns: <[null]|[Response]>`, and description. Include `### param:` sections for required parameters and `### option:` sections for optional parameters, each with `* since: v1.XX`, type annotation like `<[string]>`, and description. Optional metadata includes `* langs: js, python` for language filters and `* deprecated: v1.XX` for deprecation.
Client implementation pattern for new APIs
Client classes in `packages/playwright-core/src/client/xxx.ts` extend `ChannelOwner<XxxChannel>` and call through `this._channel`. Parameters are assembled into a single object with timeout processed through `this._timeout(options)` or `this._navigationTimeout(options)`. Return values are unwrapped using helpers like `Response.fromNullable()` or `ElementHandle.from()`. Locator methods delegate to Frame with `strict: true`, and Page methods often delegate to `this._mainFrame`.
Protocol YAML format for channel definitions
Channel methods are defined under `commands:` in interface sections in `packages/protocol/src/protocol.yml`. Each method includes `title:` (short description for tracing), `parameters:` object with type definitions, and optional `returns:` object. Type primitives are `string`, `int`, `float`, `boolean`, `binary`, `json`. Optional types append `?`: `string?`, `int?`. Arrays use `type: array` with `items:` definition. Enums use `type: enum` with `literals:` list. Flags include `slowMo`, `snapshot`, `pausesBeforeAction`, `pausesBeforeInput`.
Dispatcher pattern for handling API calls
Dispatchers in `packages/playwright-core/src/server/dispatchers/xxxDispatcher.ts` implement method signature `async method(params: channels.XxxMethodParams, progress: Progress): Promise<channels.XxxMethodResult>`. Extract params with `params.url`, `params.selector`, etc. Convert dispatcher references to server objects by casting to specific dispatcher type and accessing `._object`. Wrap server objects as dispatchers in results using helpers like `ResponseDispatcher.fromNullable()` or `ElementHandleDispatcher.from()`. All methods receive `Progress` for timeout and cancellation.
Server implementation for browser interactions
Server methods in `packages/playwright-core/src/server/xxx.ts` implement actual browser interaction logic. Browser-specific implementations live in `packages/playwright-core/src/server/chromium/crPage.ts` (Chromium using CDP), `packages/playwright-core/src/server/firefox/ffPage.ts` (Firefox), and `packages/playwright-core/src/server/webkit/wkPage.ts` (WebKit). Server methods accept `Progress` parameter for timeout/cancellation and delegate to browser-specific page delegates.
API documentation as source of truth for types
Documentation in `docs/src/api/class-xxx.md` is the source of truth for public API types. The watch process auto-generates `packages/playwright-core/types/types.d.ts` (public API types) and `packages/playwright/types/test.d.ts` (test API types) from this documentation.
Protocol YAML auto-generation
The `packages/protocol/src/protocol.yml` file auto-generates: `packages/protocol/src/channels.d.ts` (channel TypeScript interfaces), `packages/playwright-core/src/protocol/validator.ts` (runtime validators), and `packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts` (method metadata).
Language-specific method naming in API documentation
Use `* langs: js, python` to filter API documentation by language. Use `* langs: alias-java: navigate` syntax to specify language-specific method names (e.g., Java might use a different name for the same method).
Shared parameter definitions in Playwright API docs
Reuse shared parameter definitions from `docs/src/api/params.md` using the syntax `= %%-placeholder-name-%%` instead of repeating parameter documentation.
Type annotation syntax in Playwright API documentation
Type annotations use the format `<[TypeName]>`. Primitives are `<[string]>`, `<[int]>`, `<[float]>`, `<[boolean]>`. Union types use pipe: `<[null]|[Response]>`. Arrays use `<[Array]<[Locator]>>`. Objects use `<[Object]>` with indented `- \`field\` <[type]>` lines for each property.
Use minimal playwright.config.ts with single chromium project for regression testing
When testing regressions, write a minimal playwright.config.ts that specifies a single chromium project rather than using the default scaffold's 3-project config. The 3-project config will run the same spec 6 times and obscure output.
Minimal playwright.config.ts example for bisecting regressions
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
});
Map config option from environment variables
In `configFromEnv()` in `config.ts`, add environment variable mapping using helper functions: `envToString()` for strings, `envToBoolean()` for booleans, `numberParser()` for numbers, `commaSeparatedList()` for comma-separated lists, or `semicolonSeparatedList()` for semicolon-separated lists.
Add config option CLI flag
In `packages/playwright-core/src/tools/mcp/program.ts`, add a CLI flag for the new config option using `.option('--my-option <value>', 'description of option')`
Config resolution order
Configuration resolution order follows: defaultConfig → config file → environment variables → CLI arguments (last wins).
Add config option to Config type definition
When adding a new config option, first add it to the `Config` type in `packages/playwright-core/src/tools/mcp/config.d.ts` with JSDoc description using the format: `myOption?: string;`
Add config option to CLIOptions and FullConfig types
Add the new config option to the `CLIOptions` type in `packages/playwright-core/src/tools/mcp/config.ts`. If the option needs to be in `FullConfig` with required/resolved values, add it there as a required field and provide a default value in the `defaultConfig` object.
Map config option in configFromCLIOptions function
In `configFromCLIOptions()` in `config.ts`, map the CLI option to the config object using the pattern: `myOption: cliOptions.myOption,`