# pexip/playwright architecture

> Architecture diagram of the GitHub repository pexip/playwright, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pexip/playwright
- Repository: https://github.com/pexip/playwright

## Overview

#### Purpose and distribution
Playwright is a Node.js/TypeScript browser-automation platform: a common API and test runner drive Chromium, Firefox, and WebKit, with CLI, MCP/agent, component-testing, trace, and reporting surfaces. Published package facades expose CommonJS/ESM/types and install hooks from `packages/playwright/package.json`, `packages/playwright-core/package.json`, and browser-specific packages such as `packages/playwright-chromium/package.json`.

#### Primary entry points
Library consumers import `playwright` or `playwright-core`; package entry shims resolve into the core client/server implementation. User-facing commands enter through `packages/playwright/cli.js` and `packages/playwright-core/cli.js`. Test commands are assembled in `packages/playwright/src/program.ts` and `packages/playwright/src/cli/testActions.ts`; core CLI installation/browser actions live in `packages/playwright-core/src/cli/program.ts`. MCP starts from `packages/playwright-core/src/entry/mcp.ts` and `packages/playwright-core/src/tools/mcp/program.ts`.

#### Client, protocol, and server boundary
The public client API models browsers, contexts, pages, locators, network, artifacts, and tracing in `packages/playwright-core/src/client/playwright.ts`, `packages/playwright-core/src/client/page.ts`, and `packages/playwright-core/src/client/locator.ts`. Calls cross a channel-based object protocol: generated/spec-defined contracts are rooted in `packages/protocol/spec/playwright.yml`, validated/serialized in `packages/playwright-core/src/protocol/validator.ts`, and bridged by server dispatchers such as `packages/playwright-core/src/server/dispatchers/playwrightDispatcher.ts`. This boundary permits in-process operation plus remote pipe/WebSocket transports.

#### Browser lifecycle and engine adapters
The server owns browser launch, context isolation, page/frame state, instrumentation, downloads, screenshots, video, and network routing. Core orchestration is in `packages/playwright-core/src/server/playwright.ts`, `packages/playwright-core/src/server/browserType.ts`, and `packages/playwright-core/src/server/browserContext.ts`. Engine-specific adapters translate the shared model to Chromium CDP, Firefox’s Juggler protocol, and WebKit protocol: `packages/playwright-core/src/server/chromium/crBrowser.ts`, `packages/playwright-core/src/server/firefox/ffBrowser.ts`, and `packages/playwright-core/src/server/webkit/wkBrowser.ts`. Browser acquisition/version registry is separate in `packages/playwright-core/src/server/registry/index.ts`.

#### Page-resident automation
A bundled injected script runs inside controlled pages to implement selector evaluation, locator generation, actionability support, accessibility snapshots, recorder behavior, and WebAuthn/mock capabilities. Key sources are `packages/injected/src/injectedScript.ts`, `packages/injected/src/selectorEvaluator.ts`, and `packages/injected/src/ariaSnapshot.ts`. This is a strict execution boundary: Node-side server code requests behavior, while DOM traversal and element resolution execute in the browser realm.

#### Test runner pipeline
`@playwright/test` layers configuration, project expansion, discovery/transformation, worker scheduling, fixtures, retries, assertions, and reporters over the library. Configuration/loading begins at `packages/playwright/src/common/configLoader.ts`; scheduling and child-process control are in `packages/playwright/src/runner/testRunner.ts` and `packages/playwright/src/runner/workerHost.ts`; test execution/fixtures run in `packages/playwright/src/worker/workerMain.ts` and `packages/playwright/src/worker/fixtureRunner.ts`. Results flow through reporter implementations, including blob and HTML formats, in `packages/playwright/src/reporters/blob.ts` and `packages/playwright/src/reporters/html.ts`.

