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
docs(skills): update stale paths in playwright-dev guides (#43051)
Gabriel dos Anjos0bd6f75751e6
diff --git a/.claude/skills/playwright-dev/api.md b/.claude/skills/playwright-dev/api.mdindex 2ef9ecb7d4..dd1a5e6639 100644--- a/.claude/skills/playwright-dev/api.md+++ b/.claude/skills/playwright-dev/api.md@@ -97,7 +97,7 @@ async goto(url: string, options: channels.FrameGotoOptions = {}): Promise<networ## Step 3: Define Protocol Channel-Define (or update) channel for the API in `packages/protocol/src/protocol.yml` as needed.+Define (or update) channel for the API in the matching `packages/protocol/spec/*.yml` file (e.g. `page.yml`) as needed.### Protocol YAML Format@@ -153,9 +153,9 @@ Page:**Flags:** `slowMo`, `snapshot`, `pausesBeforeAction`, `pausesBeforeInput`Watch will kick in and auto-generate:-- `packages/protocol/src/channels.d.ts` — channel TypeScript interfaces-- `packages/playwright-core/src/protocol/validator.ts` — runtime validators-- `packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts` — method metadata+- `packages/playwright-core/src/client/channels.d.ts`, `packages/playwright-core/src/server/channels.d.ts` — channel TypeScript interfaces+- `packages/protocol/src/validator.ts` — runtime validators+- `packages/isomorphic/protocolMetainfo.ts` — method metadata## Step 4: Implement Dispatcher@@ -283,7 +283,7 @@ npm run ctest -- --grep "should do something" # Filter by namedocs/src/api/class-xxx.md (API documentation — source of truth for public types)→ auto-generates → types.d.ts, test.d.ts-packages/protocol/src/protocol.yml (RPC protocol definition)+packages/protocol/spec/*.yml (RPC protocol definition)→ auto-generates → channels.d.ts, validator.ts, protocolMetainfo.tsClient call chain:diff --git a/.claude/skills/playwright-dev/library.md b/.claude/skills/playwright-dev/library.mdindex 52456a47cb..2742c30a20 100644--- a/.claude/skills/playwright-dev/library.md+++ b/.claude/skills/playwright-dev/library.md@@ -5,8 +5,12 @@ Playwright uses a client-server architecture connected by a protocol layer. The## Package Layout```-packages/protocol/src/- protocol.yml — RPC protocol definition (source of truth)+packages/protocol/+ spec/*.yml — RPC protocol definition (source of truth)+ src/ — validators (generated + primitives)++packages/isomorphic/ — shared code used by both client and server+ protocolMetainfo.ts — generated method metadata (flags, titles)packages/playwright-core/src/client/ — public API objects (ChannelOwner subclasses)@@ -14,9 +18,6 @@ packages/playwright-core/src/server/ — browser automation implementation (SdkObject subclasses)channels.d.ts — generated server channel interfacesserver/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)@@ -26,17 +27,16 @@ Each directory has a `DEPS.list` constraining its imports. These are enforced byEntries can be relative paths, alias paths (`@isomorphic/**`, `@utils/**`), or `node_modules/<pkg>` to allow a specific npm package import. The `"strict"` marker disables inheritance from parent folders. Section headers like `[filename.ts]` scope rules to a single file.**client/** can import from:-- `../protocol/` — validators and channel types-- `../utils/isomorphic` — shared utilities+- `@protocol/**` — validators and channel types+- `@isomorphic/**` — shared utilities**server/** can import from:-- `../protocol/`, `../utils/`, `../utils/isomorphic/`, `../utilsBundle.ts`-- `./` (own directory), `./codegen/`, `./isomorphic/`, `./har/`, `./recorder/`, `./registry/`, `./utils/`+- `@protocol/**`, `@utils/**`, `@isomorphic/**`+- `./` (own directory), `./har/`, `./recorder/`, `./registry/`- 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/`+- `@protocol/**`, `@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.@@ -45,9 +45,9 @@ Entries can be relative paths, alias paths (`@isomorphic/**`, `@utils/**`), or `## Protocol Layer-### protocol.yml+### packages/protocol/spec/*.yml-Defines all RPC interfaces, commands (methods), events, and types. Example:+These files define all RPC interfaces, commands (methods), events, and types, one file per domain (`page.yml`, `frame.yml`, ...). Example:```yamlPage:@@ -74,9 +74,9 @@ Page:### Code GenerationRunning `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.)+- `packages/playwright-core/src/client/channels.d.ts` and `packages/playwright-core/src/server/channels.d.ts` (plus shared `packages/protocol/src/structs.d.ts`) — TypeScript types: `PageChannel`, `PageGotoParams`, `PageGotoResult`, `PageInitializer`, event types+- `packages/protocol/src/validator.ts` — runtime validators: `scheme.PageGotoParams = tObject({...})`+- `packages/isomorphic/protocolMetainfo.ts` — method flags (slowMo, snapshot, etc.)### Wire Format@@ -408,9 +408,9 @@ it('should click button', async ({ page, server }) => {Examples:```bash-npm run ctest tests/library/browser-context-cookies.spec.ts+npm run ctest tests/library/browsercontext-cookies.spec.tsnpm run ctest tests/page/locator-click.spec.ts-npm run test tests/library/browser-context-cookies.spec.ts+npm run test tests/library/browsercontext-cookies.spec.ts```### Configurationdiff --git a/.claude/skills/playwright-dev/tools.md b/.claude/skills/playwright-dev/tools.mdindex 2789feedbc..f26b7c7f9c 100644--- a/.claude/skills/playwright-dev/tools.md+++ b/.claude/skills/playwright-dev/tools.md@@ -6,10 +6,10 @@Create `packages/playwright-core/src/tools/backend/<your-tool>.ts`.-Import zod from the MCP bundle and use `defineTool` or `defineTabTool`:+Import zod and use `defineTool` or `defineTabTool`:```typescript-import { z } from '../../zodBundle';+import * as z from 'zod';import { defineTool, defineTabTool } from './tool';```@@ -201,7 +201,7 @@ Implement the corresponding MCP tool first (see section above). CLI commands calIn `packages/playwright-core/src/tools/cli-daemon/commands.ts`, use `declareCommand()`:```typescript-import { z } from '../../zodBundle';+import * as z from 'zod';import { declareCommand } from './command';const myCommand = declareCommand({@@ -275,8 +275,8 @@ To add a new category:### Step 3: Update SKILL File-Update `packages/playwright/src/skill/SKILL.md` with the new command documentation.-Add reference docs in `packages/playwright/src/skill/references/` if the feature is complex.+Update `packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md` with the new command documentation.+Add reference docs in `packages/playwright-core/src/tools/skills/playwright-cli/references/` if the feature is complex.Run `npm run playwright-cli -- --help` to verify the help output includes your new command.@@ -398,9 +398,9 @@ If the option is nested, update `mergeConfig()` in `config.ts` to deep-merge it.## SKILL File-The skill file is located at `packages/playwright/src/skill/SKILL.md`. It contains documentation for all available CLI commands and MCP tools. Update it whenever you add new commands or tools.+The skill file is located at `packages/playwright-core/src/tools/skills/playwright-cli/SKILL.md`. It contains documentation for all available CLI commands and MCP tools. Update it whenever you add new commands or tools.-Reference docs live in `packages/playwright/src/skill/references/`:+Reference docs live in `packages/playwright-core/src/tools/skills/playwright-cli/references/`:- `request-mocking.md` — network mocking patterns- `running-code.md` — code execution- `session-management.md` — session handling@@ -481,12 +481,11 @@ packages/playwright-core/src/tools/│ ├── server.ts # MCP server wrapper│ ├── tool.ts # ToolSchema type, toMcpTool()│ └── http.ts # HTTP utilities-└── exports.ts # Public exports--packages/playwright/src/-└── skill/- ├── SKILL.md # Skill documentation- └── references/ # Reference docs+├── index.ts # Public exports+└── skills/+ └── playwright-cli/+ ├── SKILL.md # Skill documentation+ └── references/ # Reference docstests/mcp/├── fixtures.ts # MCP test fixtures (client, startClient, server)diff --git a/.claude/skills/playwright-dev/trace_system_guide.md b/.claude/skills/playwright-dev/trace_system_guide.mdindex c8312b7523..b7675d0f87 100644--- a/.claude/skills/playwright-dev/trace_system_guide.md+++ b/.claude/skills/playwright-dev/trace_system_guide.md@@ -323,7 +323,7 @@ traces-dir/## 7. Trace Recording (tracing.ts)-Located: `/home/pfeldman/code/playwright/packages/playwright-core/src/server/trace/recorder/tracing.ts`+Located: `packages/playwright-core/src/server/trace/recorder/tracing.ts`### Tracing Class Architecture@@ -429,7 +429,7 @@ type RecordingState = {## 8. Trace Loading (traceLoader.ts)-Located: `/home/pfeldman/code/playwright/packages/playwright-core/src/utils/isomorphic/trace/traceLoader.ts`+Located: `packages/isomorphic/trace/traceLoader.ts`### TraceLoaderBackend Interface```typescript@@ -494,7 +494,7 @@ type ContextEntry = {## 9. Trace Model (traceModel.ts)-Located: `/home/pfeldman/code/playwright/packages/playwright-core/src/utils/isomorphic/trace/traceModel.ts`+Located: `packages/isomorphic/trace/traceModel.ts`### TraceModel ClassHigh-level data model for trace viewer:@@ -553,7 +553,7 @@ type ActionTraceEventInContext = ActionEntry & {## 10. Trace Modernizer (traceModernizer.ts)-Located: `/home/pfeldman/code/playwright/packages/playwright-core/src/utils/isomorphic/trace/traceModernizer.ts`+Located: `packages/isomorphic/trace/traceModernizer.ts`### Version Support- **Latest:** Version 8@@ -585,7 +585,7 @@ class TraceModernizer {## 11. Trace Viewer-Located: `/home/pfeldman/code/playwright/packages/trace-viewer/src/`+Located: `packages/trace-viewer/src/`### Structure```@@ -624,7 +624,7 @@ trace-viewer/src/## 12. CLI Commands-Located: `/home/pfeldman/code/playwright/packages/playwright-core/src/cli/program.ts`+Located: `packages/playwright-core/src/cli/program.ts`### show-trace Command```bash@@ -918,9 +918,9 @@ Every action uses a unique `callId` to correlate:| `playwright-core/.../tracing.ts` | 700+ lines | Recording engine || `playwright-core/.../traceParser.ts` | 62 lines | ZIP backend || `playwright-core/.../traceViewer.ts` | 288 lines | Viewer server |-| `playwright-core/.../traceLoader.ts` | 158 lines | Load traces |-| `playwright-core/.../traceModel.ts` | 300+ lines | Data model |-| `playwright-core/.../traceModernizer.ts` | 500+ lines | Version upgrades |+| `isomorphic/trace/traceLoader.ts` | 158 lines | Load traces |+| `isomorphic/trace/traceModel.ts` | 300+ lines | Data model |+| `isomorphic/trace/traceModernizer.ts` | 500+ lines | Version upgrades || `trace-viewer/src/index.tsx` | 48 lines | Viewer entry || `trace-viewer/src/ui/workbench.tsx` | Main UI | Display |diff --git a/.claude/skills/playwright-dev/vendor.md b/.claude/skills/playwright-dev/vendor.mdindex 3eb985aae8..2ba612a649 100644--- a/.claude/skills/playwright-dev/vendor.md+++ b/.claude/skills/playwright-dev/vendor.md@@ -49,7 +49,7 @@ export key lives in `utils/build/utilsBundleMapping.js`.The `common` and `runner` bundles externalize `../transform/babelBundle`(among other things) so babel code is not duplicated across them. The-`lib/transform/transform.ts` module uses `libPath('transform', 'babelBundle')`+`src/transform/transform.ts` module uses `libPath('transform', 'babelBundle')`(absolute path via `package.ts` root) to load the babel bundle at runtime,so it works regardless of which bundle has inlined it.@@ -133,12 +133,12 @@ inlined into `utilsBundle` (i.e., loaded through `require('./utilsBundle').<key>## In-tree Third-Party HelpersSome vendored code isn't a published npm package but lives in-tree at-`packages/playwright-core/src/server/utils/third_party/` (e.g.+`packages/utils/third_party/` (e.g.`extractZip.ts`, `lockfile.ts`). These are TypeScript files, notnode_modules. They're exposed to callers via two different routes:- **Through `coreBundle.utils`.** Re-exported from- `src/server/utils/index.ts` via `export * from './third_party/extractZip'`+ `packages/utils/index.ts` via `export * from './third_party/extractZip'`etc. Callers import via the `@utils/*` path alias:```tsimport { extractZip } from '@utils/third_party/extractZip';@@ -228,7 +228,7 @@ imports to the sibling bundle at consumer output level:- To add a new vendored npm dep: root `package.json` → `utilsBundle.ts`export → `utilsBundleMapping.js` entry → DEPS.list → `npm run flint`.- To add a new in-tree third-party helper: drop the `.ts` file under- `server/utils/third_party/`, re-export from `server/utils/index.ts`,+ `packages/utils/third_party/`, re-export from `packages/utils/index.ts`,and use `@utils/third_party/<name>` at call sites.- To add a new bundle entry: add an `EsbuildStep` in`utils/build/build.js`, pick output location so relative externalsdiff --git a/CLAUDE.md b/CLAUDE.mdindex e5f8fca852..b54822a515 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -6,7 +6,7 @@| `playwright` | `playwright` | Test runner + browser automation (public package) || `playwright-test` | `@playwright/test` | Test runner entry point || `playwright-client` | `@playwright/client` | Standalone client package |-| `protocol` | *(internal)* | RPC protocol definitions (`protocol.yml` → generated `channels.d.ts`) |+| `protocol` | *(internal)* | RPC protocol definitions (`spec/*.yml` → generated validators and channel types) |### Browser Packages