CLAUDE.md

1### Monorepo Packages
2 
3| Package | npm name | Purpose |
4|---------|----------|---------|
5| `playwright-core` | `playwright-core` | Browser automation engine: client, server, dispatchers, protocol |
6| `playwright` | `playwright` | Test runner + browser automation (public package) |
7| `playwright-test` | `@playwright/test` | Test runner entry point |
8| `playwright-client` | `@playwright/client` | Standalone client package |
9| `protocol` | *(internal)* | RPC protocol definitions (`protocol.yml` → generated `channels.d.ts`) |
10 
11### Browser Packages
12 
13`playwright-chromium`, `playwright-firefox`, `playwright-webkit` — per-browser distributions.
14`playwright-browser-chromium`, `playwright-browser-firefox`, `playwright-browser-webkit` — binary packages.
15 
16### Tooling Packages
17 
18| Package | Purpose |
19|---------|---------|
20| `html-reporter` | HTML test report viewer |
21| `trace-viewer` | Trace viewer UI |
22| `recorder` | Test recorder |
23| `web` | Shared web UI components |
24| `injected` | Scripts injected into browser pages |
25 
26### Component Testing
27 
28`playwright-ct-core`, `playwright-ct-react`, `playwright-ct-vue`
29 
30### Key Directories
31 
32| Directory | Purpose |
33|-----------|---------|
34| `tests/` | All test suites (page, library, playwright-test, mcp, components, etc.) |
35| `docs/src/` | API documentation — **source of truth** for public TypeScript types |
36| `docs/src/api/` | Per-class API reference (`class-page.md`, `class-locator.md`, etc.) |
37| `utils/` | Build scripts, code generation, linting, doc tools |
38| `browser_patches/` | Browser engine patches |
39 
40## Build
41 
42```bash
43npm run build       # Full build
44npm run watch       # Watch mode (recommended during development)
45```
46 
47Assume watch is running and code is up to date. Generated files (types, channels, validators) are produced by watch automatically.
48 
49## Lint and type check
50 
51```bash
52npm run flint
53```
54 
55Runs all lint checks in parallel: eslint, tsc, doclint, check-deps, generate_channels, generate_types, lint-tests, test-types, lint-packages, code-snippet linting.
56 
57**Always run `flint` before committing.** Do not use `tsc --noEmit` or individual lint commands separately.
58 
59## Test Commands
60 
61| Command | Scope |
62|---------|-------|
63| `npm run ctest <filter>` | Chromium only library tests — **use during development** |
64| `npm run test <filter> -- --project=<chromium,firefix,webkit>` | All library / per project |
65| `npm run ttest <filter>` | Test runner (`tests/playwright-test/`) |
66| `npm run ctest-mcp <filter>` | Chromium only MCP tools (`tests/mcp/`) |
67| `npm run test-mcp <filter> -- --project=<chromium,firefox,webkit>` | MCP tools (`tests/mcp/`) |
68 
69 
70### Filtering
71 
72```bash
73npm run ctest tests/page/locator-click.spec.ts         # Specific file
74npm run ctest tests/page/locator-click.spec.ts:12      # Specific location
75npm run ctest -- --grep &quot;should click&quot;                 # By test name
76npm run ctest-mcp snapshot                             # By file name part
77```
78 
79### Test Directories and Fixtures
80 
81| Directory | Import | Key Fixtures | What to Test |
82|-----------|--------|--------------|--------------|
83| `tests/page/` | `import { test, expect } from './pageTest'` | `page`, `server`, `browserName` | User interactions: click, fill, navigate, locators, assertions |
84| `tests/library/` | `import { browserTest, expect } from '../config/browserTest'` | `browser`, `context`, `browserType` | Browser/context lifecycle, cookies, permissions, browser-specific features |
85| `tests/playwright-test/` | `import { test, expect } from './playwright-test-fixtures'` | test runner fixtures | Test runner: reporters, config, annotations, retries |
86| `tests/mcp/` | `import { test, expect } from './fixtures'` | `client`, `server` | MCP tools via `client.callTool()` |
87 
88**Decision rule**: Does the test need `browser`/`browserType`/`context` → `tests/library/`. Just needs `page` + `server` → `tests/page/`.
89 
90## DEPS System
91 
92Import boundaries are enforced via `DEPS.list` files (52+ across the repo), checked by `npm run flint`.
93 
94**Key rule**: Client code NEVER imports server code. Server code NEVER imports client code. Communication is only through the protocol.
95When creating or moving files, update the relevant `DEPS.list` to declare allowed imports. Files marked `"strict"` can only import what is explicitly listed.
96 
97## Coding Convention
98 
99For exported classes:
100- `private _method()` — only used within the class itself
101- `_method()` (no `private`) — used by other code in the same file, but not outside the file
102- `method()` (public) — used in other files
103 
104Non-exported classes have no naming convention; they are internal implementation details.
105 
106## Commit Convention
107 
108Before committing, run `npm run flint` and fix errors.
109 
110Semantic commit messages: `label(scope): description`
111 
112Labels: `fix`, `feat`, `chore`, `docs`, `test`, `devops`
113 
114```bash
115git checkout -b fix-39562
116# ... make changes ...
117git add &lt;changed-files&gt;
118git commit -m &quot;$(cat &lt;&lt;'EOF'
119fix(proxy): handle SOCKS proxy authentication
120 
121Fixes: https://github.com/microsoft/playwright/issues/39562
122EOF
123)&quot;
124# **Never `git push` without an explicit instruction to push.**
125git push origin fix-39562
126gh pr create --repo microsoft/playwright --head username:fix-39562 \
127  --title &quot;fix(proxy): handle SOCKS proxy authentication&quot; \
128  --body &quot;$(cat &lt;&lt;'EOF'
129## Summary
130- &lt;describe the change very! briefly&gt;
131 
132Fixes https://github.com/microsoft/playwright/issues/39562
133EOF
134)&quot;
135```
136 
137Never add Co-Authored-By agents in commit message.
138Never add "Generated with" in commit message.
139Never add test plan to PR description. Keep PR description short — a few bullet points at most.
140Branch naming for issue fixes: `fix-<issue-number>`
141 
142**Never amend commits.** Always create a new commit for follow-up changes, even when iterating on an open PR. Amending rewrites history and forces a force-push, losing the incremental review trail. Only amend if the user explicitly says so.
143 
144**Never `git push` without an explicit instruction to push.** Applies even when a PR is already open for the branch — additional commits are immediately visible to reviewers. Commit locally, report what was committed, and wait. Only push when the user's message contains "push", "upload", "create PR", "ship it", or equivalent.
145 
146## Development Guides
147 
148Detailed guides for common development tasks:
149 
150- **[Architecture: Client, Server, and Dispatchers](.claude/skills/playwright-dev/library.md)** — package layout, protocol layer, ChannelOwner/SdkObject/Dispatcher base classes, DEPS rules, end-to-end RPC flow, object lifecycle
151- **[Adding and Modifying APIs](.claude/skills/playwright-dev/api.md)** — 6-step process: define docs → implement client → define protocol → implement dispatcher → implement server → write tests
152- **[MCP Tools and CLI Commands](.claude/skills/playwright-dev/tools.md)** — `defineTool()`/`defineTabTool()`, tool capabilities, CLI `declareCommand()`, config options, testing with MCP fixtures
153- **[Vendoring Dependencies](.claude/skills/playwright-dev/vendor.md)** — bundle architecture, esbuild setup, typed wrappers, adding deps to existing bundles
154