Monorepo Packages
| Package | npm name | Purpose |
|---|
playwright-core | playwright-core | Browser automation engine: client, server, dispatchers, protocol |
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) |
Browser Packages
playwright-chromium, playwright-firefox, playwright-webkit — per-browser distributions.
playwright-browser-chromium, playwright-browser-firefox, playwright-browser-webkit — binary packages.
| Package | Purpose |
|---|
html-reporter | HTML test report viewer |
trace-viewer | Trace viewer UI |
recorder | Test recorder |
web | Shared web UI components |
injected | Scripts injected into browser pages |
Component Testing
playwright-ct-core, playwright-ct-react, playwright-ct-vue
Key Directories
| Directory | Purpose |
|---|
tests/ | All test suites (page, library, playwright-test, mcp, components, etc.) |
docs/src/ | API documentation — source of truth for public TypeScript types |
docs/src/api/ | Per-class API reference (class-page.md, class-locator.md, etc.) |
utils/ | Build scripts, code generation, linting, doc tools |
browser_patches/ | Browser engine patches |
Build
npm run build # Full build
npm run watch # Watch mode (recommended during development)
Assume watch is running and code is up to date. Generated files (types, channels, validators) are produced by watch automatically.
Lint and type check
npm run flint
Runs all lint checks in parallel: eslint, tsc, doclint, check-deps, generate_channels, generate_types, lint-tests, test-types, lint-packages, code-snippet linting.
Always run flint before committing. Do not use tsc --noEmit or individual lint commands separately.
Test Commands
| Command | Scope |
|---|
npm run ctest <filter> | Chromium only library tests — use during development |
npm run test <filter> -- --project=<chromium,firefix,webkit> | All library / per project |
npm run ttest <filter> | Test runner (tests/playwright-test/) |
npm run ctest-mcp <filter> | Chromium only MCP tools (tests/mcp/) |
npm run test-mcp <filter> -- --project=<chromium,firefox,webkit> | MCP tools (tests/mcp/) |
Filtering
npm run ctest tests/page/locator-click.spec.ts # Specific file
npm run ctest tests/page/locator-click.spec.ts:12 # Specific location
npm run ctest -- --grep "should click" # By test name
npm run ctest-mcp snapshot # By file name part
Test Directories and Fixtures
| Directory | Import | Key Fixtures | What to Test |
|---|
tests/page/ | import { test, expect } from './pageTest' | page, server, browserName | User interactions: click, fill, navigate, locators, assertions |
tests/library/ | import { browserTest, expect } from '../config/browserTest' | browser, context, browserType | Browser/context lifecycle, cookies, permissions, browser-specific features |
tests/playwright-test/ | import { test, expect } from './playwright-test-fixtures' | test runner fixtures | Test runner: reporters, config, annotations, retries |
tests/mcp/ | import { test, expect } from './fixtures' | client, server | MCP tools via client.callTool() |
Decision rule: Does the test need browser/browserType/context → tests/library/. Just needs page + server → tests/page/.
DEPS System
Import boundaries are enforced via DEPS.list files (52+ across the repo), checked by npm run flint.
Key rule: Client code NEVER imports server code. Server code NEVER imports client code. Communication is only through the protocol.
When creating or moving files, update the relevant DEPS.list to declare allowed imports. Files marked "strict" can only import what is explicitly listed.
Coding Convention
For exported classes:
private _method() — only used within the class itself_method() (no private) — used by other code in the same file, but not outside the filemethod() (public) — used in other files
Non-exported classes have no naming convention; they are internal implementation details.
Commit Convention
Before committing, run npm run flint and fix errors.
Semantic commit messages: label(scope): description
Labels: fix, feat, chore, docs, test, devops
git checkout -b fix-39562
# ... make changes ...
git add <changed-files>
git commit -m "$(cat <<'EOF'
fix(proxy): handle SOCKS proxy authentication
Fixes: https://github.com/microsoft/playwright/issues/39562
EOF
)"
# **Never `git push` without an explicit instruction to push.**
git push origin fix-39562
gh pr create --repo microsoft/playwright --head username:fix-39562 \
--title "fix(proxy): handle SOCKS proxy authentication" \
--body "$(cat <<'EOF'
## Summary
- <describe the change very! briefly>
Fixes https://github.com/microsoft/playwright/issues/39562
EOF
)"
Never add Co-Authored-By agents in commit message.
Never add "Generated with" in commit message.
Never add test plan to PR description. Keep PR description short — a few bullet points at most.
Branch naming for issue fixes: fix-<issue-number>
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.
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.
Development Guides
Detailed guides for common development tasks:
- Architecture: Client, Server, and Dispatchers — package layout, protocol layer, ChannelOwner/SdkObject/Dispatcher base classes, DEPS rules, end-to-end RPC flow, object lifecycle
- Adding and Modifying APIs — 6-step process: define docs → implement client → define protocol → implement dispatcher → implement server → write tests
- MCP Tools and CLI Commands —
defineTool()/defineTabTool(), tool capabilities, CLI declareCommand(), config options, testing with MCP fixtures
- Vendoring Dependencies — bundle architecture, esbuild setup, typed wrappers, adding deps to existing bundles