Skip to content

CLAUDE.md

Latest commit

 

History

History
139 lines (101 loc) · 5.98 KB

CLAUDE.md

File metadata and controls

139 lines (101 loc) · 5.98 KB

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.

Tooling 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

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.

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
)"
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>

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