#### Artifacts and interactive tooling
Tracing records server-side actions and snapshots, then emits trace artifacts consumed by shared trace models and browser UIs: `packages/playwright-core/src/server/trace/recorder/tracing.ts`, `packages/isomorphic/trace/traceModel.ts`, and `packages/trace-viewer/src/ui/workbench.tsx`. Recorder/codegen uses `packages/playwright-core/src/server/recorder/recorderApp.ts` with the React frontend in `packages/recorder/src/recorder.tsx`. Agent-facing MCP tools translate structured requests into browser sessions via `packages/playwright-core/src/tools/mcp/browserFactory.ts` and `packages/playwright-core/src/tools/backend/tools.ts`; the dashboard provides live session control through `packages/dashboard/src/dashboard.tsx`.

#### Runtimes, native dependencies, and infrastructure
The dominant runtime is Node.js with TypeScript/JavaScript; interactive viewers/dashboard are Vite/React applications. Browser execution depends on downloaded Chromium, Firefox, and WebKit binaries and OS-native dependencies; Firefox/WebKit include maintained upstream patches under `browser_patches/firefox/juggler` and `browser_patches/webkit`. Android support includes an ADB-facing server and Gradle-built driver at `packages/playwright-core/src/server/android/android.ts` and `packages/playwright-core/src/server/android/driver`. CI publishes npm, Docker, and extension artifacts through workflows including `.github/workflows/publish_release.yml`, `.github/workflows/publish_release_docker.yml`, and `.github/workflows/publish_extension.yml`.

