microsoft/playwright
github.com/microsoft/playwright ↗ · 2660 files · 26.6 MB
🎭 Playwright Documentation | API reference Playwright is a framework for web automation and testing.
Overview
Playwright is a Node.js browser automation and testing monorepo for developers writing browser scripts, end-to-end tests, and agent-driven automation. At commit b630e71fcda7885885c459bcbb88e5bfa7c0a1ac, it combines a client/server automation engine, a parallel test runner, browser installation tooling, reporting and trace interfaces, and CLI/MCP browser tools. Its distinctive architecture carries typed commands through validated protocol dispatchers to browser implementations and injected page scripts.
System map
The repository separates browser automation, test orchestration, protocol definitions, and browser-facing interfaces into workspace packages. Local automation still crosses a client/dispatcher boundary before reaching browser implementations. Persistent state consists of browser profiles, browser installation caches, and explicit JSON/artifact files. The inspected deployment surfaces are Node packages, command-line programs, and optional browser-control servers.
- The private playwright-internal workspace is version 1.64.0-next, requires Node.js >=20, and includes packages/* as npm workspaces.
- The playwright package exports CommonJS/ESM library and test entrypoints, installs the playwright executable, and depends on the matching playwright-core version.
- packages/playwright/cli.js loads the compiled program and parses process.argv; program.ts decorates the shared library CLI before adding test-runner commands.
- createInProcessPlaywright wires Connection to DispatcherConnection, enables raw buffers, creates PlaywrightDispatcher, and switches from synchronous initialization to setImmediate message delivery.
- BrowserType launches native executables and selects WebSocketTransport or PipeTransport according to supportsPipeTransport.
- Test phases use Dispatcher to allocate worker slots; WorkerHost identifies the worker process entry and assigns a per-worker artifact directory.
- Browser installation storage honors PLAYWRIGHT_BROWSERS_PATH, including package-local mode '0'; installation locks the registry and records package links before optional cache cleanup.
- Root scripts define build/watch, combined linting, browser-specific tests, stable-runner tests, MCP tests, and platform-specific suites.
Feature catalog
The inspected public surfaces span browser automation, test execution, artifact inspection, and agent tools. Test execution exposes filtering, sharding, retries, debugging, and interactive UI options. Browser tooling includes installation, recording, screenshots, PDFs, and remote connections. These eight groups describe implemented command and API families; they are not an exhaustive method inventory.
- BrowserType exposes ordinary launch, persistent-context launch, server launch, and CDP attachment; connectOverCDP accepts endpoint URLs or a local transport and restricts supported engines.
- Locator.click delegates with strict selection by default; pointer actions wait for visible, enabled, and stable elements unless force bypasses those checks.
- The test CLI exposes grep/project filters, retries, repetition, worker counts, sharding, shuffle seeds, last-failed selection, snapshot updates, tracing, and UI mode.
- createReporters supports blob, Perfetto, terminal, GitHub, JSON, JUnit, HTML, and coverage reporters; show-report serves a report and merge-reports combines sharded blob reports.
- The library CLI provides open and codegen with language targets, screenshot with full-page/wait options, PDF capture, and show-trace in an app or browser-served mode.
- Browser lifecycle commands include install, uninstall, and install-deps with browser selection, dry-run, force, headless-shell, and cache-removal controls.
- BrowserContext supports storageState and setStorageState; saved state includes cookies and origin storage, with opt-in IndexedDB, OPFS, and credentials collection.
- The CLI mounts agent cli and mcp commands; browserTools aggregates navigation, input, dialogs, files, network/routes, snapshots, capture, storage, recording, verification, and WebMCP tools, while init-agents selects among supported agent generators.
Data flow
Commands enter through CLI parsing or client APIs and are normalized before reaching execution owners. Protocol messages carry object identities, parameters, timeouts, and metadata, with validation on both dispatch and response paths. Test state flows through project phases and workers to reporters and persisted selection metadata. Browser storage travels between injected page code, server context state, and client-owned JSON files.
- runTests converts CLI options to overrides, loads configuration, builds TestRunOptions, validates project filters, then branches to UI, watch, or ordinary execution.
- Connection.sendMessageToServer creates id/guid/method/params messages with timeout/location metadata, tracks callbacks, and emits __abort__ when a supplied signal aborts.
- DispatcherConnection resolves the target GUID, validates parameters and metadata, invokes the dispatcher under a ProgressController timeout, and validates the returned result.
- During test phases, dependency-produced environment variables are merged into downstream projects; failed dependencies prevent their test groups from being dispatched.
- LastRunReporter persists status and failed/unrun test IDs to .last-run.json or an override path, skips writes in list mode, and treats unreadable prior state as unavailable.
- storageState collects cookies, tries utility-world collection on live pages, then visits remaining origins through an intercepted blank page; the client optionally writes the returned object as formatted JSON.
- prepareStorageState accepts an object or parses a client-side file; setStorageState restores cookies/credentials and invokes StorageScript.restore for the union of old and new origins.
- API fetch merges default/request headers, resolves baseURL and query parameters, serializes the request body, sends with retry handling, and stores the response body under a fetch UID.
Behavior traces
Four concrete flows were followed through source: test startup/execution, browser launch, locator click, and storage save/restore. The traces below preserve execution order and significant conditions. Error handling, force behavior, and reuse modes change these paths. They describe source behavior rather than observed runtime executions.
- Test startup: cli.js → program.parse → addTestCommand action → runTests → overridesFromOptions → loadConfigFromFile → filterProjects; arguments after '--' are removed from file filters.
- Ordinary test execution: runAllTestsWithConfig → createReporters/LastRunReporter → rebaseline/global-setup/load tasks → phase/report/run tasks → runTasks; list mode instead loads and reports without those execution tasks.
- Worker scheduling: createRunTestsTask checks dependencies → Dispatcher.run allocates slots and schedules → _createWorker constructs WorkerHost → WorkerHost.start creates artifacts and starts the runner; workers receive groups through runTestGroup messages.
- Browser launch: client BrowserType.launch normalizes args/env → channel.launch → BrowserTypeDispatcher.launch checks denyLaunch → server BrowserType.launch validates options and chooses Selenium or _innerLaunchWithRetries → _innerLaunch.
- Native launch continuation: _prepareToLaunch creates/selects directories and resolves the executable → _launchProcess calls launchProcess and waits for readiness → pipe/WebSocket transport → connectToTransport; persistent default-context preparation is skipped with ignoreAllDefaultArgs.
- Click: Locator.click delegates to its frame with strict:true → FrameDispatcher.click → server Frame.click → _retryWithProgressIfNotConnected → handle._click → _retryPointerAction → page.mouse.click; detached targets retry and force skips prechecks/visibility waits.
- Storage save: client storageState → BrowserContextDispatcher.storageState → server storageState → injected StorageScript.collect on live or temporary pages → channel result → optional mkdir/writeFile on the client.
- Storage replacement: prepareStorageState → channel.setStorageState → dispatcher calls server mode 'api' → cache/cookie cleanup → cookie/credential restore → intercepted origin navigation and StorageScript.restore → temporary-page close; resetForReuse retains the page and removes its interceptor.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage is claimed. The repository uses Playwright fixtures for browser behavior and a stable runner for testing its own runner. Inspected specifications exercise success, failure, persistence, authentication redirects, and report rendering. Coverage observations are bounded to the files and ranges read, with explicit platform exclusions and CI trigger limits.
- The library config constructs separate library/page projects for Chromium, Firefox, and WebKit, excludes other-engine filenames, supports executable/mode overrides, and enables three CI retries.
- Runner tests import defineConfig from stable-test-runner; npm run ttest invokes that runner's installed CLI, and PWTEST_COVERAGE conditionally enables reporter/viewer UI coverage.
- locator-click.spec.ts covers basic/double clicks, removal of the page's Node global, and target removal during pointerup or pointerdown.
- Storage-state tests check multi-origin localStorage, replacement without extra surviving pages, malformed origins, and JSON/IndexedDB round trips; selected restore cases are marked fixme for msedge channels.
- runner.spec.ts checks duplicate-title rejection, forbidOnly errors, continuation after worker exit, and subprocess creation failure; its SIGINT test explicitly skips Windows.
- HTML reporter tests generate and inspect both directly created and intermediate-merged reports, asserting outcome counters and visibility; global-fetch tests assert authorization retention/removal and HTTPS-error option propagation.
- Primary CI defines browser/Node matrices and sharded runner jobs; the shared run-test action installs dependencies, builds, installs browsers, executes tests under Xvfb on Linux, and conditionally uploads reports. These definitions were inspected, not run.
- Test scope is conditional: BiDi excludes inspector/page-leak files and uses zero retries; Android/Electron/WebView configs reuse page suites, extension tests select Chromium, and MCP has a separate cross-platform/browser CI matrix. These definitions do not establish exhaustive executed coverage.
Risk map
The inspected code intentionally exercises powerful host, browser, network, and filesystem capabilities. The observations below identify trust boundaries and maintenance-sensitive branches, not confirmed vulnerabilities. Some controls are explicitly configurable or bypassed in trusted modes. Test exclusions and asynchronous cleanup are source-level limitations, not evidence of a failing implementation.
- browser_run_code_unsafe explicitly describes itself as RCE-equivalent, compiles supplied JavaScript with vm.runInContext, exposes page and host fetch, and can load snippets from a resolved filename.
- Agent checkFile resolves symlinks and restricts filenames to workspace/output roots, but explicitly bypasses checks for code-origin calls, allowUnrestrictedFileAccess, or skillMode.
- WebServerPlugin executes config.webServer.command with shell:true, inherited process environment, configured environment additions, and a config-relative working directory.
- Browser launch accepts caller-selected executables and environments and creates profile/artifact directories outside the checkout; launch and teardown changes affect native processes and host filesystem state.
- storageState writes cookie/origin data and optional credentials as plain JSON to a caller path; context preparation also reads caller-selected certificate/key/PFX paths into protocol buffers.
- API requests can disable TLS verification through ignoreHTTPSErrors, and that choice propagates across redirects; cross-origin redirects strip Authorization while Basic challenges may trigger credential retry.
- Storage restore includes deliberate asynchronous cleanup: some service-worker unregister operations are not awaited, IndexedDB deletions omit callback waits, and msedge restore tests document a cache-clear stall exclusion.
- Protocol compatibility is coupled across generated client/server channels, validators, and dispatchers; dispatch rejects schema/method mismatches, and the generator writes multiple outputs and exits nonzero when they change.
Extension points
The repository provides concrete registries, factories, and schemas for extending behavior. Some are public configuration surfaces, while others are internal integration seams. Protocol and generated-type changes require coordinated edits across boundaries. Browser engines and injected selector behavior have explicit synchronization requirements.
- Connection.registerObjectFactories installs type-to-ChannelOwner constructors in a map; the constructor registers Browser, BrowserContext, Page, Route, Tracing, Android, Electron, and other protocol object types.
- Protocol commands are declared in YAML with parameter mixins and typed returns; generate_channels emits client/server channel interfaces, structs, metadata, and runtime validators.
- createReporters is a constructor registry for built-ins and loads custom reporter modules from configuration or PW_TEST_REPORTER, adapting them through wrapReporterAsV2.
- TestRunnerPlugin defines asynchronous setup/teardown hooks; registration accepts an instance or synchronous/asynchronous factory, and createPluginSetupTasks invokes those lifecycle hooks.
- Selectors.register accepts custom engines after name/reserved/duplicate checks; parseSelector selects main or utility execution worlds based on engine contentScript and built-in requirements.
- Agent tool modules are assembled in browserTools; filteredTools retains core or enabled capabilities, excludes skillOnly tools, and removes selector fields from exposed schemas.
- defineTool preserves a typed schema/handler definition; defineTabTool wraps handlers with ensureTab and modal-state compatibility checks, allowing tools to declare which modal state they clear.
- BrowserType is an abstract engine seam for defaultArgs, connectToTransport, amendEnvironment, startup-log rewriting, and graceful close; CLI additions attach through decorateProgram and the testOptions command table.
Contributor handoff
Start with the owning package and follow the relevant client/protocol/server or runner/worker boundary. Preserve generated-source ownership, dependency rules, and platform-specific behavior. Tests and CI were inspected, not executed, and this inventory is bounded rather than exhaustive. The commands below are future validation pointers; the current read-only investigation did not run them.
- Read package.json, CONTRIBUTING.md, CLAUDE.md, and the owning package manifest first: browser API work belongs primarily in playwright-core, runner work in playwright, with Node.js >=20 and npm workspaces.
- Preserve client/server import separation and inspect DEPS.list before moving code; actual client dependency declarations allow shared protocol/isomorphic utilities rather than server implementations.
- Edit API documentation and protocol schemas as source inputs rather than treating generated types/channels/validators as independent implementations; generator checks may write files.
- Place page interaction tests with pageTest fixtures, browser/context lifecycle tests with browserTest, runner tests with playwright-test fixtures, and agent-tool tests with MCP fixtures.
- For later authorized validation, use filtered ctest for Chromium browser behavior, ttest for runner changes, and ctest-mcp for agent tools; broaden to other affected engines after the focused check. Tests and CI in this report were inspected, not executed.
- Use root build/lint scripts when execution is authorized, but do not assume a watcher is running; tsconfig uses strict checking and excludes generated lib directories, extension code, and tool skills from its package compilation scope.
- Treat storage edits as coordinated client, dispatcher, server, and injected-script changes; preserve optional collection flags, initial/API/reuse branches, intercepted navigation, and page/interceptor cleanup.
- Keep tests hermetic and cross-platform, inspect fixme/skip and CI trigger conditions before describing coverage, and follow the documented linked-issue/approval policy before submitting upstream contributions.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 1386 | 85% |
| HTML | 310 | docs/config |
| Markdown | 279 | docs/config |
| JavaScript | 181 | 11% |
| CSS | 94 | docs/config |
| JSON | 70 | docs/config |
| YAML | 60 | docs/config |
| Shell | 34 | 2% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1065 files)
Repository structure
| Top-level path | Files |
|---|---|
tests/ | 1094 |
packages/ | 1065 |
docs/ | 181 |
browser_patches/ | 95 |
utils/ | 83 |
examples/ | 71 |
.github/ | 38 |
.claude/ | 16 |
Docs found: CLAUDE.mdCONTRIBUTING.mdREADME.mddocs/src/accessibility-testing-java.mddocs/src/accessibility-testing-js.mddocs/src/actionability.mddocs/src/api-testing-csharp.mddocs/src/api-testing-java.mddocs/src/api-testing-js.mddocs/src/api-testing-python.md
Package
package.json — playwright-internal v1.64.0-next, 80 declared dependencies.
@actions/core@actions/github@babel/code-frame@babel/core@babel/helper-plugin-utils@babel/parser@babel/plugin-proposal-decorators@babel/plugin-syntax-async-generators@babel/plugin-syntax-import-attributes@babel/plugin-syntax-json-strings@babel/plugin-syntax-object-rest-spread@babel/plugin-syntax-optional-catch-binding
CI & config entrypoints
README.md— Repository readmeCLAUDE.md— Claude instructionstests/extension/playwright.config.ts— Playwright e2e configtests/playwright-test/playwright.config.ts— Playwright e2e configtests/webview/playwright.config.ts— Playwright e2e configtests/bidi/playwright.config.ts— Playwright e2e configtests/library/playwright.config.ts— Playwright e2e configtests/mcp/playwright.config.ts— Playwright e2e configtests/installation/playwright.config.ts— Playwright e2e configtests/android/playwright.config.ts— Playwright e2e config
Structural health signals
Average score 6.3/10 across 96 analyzed source files; 58 hotspots surfaced.
browser_patches/firefox/juggler/NetworkObserver.js— 1103 lines, score 4.5 (Large file, Deep nesting)browser_patches/firefox/juggler/TargetRegistry.js— 1345 lines, score 4.7 (Large file, Deep nesting)packages/playwright-core/src/server/fetch.ts— 927 lines, score 4.7 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
b630e71fcda72026-10-01 — feat(api): add APIRequestContext.cookies and clearCookies (#43052)e54293a3280f2026-10-01 — fix(blob): do not remove existing reports from output dir (#43056)3cf9b39ba1972026-10-01 — feat(locator): add page.getByRef (#43055)45b43ff3581d2026-10-01 — Revert "feat(test-runner): read last failed tests from --last-failed=<file>" (#43053)c603e4a1f6522026-10-01 — chore: start v8 profiler from bootstrap via PW_PROFILE_DIR (#43054)