Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

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.md
index 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 name
docs/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.ts
Client call chain:
diff --git a/.claude/skills/playwright-dev/library.md b/.claude/skills/playwright-dev/library.md
index 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 interfaces
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)
@@ -26,17 +27,16 @@ Each directory has a `DEPS.list` constraining its imports. These are enforced by
Entries 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:
```yaml
Page:
@@ -74,9 +74,9 @@ Page:
### 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.)
+- `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.ts
npm 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
```
### Configuration
diff --git a/.claude/skills/playwright-dev/tools.md b/.claude/skills/playwright-dev/tools.md
index 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 cal
In `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 docs
tests/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.md
index 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 Class
High-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.md
index 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 Helpers
Some 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, not
node_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:
```ts
import { 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 externals
diff --git a/CLAUDE.md b/CLAUDE.md
index 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