Main entry points: [`packages/playwright-core/src/server/playwright.ts`](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/playwright.ts) (Browser orchestration), [`packages/playwright-core/src/client/playwright.ts`](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/client/playwright.ts) (Public client API), [`packages/playwright/src/runner/testRunner.ts`](https://github.com/pexip/playwright/blob/main/packages/playwright/src/runner/testRunner.ts) (Runner scheduler), [`packages/playwright-core/src/tools/mcp/browserFactory.ts`](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserFactory.ts) (MCP browser tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Package & command entry points"]
  node_packages["Published package facades<br/>npm packages<br/>[package.json]"]
  node_cli["CLI commands<br/>Node CLI<br/>[cli.js]"]
  node_test_cli["Test command assembly<br/>test CLI<br/>[program.ts]"]
  node_core_cli["Browser install CLI<br/>core CLI<br/>[program.ts]"]
  node_mcp_entry["MCP server<br/>agent entry<br/>[mcp.ts]"]
end

subgraph group_core["Automation core"]
  node_client["Public client API<br/>TypeScript client<br/>[playwright.ts]"]
  node_protocol["Channel protocol<br/>object protocol<br/>[playwright.yml]"]
  node_dispatchers["Server dispatchers<br/>protocol bridge"]
  node_server["Browser orchestration<br/>server runtime<br/>[playwright.ts]"]
  node_engines["Engine adapters<br/>browser protocols<br/>[crBrowser.ts]"]
  node_browsers{{"Browser binaries"}}
  node_registry["Browser registry<br/>browser acquisition<br/>[index.ts]"]
  node_injected["Injected page script<br/>browser-realm runtime<br/>[injectedScript.ts]"]
end

subgraph group_test["Test runner"]
  node_config["Config &amp; discovery<br/>test loading<br/>[configLoader.ts]"]
  node_runner["Runner scheduler<br/>test orchestration<br/>[testRunner.ts]"]
  node_worker["Test workers &amp; fixtures<br/>child-process execution<br/>[workerMain.ts]"]
  node_reporters["Reporters<br/>result output<br/>[html.ts]"]
end

subgraph group_tools["Artifacts &amp; interactive tools"]
  node_tracing["Tracing recorder<br/>trace producer<br/>[tracing.ts]"]
  node_trace_viewer["Trace Viewer<br/>React UI<br/>[workbench.tsx]"]
  node_recorder["Recorder &amp; codegen<br/>interactive tooling<br/>[recorderApp.ts]"]
  node_mcp_tools["MCP browser tools<br/>agent tool backend<br/>[browserFactory.ts]"]
  node_dashboard["Session dashboard<br/>React UI<br/>[dashboard.tsx]"]
end

node_packages -->|"exports"| node_client
node_cli -->|"test commands"| node_test_cli
node_cli -->|"browser commands"| node_core_cli
node_test_cli -->|"loads"| node_config
node_core_cli -->|"installs"| node_registry
node_mcp_entry -->|"serves"| node_mcp_tools
node_client -->|"channel calls"| node_protocol
node_protocol -->|"validated messages"| node_dispatchers
node_dispatchers -->|"controls"| node_server
node_server -->|"drives"| node_engines
node_engines -->|"protocol transport"| node_browsers
node_registry -->|"downloads and resolves"| node_browsers
node_server -->|"requests page-realm actions"| node_injected
node_config -->|"projects and tests"| node_runner
node_runner -->|"spawns"| node_worker
node_worker -->|"uses automation API"| node_client
node_runner -->|"results"| node_reporters
node_server -->|"records actions and snapshots"| node_tracing
node_tracing -->|"trace artifacts"| node_trace_viewer
node_server -->|"captures interactions"| node_recorder
node_mcp_tools -->|"creates sessions"| node_client
node_dashboard -->|"live session control"| node_mcp_tools

click node_packages "https://github.com/pexip/playwright/blob/main/packages/playwright/package.json"
click node_cli "https://github.com/pexip/playwright/blob/main/packages/playwright/cli.js"
click node_test_cli "https://github.com/pexip/playwright/blob/main/packages/playwright/src/program.ts"
click node_core_cli "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/cli/program.ts"
click node_mcp_entry "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/entry/mcp.ts"
click node_client "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/client/playwright.ts"
click node_protocol "https://github.com/pexip/playwright/blob/main/packages/protocol/spec/playwright.yml"
click node_dispatchers "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/dispatchers/playwrightDispatcher.ts"
click node_server "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/playwright.ts"
click node_engines "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/chromium/crBrowser.ts"
click node_registry "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/registry/index.ts"
click node_injected "https://github.com/pexip/playwright/blob/main/packages/injected/src/injectedScript.ts"
click node_config "https://github.com/pexip/playwright/blob/main/packages/playwright/src/common/configLoader.ts"
click node_runner "https://github.com/pexip/playwright/blob/main/packages/playwright/src/runner/testRunner.ts"
click node_worker "https://github.com/pexip/playwright/blob/main/packages/playwright/src/worker/workerMain.ts"
click node_reporters "https://github.com/pexip/playwright/blob/main/packages/playwright/src/reporters/html.ts"
click node_tracing "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/trace/recorder/tracing.ts"
click node_trace_viewer "https://github.com/pexip/playwright/blob/main/packages/trace-viewer/src/ui/workbench.tsx"
click node_recorder "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/recorder/recorderApp.ts"
click node_mcp_tools "https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserFactory.ts"
click node_dashboard "https://github.com/pexip/playwright/blob/main/packages/dashboard/src/dashboard.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_packages,node_cli,node_test_cli,node_core_cli,node_mcp_entry toneBlue
class node_client,node_protocol,node_dispatchers,node_server,node_engines,node_browsers,node_registry,node_injected toneAmber
class node_config,node_runner,node_worker,node_reporters toneMint
class node_tracing,node_trace_viewer,node_recorder,node_mcp_tools,node_dashboard toneRose
```

## Components

### Package & command entry points

- [Published package facades](https://github.com/pexip/playwright/blob/main/packages/playwright/package.json): npm packages · Expose CJS, ESM, types, and install hooks. · `packages/playwright/package.json`
- [CLI commands](https://github.com/pexip/playwright/blob/main/packages/playwright/cli.js): Node CLI · `packages/playwright/cli.js`
- [Test command assembly](https://github.com/pexip/playwright/blob/main/packages/playwright/src/program.ts): test CLI · `packages/playwright/src/program.ts`
- [Browser install CLI](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/cli/program.ts): core CLI · `packages/playwright-core/src/cli/program.ts`
- [MCP server](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/entry/mcp.ts): agent entry · `packages/playwright-core/src/entry/mcp.ts`

### Automation core

- [Public client API](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/client/playwright.ts): TypeScript client · Browser, context, page, locator, network, artifacts, and tracing APIs. · `packages/playwright-core/src/client/playwright.ts`
- [Channel protocol](https://github.com/pexip/playwright/blob/main/packages/protocol/spec/playwright.yml): object protocol · Spec-defined contracts are validated and serialized across the client/server boundary. · `packages/protocol/spec/playwright.yml`
- [Server dispatchers](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/dispatchers/playwrightDispatcher.ts): protocol bridge · `packages/playwright-core/src/server/dispatchers/playwrightDispatcher.ts`
- [Browser orchestration](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/playwright.ts): server runtime · Owns launch, contexts, pages, routing, downloads, video, and screenshots. · `packages/playwright-core/src/server/playwright.ts`
- [Engine adapters](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/chromium/crBrowser.ts): browser protocols · Maps the shared browser model to CDP, Juggler, and WebKit protocols. · `packages/playwright-core/src/server/chromium/crBrowser.ts`
- **Browser binaries**: Chromium / Firefox / WebKit · Downloaded engines with OS-native dependencies.
- [Browser registry](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/registry/index.ts): browser acquisition · `packages/playwright-core/src/server/registry/index.ts`
- [Injected page script](https://github.com/pexip/playwright/blob/main/packages/injected/src/injectedScript.ts): browser-realm runtime · Executes selector evaluation, actionability, accessibility, recorder, and mocks in pages. · `packages/injected/src/injectedScript.ts`

### Test runner

- [Config & discovery](https://github.com/pexip/playwright/blob/main/packages/playwright/src/common/configLoader.ts): test loading · `packages/playwright/src/common/configLoader.ts`
- [Runner scheduler](https://github.com/pexip/playwright/blob/main/packages/playwright/src/runner/testRunner.ts): test orchestration · Schedules projects, retries, and worker processes. · `packages/playwright/src/runner/testRunner.ts`
- [Test workers & fixtures](https://github.com/pexip/playwright/blob/main/packages/playwright/src/worker/workerMain.ts): child-process execution · `packages/playwright/src/worker/workerMain.ts`
- [Reporters](https://github.com/pexip/playwright/blob/main/packages/playwright/src/reporters/html.ts): result output · Produces blob and HTML result formats. · `packages/playwright/src/reporters/html.ts`

### Artifacts & interactive tools

- [Tracing recorder](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/trace/recorder/tracing.ts): trace producer · `packages/playwright-core/src/server/trace/recorder/tracing.ts`
- [Trace Viewer](https://github.com/pexip/playwright/blob/main/packages/trace-viewer/src/ui/workbench.tsx): React UI · `packages/trace-viewer/src/ui/workbench.tsx`
- [Recorder & codegen](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/server/recorder/recorderApp.ts): interactive tooling · `packages/playwright-core/src/server/recorder/recorderApp.ts`
- [MCP browser tools](https://github.com/pexip/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserFactory.ts): agent tool backend · Turns structured agent requests into browser sessions. · `packages/playwright-core/src/tools/mcp/browserFactory.ts`
- [Session dashboard](https://github.com/pexip/playwright/blob/main/packages/dashboard/src/dashboard.tsx): React UI · Provides live session control. · `packages/dashboard/src/dashboard.tsx`

## Connections

- Published package facades → Public client API: exports
- CLI commands → Test command assembly: test commands
- CLI commands → Browser install CLI: browser commands
- Test command assembly → Config & discovery: loads
- Browser install CLI → Browser registry: installs
- MCP server → MCP browser tools: serves
- Public client API → Channel protocol: channel calls
- Channel protocol → Server dispatchers: validated messages
- Server dispatchers → Browser orchestration: controls
- Browser orchestration → Engine adapters: drives
- Engine adapters → Browser binaries: protocol transport
- Browser registry → Browser binaries: downloads and resolves
- Browser orchestration → Injected page script: requests page-realm actions
- Config & discovery → Runner scheduler: projects and tests
- Runner scheduler → Test workers & fixtures: spawns
- Test workers & fixtures → Public client API: uses automation API
- Runner scheduler → Reporters: results
- Browser orchestration → Tracing recorder: records actions and snapshots
- Tracing recorder → Trace Viewer: trace artifacts
- Browser orchestration → Recorder & codegen: captures interactions
- MCP browser tools → Public client API: creates sessions
- Session dashboard → MCP browser tools: live session control