-- eval "document.body.outerHTML"
# Export attachments
npx playwright trace attachments
npx playwright trace attachment 1 -o out.png
```
### 6.3 Typical Investigation Workflow
```bash
# 1. Open the trace
npx playwright trace open test-results/my-test/trace.zip
# 2. View all actions
npx playwright trace actions
# 3. Find failed actions
npx playwright trace actions --errors-only
# 4. Inspect specific action
npx playwright trace action 12
# 5. View page state at that moment
npx playwright trace snapshot 12
# 6. Query DOM for details
npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent"
# 7. Check network failures
npx playwright trace requests --failed
# 8. Check console errors
npx playwright trace console --errors-only
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)
### 6.4 Trace Viewer UI Components
The trace viewer web application includes:
| Component | File | Purpose |
|-----------|------|---------|
| WorkbenchLoader | `workbenchLoader.tsx` | Main application entry, handles file uploads and drag-drop |
| BrowserFrame | `browserFrame.tsx` | Renders browser chrome with address bar |
| MetadataView | `metadataView.tsx` | Displays test metadata (viewport, user agent, baseURL) |
| TestCaseView | `testCaseView.tsx` | Shows individual test case details and results |
The workbench loader provides a progressive web app experience with local-only processing:
```typescript
Playwright Trace Viewer is a Progressive Web App, it does not send your trace anywhere,
it opens it locally.
```
资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/workbenchLoader.tsx)
## 7. Key Features Summary
| Feature | Description |
|---------|-------------|
| **Cross-browser** | Chromium, Firefox, WebKit support with single API |
| **Auto-waiting** | Actions wait for elements to be actionable |
| **Web-first assertions** | Built-in assertion library |
| **Tracing** | Comprehensive action tracing and debugging |
| **Locators** | Multiple strategies: CSS, ARIA, text, role |
| **Network interception** | Mock and modify network requests |
| **Storage state** | Save/restore authentication and cookies |
| **CLI tools** | Interactive browser automation shell |
## 8. Architecture Diagram: End-to-End Test Flow
```mermaid
sequenceDiagram
participant T as Test
participant R as Playwright Runner
participant C as CLI Client
participant P as Browser
participant TV as Trace Viewer
T->>R: npx playwright test
R->>P: Launch browser
R->>P: Inject script
T->>C: playwright-cli attach
Note over C,P: Interactive debugging
P->>TV: Generate trace.zip
TV->>T: Analyze failures
```
## 9. Resources and Further Reading
- Main Documentation: Playwright CLI capabilities and commands
- Test Debugging: Debug mode and CLI attachment workflow
- Trace Analysis: Using trace viewer for post-mortem analysis
- Session Management: Multi-browser concurrent testing patterns
- Storage State: Authentication and state persistence patterns
---
## Package Ecosystem and Monorepo Structure
### 相关页面
相关主题：[Playwright Introduction and Project Overview](#page-1), [Client-Server Communication Architecture](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/microsoft/playwright/blob/main/package.json)
- [packages/playwright-core/src/client/connection.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/connection.ts)
- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)
- [packages/injected/src/consoleApi.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/consoleApi.ts)
- [packages/playwright-browser-webkit/package.json](https://github.com/microsoft/playwright/blob/main/packages/playwright-browser-webkit/package.json)
- [packages/trace-viewer/src/ui/workbenchLoader.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/workbenchLoader.tsx)
- [examples/todomvc/package.json](https://github.com/microsoft/playwright/blob/main/examples/todomvc/package.json)
# Package Ecosystem and Monorepo Structure
Playwright is organized as a monorepo using npm workspaces, enabling centralized version management and shared tooling across multiple specialized packages. The repository contains the main `playwright` package alongside browser-specific packages, core libraries, and supporting tools.
## Repository Overview
The Playwright monorepo follows a multi-package architecture where:
- The root `package.json` defines shared scripts, build tooling, and workspace configuration
- Individual packages under `packages/` contain focused, modular functionality
- Examples under `examples/` demonstrate real-world usage patterns
```mermaid
graph TD
Root[Root package.json
v1.61.0-next] --> Core[playwright-core]
Root --> Main[playwright]
Root --> Chromium[playwright-browser-chromium]
Root --> Firefox[playwright-browser-firefox]
Root --> Webkit[playwright-browser-webkit]
Root --> Injected[injected]
Root --> TraceViewer[trace-viewer]
Root --> HtmlReporter[html-reporter]
Core --> Injected
Main --> Core
Chromium --> Core
Firefox --> Core
Webkit --> Core
```
## Core Packages
### playwright
The main public package that provides the high-level API for browser automation. It re-exports types and utilities from `playwright-core` while bundling browser automation capabilities.
### playwright-core
The foundational package containing all browser automation logic. This package:
- Defines client-side abstractions (`Page`, `Request`, `Response`, `Route`, `WebSocket`, `Worker`)
- Manages channel-based communication between client and server
- Implements the `LocalUtils` factory for shared utilities
The connection layer registers object factories for all domain objects:
```typescript
registerObjectFactories({
LocalUtils: (parent, type, guid, init) => {
const result = new LocalUtils(parent, type, guid, init);
if (!this._localUtils)
this._localUtils = result;
return result;
},
Page: (parent, type, guid, init) => new Page(parent, type, guid, init),
Request: (parent, type, guid, init) => new Request(parent, type, guid, init),
Response: (parent, type, guid, init) => new Response(parent, type, guid, init),
Route: (parent, type, guid, init) => new Route(parent, type, guid, init),
Tracing: (parent, type, guid, init) => new Tracing(parent, type, guid, init),
WebSocket: (parent, type, guid, init) => new WebSocket(parent, type, guid, init),
Worker: (parent, type, guid, init) => new Worker(parent, type, guid, init),
});
```
资料来源：[packages/playwright-core/src/client/connection.ts:10-35]()
## Browser Packages
Browser-specific packages provide automatic browser installation and management. Each package depends on `playwright-core`.
| Package | Purpose | Dependencies |
|---------|---------|--------------|
| `playwright-browser-chromium` | Chromium browser support | playwright-core |
| `playwright-browser-firefox` | Firefox browser support | playwright-core |
| `playwright-browser-webkit` | WebKit browser support | playwright-core |
The browser packages expose a standard interface:
```json
{
"name": "@playwright/browser-webkit",
"version": "1.61.0-next",
"exports": {
".": {
"types": "./index.d.ts",
"import": "./index.mjs",
"require": "./index.js",
"default": "./index.js"
}
},
"dependencies": {
"playwright-core": "1.61.0-next"
}
}
```
资料来源：[packages/playwright-browser-webkit/package.json]()
## Injected Scripts Package
The `injected` package contains scripts that run within the browser context, providing accessibility utilities and developer inspection capabilities.
### Console API Installation
The injected script installs a `playwright` object onto `window` when `install()` is called:
```typescript
install() {
if (this._injectedScript.window.playwright)
return;
this._injectedScript.window.playwright = {
$: (selector: string, strict?: boolean) => this._querySelector(selector, !!strict),
$$: (selector: string) => this._querySelectorAll(selector),
inspect: (selector: string) => this._inspect(selector),
selector: (element: Element) => this._selector(element),
generateLocator: (element: Element, language?: Language) => this._generateLocator(element, language),
ariaSnapshot: (element?: Element, options?: AriaTreeOptions) => {
return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options || { mode: 'default' });
},
resume: () => this._resume(),
...new Locator(this._injectedScript, ''),
};
}
```
资料来源：[packages/injected/src/consoleApi.ts:10-30]()
### Role Utilities
The `roleUtils.ts` file maps HTML elements to their ARIA roles for accessibility testing:
```typescript
'DIALOG': () => 'dialog',
'FORM': (e: Element) => hasExplicitAccessibleName(e) ? 'form' : null,
'HEADER': (e: Element) => closestCrossShadow(e, kAncestorPreventingLandmark) ? null : 'banner',
'IMG': (e: Element) => (e.getAttribute('alt') === '') && !e.getAttribute('title') && !hasGlobalAriaAttribute(e) && !hasTabIndex(e) ? 'presentation' : 'img',
```
资料来源：[packages/injected/src/roleUtils.ts:1-50]()
## Tooling Packages
### trace-viewer
A React-based Progressive Web Application for inspecting Playwright trace files. The trace viewer provides:
- Drop-zone interface for loading trace files locally
- Progress dialogs for trace processing
- Version display showing the Playwright version
- No data transmission—opens files locally
```tsx
Playwright Trace Viewer is a Progressive Web App, it does not send your trace anywhere,
it opens it locally.
Playwright v{__APP_VERSION__}
```
资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx:1-30]()
### html-reporter
Generates HTML test reports with:
- Test case location linking
- Duration tracking
- Project and tag labeling
- Annotation display
- Retry labeling for failed tests
```tsx
{test.location.file}:{test.location.line}
{msToString(test.duration)}
```
资料来源：[packages/html-reporter/src/testCaseView.tsx:1-30]()
## CLI Tools
### playwright-cli
A command-line tool for browser automation and page interaction. Available commands include:
```bash
# Core commands
playwright-cli open # Open browser
playwright-cli goto # Navigate
playwright-cli click # Click element
playwright-cli type # Type text
# Snapshot and evaluation
playwright-cli snapshot # Get page snapshot
playwright-cli eval "code" # Execute JS
# Tab management
playwright-cli tab-list # List tabs
playwright-cli tab-new # New tab
# State management
playwright-cli state-save # Save state
playwright-cli state-load # Load state
# Network interception
playwright-cli route "" # Intercept routes
```
### playwright-trace
Inspect trace files from the command line:
```bash
npx playwright trace open # Open and extract trace
npx playwright trace actions # List all actions
npx playwright trace action # View action details
npx playwright trace console # View console messages
npx playwright trace errors # View errors
npx playwright trace snapshot # View DOM snapshot
npx playwright trace close # Close trace
```
## Build and Test Scripts
The root `package.json` defines comprehensive test and lint scripts:
| Script | Purpose |
|--------|---------|
| `ctest` | Chromium tests |
| `ftest` | Firefox tests |
| `wtest` | WebKit tests |
| `atest` | Android tests |
| `etest` | Electron tests |
| `itest` | Installation tests |
| `stest` | Stress tests |
| `biditest` | BiDi protocol tests |
| `ttest` | Playwright Test runner tests |
| `lint` | Full linting suite |
| `tsc` | TypeScript compilation |
```json
{
"scripts": {
"ctest": "playwright test --config=tests/library/playwright.config.ts --project=chromium-*",
"ftest": "playwright test --config=tests/library/playwright.config.ts --project=firefox-*",
"wtest": "playwright test --config=tests/library/playwright.config.ts --project=webkit-*",
"test": "playwright test --config=tests/library/playwright.config.ts",
"eslint": "eslint --cache",
"tsc": "tsc -p ."
}
}
```
资料来源：[package.json:1-50]()
## Monorepo Structure Summary
```mermaid
graph TD
subgraph "Root"
RootPkg[package.json
v1.61.0-next]
end
subgraph "Core Packages"
Core[playwright-core
Automation core]
Injected[injected
Browser scripts]
end
subgraph "Public Packages"
Main[playwright
Main API]
Chromium[playwright-browser-chromium]
Firefox[playwright-browser-firefox]
Webkit[playwright-browser-webkit]
end
subgraph "Tooling"
CLI[playwright-cli
CLI tool]
Trace[playwright-trace
Trace CLI]
Viewer[trace-viewer
Trace PWA]
Reporter[html-reporter
Test reports]
end
subgraph "Examples"
Todo[todomvc]
Svgomg[svgomg]
end
Main --> Core
Chromium --> Core
Firefox --> Core
Webkit --> Core
CLI --> Core
Trace --> Core
Viewer --> Core
Reporter --> Core
Core --> Injected
```
## Package Versioning
All packages in the monorepo share the same version number for consistency:
```json
{
"version": "1.61.0-next",
"engines": {
"node": ">=18"
}
}
```
Browser packages declare explicit dependencies on `playwright-core`:
```json
"dependencies": {
"playwright-core": "1.61.0-next"
}
```
This ensures version alignment across the ecosystem while allowing independent releases when necessary.
---
## Client-Server Communication Architecture
### 相关页面
相关主题：[Package Ecosystem and Monorepo Structure](#page-2), [Browser Launch and Process Management](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/client/channelOwner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/channelOwner.ts)
- [packages/playwright-core/src/client/connection.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/connection.ts)
- [packages/playwright-core/src/server/dispatchers/dispatcher.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/dispatchers/dispatcher.ts)
- [packages/playwright-core/src/remote/playwrightConnection.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/remote/playwrightConnection.ts)
- [packages/protocol/src/channels.d.ts](https://github.com/microsoft/playwright/blob/main/packages/protocol/src/channels.d.ts)
- [packages/playwright-core/src/client/playwright.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/playwright.ts)
- [packages/playwright-core/src/client/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/page.ts)
# Client-Server Communication Architecture
## Overview
Playwright's Client-Server Communication Architecture enables the automation of web browsers through a well-defined message-passing system. The architecture separates the client API (used by test developers) from the server-side browser automation engine, allowing tests to control Chromium, Firefox, and WebKit browsers running either locally or in remote environments.
## High-Level Architecture
```mermaid
graph TD
subgraph Client["Client Side (Node.js)"]
API[Test API
playwright.click()]
CO[ChannelOwner
Base Class]
CONN[Connection]
end
subgraph Server["Server Side (Node.js + Browser)"]
DIS[Dispatcher]
CH[Channel Handlers]
BR[Browser
Chromium/Firefox/WebKit]
end
API --> CO
CO --> CONN
CONN -->|Protocol Messages| DIS
DIS --> CH
CH --> BR
style Client fill:#e1f5fe
style Server fill:#fff3e0
```
The architecture follows a factory pattern where the `Connection` class registers object factories for all protocol-defined objects. When the client creates a `Page` or `BrowserContext`, the corresponding factory is invoked to create a client-side proxy object.
## Core Components
### ChannelOwner (Client-Side Base Class)
The `ChannelOwner` class serves as the base for all client-side objects that communicate with the server. It provides:
- **Message routing**: Sends commands to the server and receives responses
- **Event handling**: Subscribes to server-side events
- **Lifecycle management**: Tracks object disposal and cleanup
| Property | Type | Description |
|----------|------|-------------|
| `channel` | `Channel` | The communication channel to the server |
| `connection` | `Connection` | Reference to the parent connection |
| `guid` | `string` | Unique identifier for this object |
| `parent` | `ChannelOwner \| null` | Parent object in the hierarchy |
资料来源：[packages/playwright-core/src/client/channelOwner.ts]()
### Connection (Client-Side Hub)
The `Connection` class manages all client-server communication and object lifecycle.
```typescript
// Connection registers factories for all protocol objects
registerObjectFactories(factories: Record) {
// Creates appropriate client-side objects for each type
}
```
**Registered Object Factories:**
| Object Type | Factory Creates | Purpose |
|-------------|-----------------|---------|
| `Browser` | Browser instance | Main browser process |
| `BrowserContext` | Context instance | Isolated browsing sessions |
| `Page` | Page instance | Single tab/page |
| `Request` | Request instance | HTTP request tracking |
| `Response` | Response instance | HTTP response data |
| `Route` | Route instance | Network request interception |
| `Tracing` | Tracing instance | Trace collection |
| `WebSocket` | WebSocket instance | WebSocket communication |
| `Worker` | Worker instance | Web Workers |
| `LocalUtils` | Utility instance | Local utility functions |
资料来源：[packages/playwright-core/src/client/connection.ts:1-50]()
### Dispatcher (Server-Side Handler)
The `Dispatcher` class is the server-side counterpart that handles messages from clients.
```mermaid
graph LR
MSG[Incoming
Message] --> DIS[Dispatcher]
DIS -->|Route| HAND[Channel Handler]
HAND -->|Execute| BR[Browser API]
BR -->|Result| RES[Response
to Client]
```
Key responsibilities:
- Deserialize incoming messages
- Route to appropriate channel handler
- Execute browser automation commands
- Send responses back to client
资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts]()
### Protocol Channels
The protocol defines typed channels for all communication between client and server.
```typescript
// Generated from protocol definitions
interface Channels {
Browser: {
// Methods
newContext(options?: BrowserNewContextOptions): Promise;
close(): Promise;
// Events
on('disconnected', callback: () => void): void;
};
Page: {
click(selector: string, options?: PageClickOptions): Promise;
fill(selector: string, value: string): Promise;
// ...
};
}
```
资料来源：[packages/protocol/src/channels.d.ts]()
## Communication Flow
### Method Invocation Flow
```mermaid
sequenceDiagram
participant Client as Test Code
participant CO as ChannelOwner
participant CONN as Connection
participant Wire as Wire Protocol
participant DIS as Dispatcher
participant Impl as Implementation
Client->>CO: page.click('#button')
CO->>CONN: sendMessage('click', args)
CONN->>Wire: serialize & send
Wire->>DIS: deliver message
DIS->>Impl: invoke method
Impl-->>DIS: return result
DIS-->>Wire: send response
Wire-->>CONN: receive response
CONN-->>CO: deserialize result
CO-->>Client: Promise resolves
```
### Object Creation Flow
When a client requests a new object (e.g., `browser.newContext()`):
1. Server creates the implementation object
2. Server creates a dispatcher wrapper
3. Server returns the new object's channel reference to client
4. Client's connection factory creates appropriate `ChannelOwner` subclass
5. Client receives a proxy object to interact with the new object
```mermaid
graph TD
subgraph Server["Server"]
IMPL[Implementation]
DISP[Dispatcher]
end
subgraph Client["Client"]
FACT[Factory]
PROXY[ChannelOwner Proxy]
end
IMPL -->|creates| DISP
DISP -->|returns guid| FACT
FACT -->|creates| PROXY
```
## Remote Connections
Playwright supports remote browser connections through `PlaywrightConnection`.
```mermaid
graph TD
subgraph Local["Test Machine"]
TEST[Test Code]
CLIENT[Local Client]
end
subgraph Remote["Remote Machine"]
SERVER[Playwright Server]
BROWSER[Browser]
end
TEST --> CLIENT
CLIENT -->|WebSocket| SERVER
SERVER --> BROWSER
```
The remote connection maintains the same channel-based communication but uses WebSocket transport instead of in-process communication.
资料来源：[packages/playwright-core/src/remote/playwrightConnection.ts]()
## Message Protocol
### Message Structure
```typescript
interface ProtocolMessage {
id: string; // Unique message ID
guid: string; // Target object GUID
method: string; // Method name
params?: object; // Method parameters
type: 'request' | 'response' | 'event';
}
```
### Event Subscription
Clients subscribe to server-side events through the channel system:
```typescript
// Server emits event
dispatcher.dispatchEvent('eventName', payload);
// Client receives via callback
page.on('close', () => {
console.log('Page closed');
});
```
## Object Hierarchy
```mermaid
graph TD
P[Playwright] --> BC[Browser]
BC --> BCT[BrowserContext]
BCT --> PGE[Page]
PGE --> W[Worker]
PGE --> R[Route]
BCT --> RS[Request]
BCT --> RS2[Response]
style P fill:#c8e6c9
style BC fill:#fff9c4
style BCT fill:#bbdefb
style PGE fill:#ffccbc
```
All objects inherit from `ChannelOwner` and maintain references to their parent connection.
## Error Handling
The architecture handles errors through:
1. **Sync errors**: Caught and returned as rejected promises
2. **Async errors**: Propagated through the message response
3. **Disconnection**: Server sends 'disconnected' event to notify clients
```typescript
try {
await page.click('#missing');
} catch (e) {
// Error contains reason and stack
console.log(e.message); // Target closed, did you mean to close the browser?
}
```
## Key Design Patterns
### Factory Pattern
Object factories in `Connection` create the appropriate `ChannelOwner` subclass based on protocol type.
### Proxy Pattern
`ChannelOwner` instances are proxies that forward method calls to the server.
### Observer Pattern
Event subscriptions allow clients to react to server-side state changes.
### Promise-based Async
All operations return Promises, enabling async/await usage in tests.
## Summary
Playwright's Client-Server Communication Architecture provides:
- **Type safety**: Protocol definitions ensure consistent interfaces
- **Location transparency**: Local and remote execution use the same API
- **Extensibility**: New object types can be added to the protocol
- **Performance**: Optimized message serialization and batching
- **Debuggability**: Clear message flow between components
---
## Browser Launch and Process Management
### 相关页面
相关主题：[Client-Server Communication Architecture](#page-3), [Browser Implementations and Protocol Support](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/outofprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/outofprocess.ts)
- [packages/playwright-core/src/inprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/inprocess.ts)
- [packages/playwright-core/src/server/browserType.ts](https://github.com/microsoft/playicrosoft/playwright/blob/main/packages/playwright-core/src/server/browserType.ts)
- [packages/playwright-core/src/server/browser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browser.ts)
- [packages/utils/processLauncher.ts](https://github.com/microsoft/playwright/blob/main/packages/utils/processLauncher.ts)
- [packages/playwright-core/src/server/transport.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/transport.ts)
# Browser Launch and Process Management
## Overview
Browser Launch and Process Management is a core subsystem in Playwright responsible for spawning, communicating with, and lifecycle-managing browser processes. This subsystem abstracts the complexity of launching different browser types (Chromium, Firefox, WebKit) across different environments, handling both in-process and out-of-process execution models while maintaining reliable communication channels.
The system provides:
- **Cross-browser abstraction** - Unified API for launching Chromium, Firefox, and WebKit
- **Process lifecycle management** - Spawning, health monitoring, graceful termination
- **Dual execution modes** - In-process and out-of-process browser execution
- **Transport layer abstraction** - Message-based IPC between Node.js and browser processes
- **Resource cleanup** - Proper disposal of browser instances and associated resources
资料来源：[packages/playwright-core/src/server/browserType.ts:1-50]()
## Architecture
### High-Level Components
```mermaid
graph TD
A[Playwright Client API] --> B[BrowserType]
B --> C{Launch Mode}
C -->|Out-of-Process| D[OutOfProcess]
C -->|In-Process| E[InProcess]
D --> F[ProcessLauncher]
D --> G[Transport Layer]
E --> H[BrowserProcess]
F --> I[Browser Executable]
G --> J[Browser Server]
H --> I
```
### Core Component Roles
| Component | Package | Responsibility |
|-----------|---------|----------------|
| `BrowserType` | `playwright-core` | Entry point for browser launching, delegates to appropriate implementation |
| `OutOfProcess` | `playwright-core` | Manages out-of-process browser execution with separate server process |
| `InProcess` | `playwright-core` | Manages in-process browser execution within Node.js |
| `ProcessLauncher` | `utils` | Core process spawning and management utilities |
| `Transport` | `playwright-core` | Message-based IPC communication layer |
| `Browser` | `playwright-core` | Abstract browser base class with lifecycle management |
资料来源：[packages/playwright-core/src/server/browserType.ts:1-100]()
## Launch Modes
Playwright supports two distinct browser launch modes, each suited for different use cases.
### Out-of-Process Mode
The out-of-process (OOP) mode spawns browser processes as separate OS processes, with communication handled via WebSocket or pipe-based transport layers.
**Characteristics:**
- Process isolation - Browser crashes do not affect the Node.js process
- Cross-language support - Enables Playwright bindings in languages other than Node.js
- Resource efficiency - Better for running multiple browser instances
- Security - Browser runs in separate sandboxed process
```mermaid
graph LR
A[Node.js Process] <-->|WebSocket/Pipes| B[Browser Server Process]
B --> C[Browser Executable]
```
The `OutOfProcess` class handles:
1. Spawning the browser server executable
2. Establishing transport connection
3. Handshake and version negotiation
4. Proxying API calls to the browser
资料来源：[packages/playwright-core/src/outofprocess.ts:1-80]()
### In-Process Mode
The in-process mode runs browser execution within the Node.js process itself, useful for scenarios requiring tighter integration.
**Characteristics:**
- Direct execution - No inter-process communication overhead
- Debugging simplicity - Easier to debug browser and client code together
- Shared memory - Direct access to browser resources
- Limited isolation - Browser crashes may affect Node.js process
The `InProcess` class provides a simplified launch path that instantiates browser internals directly without spawning separate processes.
资料来源：[packages/playwright-core/src/inprocess.ts:1-60]()
### Mode Selection
```typescript
// Out-of-process (default)
const browser = await chromium.launch({ headless: true });
// In-process via browser type's `launchServer`
const server = await chromium.launchServer({ headless: true });
```
## Process Lifecycle
### Launch Sequence
```mermaid
sequenceDiagram
participant Client
participant BrowserType
participant Launcher
participant Browser
participant Transport
Client->>BrowserType: launch(options)
BrowserType->>Launcher: spawn(executable, args)
Launcher->>Browser: new Browser(transport)
Browser->>Transport: connect()
Transport-->>Browser: connection established
Browser->>Browser: initialize()
Browser-->>BrowserType: ready
BrowserType-->>Client: Browser instance
```
### Lifecycle States
| State | Description | Transitions |
|-------|-------------|-------------|
| `Launching` | Process is being spawned | → `Connected` or `Failed` |
| `Connected` | Transport layer established | → `Initialized` or `Closed` |
| `Initialized` | Browser fully ready | → `Closed` |
| `Failed` | Launch or initialization failed | Terminal state |
| `Closed` | Browser process terminated | Terminal state |
资料来源：[packages/playwright-core/src/server/browser.ts:1-150]()
### Termination
Browser termination follows a controlled shutdown sequence:
1. **Graceful close request** - Send close command to browser
2. **Resource cleanup** - Dispose contexts, pages, and handlers
3. **Process termination** - Kill the browser executable if still running
4. **Transport cleanup** - Close connections and cleanup pipes
```mermaid
graph TD
A[Browser.close called] --> B{Force kill?}
B -->|No| C[Graceful shutdown]
B -->|Yes| D[Kill process]
C --> E[Wait for exit]
E --> F[Force kill if timeout]
D --> G[Cleanup resources]
F --> G
G --> H[Done]
```
## Transport Layer
The transport layer enables message-based communication between the Node.js client and browser process.
### Message Protocol
Messages follow a structured format with JSON-serialized headers and binary payloads:
```
┌─────────────────────────────────────────┐
│ Message Header (JSON) │
│ { id, method, params, binaryLength } │
├─────────────────────────────────────────┤
│ Binary Payload (if binaryLength > 0) │
└─────────────────────────────────────────┘
```
### Transport Implementations
| Type | Use Case | Package |
|------|----------|---------|
| `PipeTransport` | Local Windows processes | `playwright-core` |
| `StdioTransport` | Unix domain sockets | `playwright-core` |
| `WebSocketTransport` | Remote/cloud browsers | `playwright-core` |
资料来源：[packages/playwright-core/src/server/transport.ts:1-100]()
### Connection Establishment
```typescript
class Transport {
constructor(connection: Connection) {
this._connection = connection;
}
async connect(pipe: Pipe): Promise {
// Establish connection to browser process
}
send(message: ProtocolMessage): void {
// Serialize and send message
}
async close(): Promise {
// Graceful transport shutdown
}
}
```
## Process Launcher
The `ProcessLauncher` utility provides cross-platform process spawning and management.
### Launch Options
| Option | Type | Description |
|--------|------|-------------|
| `executablePath` | `string` | Path to browser executable |
| `args` | `string[]` | Command-line arguments |
| `env` | `Record` | Environment variables |
| `cwd` | `string` | Working directory |
| `stdio` | `'pipe' \| 'inherit'` | Standard IO mode |
| `detach` | `boolean` | Run in detached mode |
| `timeout` | `number` | Launch timeout in ms |
资料来源：[packages/utils/processLauncher.ts:1-120]()
### Process Monitoring
The launcher maintains process health through:
1. **Exit detection** - Monitoring for unexpected process termination
2. **Output capture** - Collecting stdout/stderr for debugging
3. **Resource limits** - Optional memory and CPU limits
4. **Cleanup hooks** - Automatic resource disposal on exit
### Error Handling
```typescript
interface LaunchError {
reason: 'executable-not-found' | 'timeout' | 'crash' | 'protocol-error';
message: string;
stack?: string;
}
```
## Browser Type Registry
Each browser type (Chromium, Firefox, WebKit) extends the base `BrowserType` class with browser-specific logic.
### Browser Executable Resolution
```mermaid
graph TD
A[launch called] --> B{Find browser?}
B -->|User path| C[Validate executable]
B -->|Default| D[Check installed browsers]
C -->|Valid| E[Launch browser]
C -->|Invalid| F[Throw error]
D -->|Found| E
D -->|Not found| G[Prompt installation]
```
### BrowserType Interface
```typescript
interface BrowserType {
name(): string;
executablePath(): string;
launch(options?: LaunchOptions): Promise;
launchServer(options?: LaunchOptions): Promise;
launchPersistentContext(userDataDir: string, options?: LaunchOptions): Promise;
executable(): string;
defaultArgs(options?: LaunchOptions): string[];
}
```
资料来源：[packages/playwright-core/src/server/browserType.ts:100-200]()
## Configuration Options
### Common Launch Options
| Option | Default | Description |
|--------|---------|-------------|
| `headless` | `true` | Run browser in headless mode |
| `args` | `[]` | Additional browser arguments |
| `channel` | `undefined` | Browser channel (e.g., 'chrome', 'msedge') |
| `chromiumSandbox` | `true` | Enable Chromium sandbox (Linux) |
| `devtools` | `false` | Open DevTools on launch |
| `downloadPath` | `undefined` | Custom download directory |
| `env` | `process.env` | Environment variables |
| `executablePath` | `undefined` | Custom browser executable path |
| `firefoxUserPrefs` | `{}` | Firefox-specific preferences |
| `proxy` | `undefined` | Proxy configuration |
| `timeout` | `30000` | Launch timeout in milliseconds |
| `viewport` | `{ width: 1280, height: 720 }` | Default viewport size |
### Browser-Specific Options
#### Chromium
| Option | Type | Description |
|--------|------|-------------|
| `chromiumSandbox` | `boolean` | Enable Linux sandbox |
| `proxy` | `ProxySettings` | HTTP/SOCKS proxy |
| `downloadContentTypes` | `string[]` | Content types to download |
#### Firefox
| Option | Type | Description |
|--------|------|-------------|
| `firefoxUserPrefs` | `Record` | Gecko preferences |
| `firefoxExtensionPaths` | `string[]` | Extension directories |
#### WebKit
| Option | Type | Description |
|--------|------|-------------|
| `wkWebKitExperimentalSimulateSaturation` | `boolean` | Simulate saturation |
| `wkWebKitExperimentalLayoutMetrics` | `boolean` | Enable layout metrics |
## Integration with CLI Tools
The browser launch system integrates with Playwright's CLI tooling for interactive browser automation.
### CLI Session Management
```bash
# Open browser with named session
playwright-cli -s=mysession open https://example.com
# Create persistent profile
playwright-cli open https://example.com --persistent
# Browser selection
playwright-cli open https://example.com --browser=firefox
```
The CLI layer uses the same `BrowserType` APIs to establish browser sessions, with session state managed through the browser's context persistence mechanisms.
## Best Practices
### Resource Management
1. **Always close browsers** - Use `browser.close()` in try/finally blocks
2. **Handle launch failures** - Wrap launch calls in try/catch for graceful error handling
3. **Use context isolation** - Launch separate contexts instead of separate browsers when possible
4. **Set appropriate timeouts** - Adjust timeouts for slow environments
### Launch Example
```typescript
import { chromium } from 'playwright';
async function run() {
let browser;
try {
browser = await chromium.launch({
headless: true,
timeout: 30000,
args: ['--disable-gpu', '--no-sandbox'],
});
const context = await browser.newContext();
const page = await context.newPage();
// Perform actions...
} catch (error) {
console.error('Browser launch failed:', error);
} finally {
if (browser) {
await browser.close();
}
}
}
```
## Summary
The Browser Launch and Process Management system provides a robust foundation for browser automation in Playwright. By abstracting the complexities of process spawning, inter-process communication, and lifecycle management, it enables developers to work with browsers through a clean, consistent API regardless of the underlying browser type or execution environment.
Key takeaways:
- **Dual execution modes** support both isolated (OOP) and integrated (in-process) browser execution
- **Transport abstraction** enables reliable message passing across different IPC mechanisms
- **Lifecycle management** ensures proper resource cleanup and graceful degradation
- **Browser type registry** provides consistent APIs across Chromium, Firefox, and WebKit
---
## Test Runner and Execution Engine
### 相关页面
相关主题：[Playwright Introduction and Project Overview](#page-1), [Locators, Selectors, and Element Interaction](#page-6), [Assertions, Matchers, and Expect API](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright/src/runner/testRunner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/testRunner.ts)
- [packages/playwright/src/runner/dispatcher.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/dispatcher.ts)
- [packages/playwright/src/common/testLoader.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/testLoader.ts)
- [packages/playwright/src/common/fixtures.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/fixtures.ts)
- [packages/playwright/src/common/poolBuilder.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/poolBuilder.ts)
- [packages/playwright/src/runner/workerHost.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/workerHost.ts)
- [packages/playwright/src/worker/workerMain.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/worker/workerMain.ts)
# Test Runner and Execution Engine
The Playwright Test Runner is the core execution engine responsible for discovering, scheduling, and running end-to-end tests across multiple browsers and processes. It provides a complete test isolation model, automatic retry logic, parallel execution, and seamless integration with fixtures for test setup and teardown.
## Architecture Overview
The test runner follows a multi-process architecture designed for scalability and isolation. At a high level, it consists of a central **TestRunner** process that coordinates test execution, multiple **Worker** processes that execute tests in isolated browser contexts, and a **Dispatcher** that manages the assignment of tests to available workers.
```mermaid
graph TD
A[TestRunner
Main Process] --> B[Dispatcher
Test Assignment]
B --> C[Worker Host 1
Process]
B --> D[Worker Host 2
Process]
B --> E[Worker Host N
Process]
C --> F[Browser Context 1]
D --> G[Browser Context 2]
E --> H[Browser Context N]
F --> I[Page 1]
G --> J[Page 2]
H --> K[Page N]
```
### Core Components
| Component | File Location | Responsibility |
|-----------|---------------|----------------|
| TestRunner | `packages/playwright/src/runner/testRunner.ts` | Entry point; orchestrates the full test run lifecycle |
| Dispatcher | `packages/playwright/src/runner/dispatcher.ts` | Distributes tests to workers and tracks completion |
| TestLoader | `packages/playwright/src/common/testLoader.ts` | Discovers and parses test files |
| Fixtures | `packages/playwright/src/common/fixtures.ts` | Manages test fixtures and dependencies |
| PoolBuilder | `packages/playwright/src/common/poolBuilder.ts` | Creates and manages browser context pools |
| WorkerHost | `packages/playwright/src/runner/workerHost.ts` | Manages worker process lifecycle |
| WorkerMain | `packages/playwright/src/worker/workerMain.ts` | Worker process entry point; runs actual tests |
资料来源：[packages/playwright/src/runner/testRunner.ts:1-50]()
资料来源：[packages/playwright/src/runner/dispatcher.ts:1-60]()
## Test Discovery and Loading
The test discovery process begins with the **TestLoader**, which recursively scans the project for test files matching the configured patterns. Playwright supports both `.spec.ts` and `.spec.js` file extensions by default, though these patterns are fully configurable through `playwright.config.ts`.
### Loading Pipeline
```mermaid
graph LR
A[Test Files
*.spec.ts] --> B[TestLoader]
B --> C[Parse Test Cases]
C --> D[Extract Fixtures]
D --> E[Build Test Tree]
E --> F[Dispatcher]
```
The TestLoader performs the following operations:
1. **File Discovery** — Scans the specified test directory for files matching the glob patterns defined in the configuration.
2. **Syntax Parsing** — Parses each test file to extract `test`, `test.describe`, and `test.beforeEach` declarations.
3. **Fixture Extraction** — Identifies fixture dependencies declared via `test.use()` or fixture function signatures.
4. **Test Tree Construction** — Builds a hierarchical structure representing test suites and individual test cases.
资料来源：[packages/playwright/src/common/testLoader.ts:1-80]()
### Configuration Files
Playwright recognizes two primary configuration file formats:
| File | Format | Priority |
|------|--------|----------|
| `playwright.config.ts` | TypeScript | Highest |
| `playwright.config.js` | JavaScript | Lower |
| `playwright.config.mjs` | ES Module | Lower |
The configuration defines critical execution parameters including:
```typescript
// Example playwright.config.ts structure
export default defineConfig({
timeout: 30000, // Per-test timeout in milliseconds
retries: 0, // Number of retries on failure
workers: process.env.CI ? 1 : undefined, // Parallel workers
reporter: 'html', // Output format
use: {
baseURL: 'http://localhost',
headless: true,
viewport: { width: 1280, height: 720 },
ignoreHTTPSErrors: false,
},
projects: [
{ name: 'chromium', use: { browserName: 'chromium' } },
{ name: 'firefox', use: { browserName: 'firefox' } },
{ name: 'webkit', use: { browserName: 'webkit' } },
],
});
```
资料来源：[package.json:test-scripts]()
资料来源：[README.md:test-configuration]()
## Worker Process Model
Each worker process operates as an independent execution unit, running in a separate Node.js process for complete isolation. The **WorkerHost** manages the lifecycle of these processes, handling creation, communication, and graceful termination.
### Worker Lifecycle
```mermaid
stateDiagram-v2
[*] --> Spawning: Start Worker
Spawning --> Initializing: Worker PID obtained
Initializing --> Ready: Fixtures initialized
Ready --> Running: Test assigned
Running --> Ready: Test complete
Running --> Retrying: Test failed, retries remaining
Retrying --> Running: Retry attempt
Retrying --> Failed: No retries left
Running --> Failed: Test failed, no retries
Ready --> Shutdown: All tests complete
Failed --> [*]: Worker terminated
Shutdown --> [*]: Cleanup complete
```
### Worker Communication
Workers communicate with the main process through an IPC (Inter-Process Communication) channel. The protocol supports the following message types:
| Message Type | Direction | Purpose |
|--------------|-----------|---------|
| `init` | Main → Worker | Initialize worker with config |
| `run` | Main → Worker | Execute a specific test |
| `stop` | Main → Worker | Cancel running test |
| `done` | Worker → Main | Report test result |
| `error` | Worker → Main | Report runtime error |
| `teardown` | Main → Worker | Graceful shutdown |
资料来源：[packages/playwright/src/runner/workerHost.ts:1-100]()
资料来源：[packages/playwright/src/worker/workerMain.ts:1-50]()
## Dispatcher and Test Assignment
The **Dispatcher** is the central coordinator responsible for assigning tests to available workers while respecting configured parallelism limits. It maintains a queue of pending tests and dynamically allocates them based on worker availability.
### Test Assignment Algorithm
```mermaid
graph TD
A[Test Queue] --> B{Workers Available?}
B -->|Yes| C[Pop Next Test]
C --> D{Test has deps?}
D -->|No| E[Assign to available worker]
D -->|Yes| F[Wait for deps]
F --> D
E --> G[Execute Test]
G --> H[Test Result]
H --> I{Success?}
I -->|Yes| J[Mark complete]
I -->|No| K{Retries left?}
K -->|Yes| L[Re-queue for retry]
K -->|No| M[Mark failed]
J --> A
L --> A
M --> A
```
The dispatcher implements the following strategies:
- **Load Balancing** — Tests are distributed evenly across workers to maximize throughput.
- **Retry Logic** — Failed tests are automatically re-queued up to the configured retry count.
- **Serial Execution per Worker** — Each worker processes one test at a time to maintain isolation.
- **Sharding** — Tests can be sharded across multiple machines using `--shard` flag.
资料来源：[packages/playwright/src/runner/dispatcher.ts:50-200]()
### Parallelism Configuration
| Config Option | CLI Flag | Description |
|---------------|----------|-------------|
| `workers` | `--workers` | Number of parallel worker processes |
| `retries` | `--retries` | Number of retry attempts per failed test |
| `timeout` | `--timeout` | Per-test timeout in milliseconds |
| `shard` | `--shard=N/M` | Shard tests across M machines, run shard N |
```bash
# Run with 4 workers
npx playwright test --workers=4
# Run with retries and extended timeout
npx playwright test --retries=2 --timeout=60000
# Run shard 1 of 3
npx playwright test --shard=1/3
```
## Fixture System
Fixtures provide a dependency injection mechanism for test setup and teardown. They ensure that resources are properly initialized before tests run and cleaned up afterward.
### Fixture Types
| Type | Scope | Usage |
|------|-------|-------|
| `static` | Across all tests | Global configuration |
| `worker` | Per worker process | Shared within one worker |
| `test` | Per test execution | Fresh for each test |
| `session` | Across all workers | Shared global state |
```typescript
import { test as baseTest, expect } from '@playwright/test';
// Define a fixture with automatic cleanup
export const test = baseTest.extend({
// Auto-cleanup database for each test
database: async ({}, use) => {
const db = await createTestDatabase();
await use(db);
await db.cleanup();
},
// Reuse authenticated page across all tests in a worker
authenticatedPage: async ({ browser }, use) => {
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('/login');
await page.fill('#username', 'testuser');
await page.fill('#password', 'testpass');
await page.click('#submit');
await use(page);
await context.close();
},
});
```
资料来源：[packages/playwright/src/common/fixtures.ts:1-100]()
### Built-in Fixtures
Playwright provides several built-in fixtures that are automatically available to all tests:
| Fixture | Type | Description |
|---------|------|-------------|
| `page` | `test` | Fresh page for each test |
| `context` | `test` | Fresh browser context |
| `browser` | `worker` | Browser instance shared in worker |
| `request` | `test` | APIRequestContext for REST testing |
| `火` | `test` | Playwright test object |
## Browser Context Pooling
The **PoolBuilder** manages a pool of browser contexts to optimize resource usage. Rather than creating a new context for each test (which can be expensive), the pool maintains a set of reusable contexts.
### Pooling Strategy
```mermaid
graph TD
A[Test Request] --> B{Idle Context Available?}
B -->|Yes| C[Use Pooled Context]
B -->|No| D{Max Pool Size Reached?}
D -->|No| E[Create New Context]
D -->|Yes| F[Wait for Available]
E --> C
F --> C
C --> G[Test Execution]
G --> H{Context Satisfies Test?}
H -->|Yes| I[Return to Pool]
H -->|No| J[Destroy Context]
J --> K[Create Fresh Context]
K --> I
```
### Context Configuration
Each project can define its own context configuration:
```typescript
export default defineConfig({
projects: [
{
name: 'chromium',
use: {
browserName: 'chromium',
viewport: { width: 1920, height: 1080 },
permissions: ['geolocation'],
storageState: './auth.json',
launchOptions: {
args: ['--disable-dev-shm-usage'],
},
},
},
],
});
```
资料来源：[packages/playwright/src/common/poolBuilder.ts:1-80]()
## Debug Mode and CLI Integration
Playwright provides a CLI-based debugging mode that allows interactive inspection of test execution. When running with `--debug=cli`, the test runner pauses at the start and exposes a debug session.
### Debug Workflow
```mermaid
graph TD
A[npx playwright test --debug=cli] --> B[Test Paused at Start]
B --> C[Debugging Instructions
Session: tw-XXXX]
C --> D[playwright-cli attach tw-XXXX]
D --> E[Interactive Commands]
E --> F[snapshot, click, fill, etc.]
F --> G[Test Continues]
G --> H[Capture Results]
H --> I[Generate Report]
```
### Debug Commands
| Command | Purpose |
|---------|---------|
| `playwright-cli snapshot` | Get current page snapshot with element refs |
| `playwright-cli click [` | Click an element by its reference |
| `playwright-cli fill ][ ` | Fill input field |
| `playwright-cli eval ` | Execute JavaScript in page context |
| `playwright-cli resume` | Continue test execution |
| `playwright-cli screenshot` | Capture current page state |
```bash
# Start test in debug mode
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
# In another terminal, attach to the debug session
playwright-cli attach tw-abcdef
# Explore the page
playwright-cli snapshot
playwright-cli click e15
playwright-cli eval "document.title"
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md:1-50]()
## Tracing and Debugging
Playwright includes a comprehensive tracing system that captures detailed execution information for post-mortem analysis.
### Trace Contents
| Category | Captured Data |
|----------|---------------|
| **Actions** | Clicks, fills, navigations with timestamps |
| **DOM Snapshots** | Before/after state for each action |
| **Screenshots** | Visual state at key moments |
| **Network** | All HTTP requests/responses |
| **Console** | Console.log output and errors |
| **Errors** | Stack traces for failures |
### Trace Commands
```bash
# Open a trace file
npx playwright trace open trace.zip
# List all actions
npx playwright trace actions
# View specific action details
npx playwright trace action
# Get DOM snapshot at an action
npx playwright trace snapshot
# View console errors
npx playwright trace console --errors-only
```
```mermaid
graph LR
A[Test Execution] --> B[trace-{timestamp}.trace]
A --> C[trace-{timestamp}.network]
A --> D[resources/]
B --> E[Action Log]
C --> F[Network Activity]
D --> G[Cached Assets]
E --> H[Trace Viewer]
F --> H
G --> H
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md:1-80]()
## Execution Flow Summary
The complete test execution flow follows these stages:
```mermaid
sequenceDiagram
participant User
participant TestRunner
participant TestLoader
participant Dispatcher
participant WorkerHost
participant Worker
User->>TestRunner: npx playwright test
TestRunner->>TestLoader: Load tests
TestLoader-->>TestRunner: Test tree
TestRunner->>Dispatcher: Initialize
TestRunner->>WorkerHost: Spawn workers
WorkerHost->>Worker: Start process
loop For each test
Dispatcher->>WorkerHost: Assign test
WorkerHost->>Worker: Run test
Worker->>PoolBuilder: Request context
PoolBuilder-->>Worker: Context
Worker->>Fixtures: Setup fixtures
Fixtures-->>Worker: Fixture values
Worker->>Worker: Execute test body
Worker->>Fixtures: Teardown fixtures
Worker-->>WorkerHost: Test result
WorkerHost-->>Dispatcher: Result
end
Dispatcher-->>TestRunner: All complete
TestRunner->>User: Report
```
## Command-Line Interface
### Common Commands
| Command | Description |
|---------|-------------|
| `npx playwright test` | Run all tests |
| `npx playwright test ` | Run specific file |
| `npx playwright test --debug` | Run in debug mode |
| `npx playwright test --list` | List all tests without running |
| `npx playwright show-report` | Open HTML report |
### Configuration via CLI
```bash
# Override config values
npx playwright test --project=chromium --timeout=30000
# Run only matching tests
npx playwright test --grep="login"
# Run only failed tests from last run
npx playwright test --last-failed
# Update snapshots
npx playwright test --update-snapshots
```
## Integration with Trace Viewer
The trace viewer is a Progressive Web App that opens trace files locally without sending data anywhere. It provides visual debugging capabilities.
```mermaid
graph TD
A[Trace.zip] --> B[WorkbenchLoader]
B --> C[TraceModel]
C --> D[Actions Panel]
C --> E[Screenshots Panel]
C --> F[Network Panel]
C --> G[Console Panel]
D --> H[Unified Timeline]
E --> H
F --> H
G --> H
```
To use the trace viewer:
1. Run a test that generates a trace (using `trace: 'on'` in config)
2. Locate the trace file in `test-results//trace.zip`
3. Open at [trace.playwright.dev](https://trace.playwright.dev) or via CLI
资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx:1-60]()
## Summary
The Playwright Test Runner provides a production-grade testing infrastructure with:
- **Multi-process isolation** ensuring test independence
- **Automatic resource management** through fixture cleanup
- **Flexible parallelism** configurable per project and CI environment
- **Rich debugging** via CLI integration and trace playback
- **Cross-browser support** executing tests on Chromium, Firefox, and WebKit
- **Comprehensive reporting** with built-in HTML reports and trace viewer
The architecture cleanly separates concerns between test discovery (TestLoader), orchestration (Dispatcher), execution (Workers), and resource management (Fixtures, PoolBuilder), making it both maintainable and extensible.
---
## Locators, Selectors, and Element Interaction
### 相关页面
相关主题：[Test Runner and Execution Engine](#page-5), [Assertions, Matchers, and Expect API](#page-7)
]
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)
- [packages/injected/src/selectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEngine.ts)
- [packages/injected/src/selectorGenerator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorGenerator.ts)
- [packages/injected/src/roleSelectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleSelectorEngine.ts)
- [packages/injected/src/selectorEvaluator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEvaluator.ts)
- [packages/injected/src/injectedScript.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/injectedScript.ts)
- [packages/playwright-core/src/server/selectors.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/selectors.ts)
# Locators, Selectors, and Element Interaction
This page describes how Playwright locates DOM elements and interacts with them programmatically. The system consists of client-side Locator APIs, an in-browser Injected Script that evaluates selectors, and a server-side Selector Manager that registers and manages selector engines.
## Architecture Overview
Playwright uses a layered architecture for element location:
| Layer | Package | Responsibility |
|-------|---------|----------------|
| **Client API** | `playwright-core/src/client/locator.ts` | Fluent locator interface exposed to test authors |
| **Server Manager** | `playwright-core/src/server/selectors.ts` | Registers selector engines, manages context |
| **Injected Script** | `packages/injected/src/` | Runs in browser context, evaluates selectors |
```mermaid
graph TD
A[Test Author Code] --> B[Locator API]
B --> C[Selector Manager]
C --> D[Registered Selector Engines]
D --> E[Injected Script]
E --> F[Browser DOM]
B -->|locator.click/hover/fill| G[Action Commands]
E -->|querySelector, querySelectorAll| F
```
资料来源：[packages/playwright-core/src/client/locator.ts](packages/playwright-core/src/client/locator.ts)
资料来源：[packages/playwright-core/src/server/selectors.ts](packages/playwright-core/src/server/selectors.ts)
## Locator API
The `Locator` class provides a fluent API for finding and interacting with elements. It differs from `ElementHandle` by using *strict* mode by default and automatically retrying until elements are actionable.
### Core Locator Methods
| Method | Description |
|--------|-------------|
| `click()` | Click the element |
| `fill()` | Fill input field with text |
| `hover()` | Hover over element |
| `dblclick()` | Double-click element |
| `check()` / `uncheck()` | Toggle checkbox/radio |
| `selectOption()` | Select option(s) from dropdown |
| `scrollIntoViewIfNeeded()` | Scroll element into view |
| `tap()` | Perform tap gesture |
| `dragAndDrop()` | Drag and drop operations |
### Locator vs ElementHandle
| Aspect | Locator | ElementHandle |
|--------|---------|---------------|
| Evaluation | Re-evaluated on each action | Captured once |
| Strict mode | Enabled by default | Must be manually enforced |
| Retries | Auto-retries until actionable | Single attempt |
| Shadow DOM | Traverses automatically | Manual shadow traversal |
The injected script exposes locator helpers via `window.playwright`:
```typescript
this._injectedScript.window.playwright = {
$: (selector: string, strict?: boolean) => this._querySelector(selector, !!strict),
$$: (selector: string) => this._querySelectorAll(selector),
inspect: (selector: string) => this._inspect(selector),
selector: (element: Element) => this._selector(element),
generateLocator: (element: Element, language?: Language) => this._generateLocator(element, language),
ariaSnapshot: (element?: Element, options?: AriaTreeOptions) => { ... },
resume: () => this._resume(),
...new Locator(this._injectedScript, ''),
};
```
资料来源：[packages/injected/src/consoleApi.ts:1-30](packages/injected/src/consoleApi.ts)
## Selector Engine Architecture
Playwright supports multiple built-in selector engines that can be combined using the `>>` combinator.
### Selector Engine Types
| Engine | Prefix | Example | Description |
|--------|--------|---------|-------------|
| **CSS** | (default) | `div.button` | Standard CSS selectors |
| **Role** | `role/` | `role=button[name="Submit"]` | ARIA role matching |
| **Text** | `text/` | `text="Log In"` | Text content matching |
| **Test ID** | `testId=` | `testId=submit-btn` | `data-testid` attribute |
| **Label** | `label=` | `label=Username` | Form label association |
| **Alt Text** | `alt=` | `alt=Profile Photo` | Image alt attributes |
| **Title** | `title=` | `title=Settings` | Title attribute |
| **XPath** | `xpath=` | `xpath=//button[1]` | XPath expressions |
| **Regex** | `/regex/` | `/^submit.*$/i` | Pattern matching |
### Selector Evaluation Flow
```mermaid
graph LR
A[Selector String] --> B[Parse & Split by >>]
B --> C[Engine Registry Lookup]
C --> D{Engine Type?}
D -->|CSS| E[query/queryAll]
D -->|Role| F[Role Selector Engine]
D -->|Text| G[Text Selector Engine]
D -->|Other| H[Custom Engine]
E --> I[Evaluate in DOM]
F --> I
G --> I
H --> I
I --> J[Match Results]
```
### Engine Registration
Selector engines are registered with the `SelectorEngine` class:
```typescript
type SelectorEngine = {
name: string;
create?(root: Preview, target: Element, context: SelectorInjectedContext): Selector;
query(root: Element, selector: Selector): Element | null;
queryAll?(root: Element, selector: Selector): Element[];
};
```
资料来源：[packages/injected/src/selectorEngine.ts](packages/injected/src/selectorEngine.ts)
## Role Selector Engine
The role selector engine matches elements by their ARIA role with optional name and properties filters.
### Supported ARIA Roles
The engine recognizes all standard ARIA roles including: `button`, `link`, `checkbox`, `radio`, `textbox`, `searchbox`, `combobox`, `listbox`, `menu`, `menuitem`, `tab`, `tablist`, `dialog`, `alertdialog`, and many more.
### Role Selector Syntax
```bash
role=button[name="Submit"]
role=link[name="Documentation"]
role=textbox[name="Email"][include-hidden]
role=menuitemcheckbox[name="Bold"][checked]
```
### Role Matching Logic
```mermaid
graph TD
A[Input: role=button] --> B[Get all elements with role=button]
B --> C{has name filter?}
C -->|Yes| D[Filter by accessible name]
C -->|No| E[Return all matches]
D --> F{Matches found?}
F -->|Yes| E
F -->|No| G[Return empty]
E --> H[Apply other filters]
```
资料来源：[packages/injected/src/roleSelectorEngine.ts](packages/injected/src/roleSelectorEngine.ts)
## Selector Evaluator
The `SelectorEvaluator` class performs actual DOM matching using registered engines.
### Key Methods
| Method | Signature | Purpose |
|--------|-----------|---------|
| `query` | `(selector: ParsedSelector, root: Element, strict: boolean)` | Find single element |
| `queryAll` | `(selector: ParsedSelector, root: Element)` | Find all matches |
| `parseSelector` | `(selector: string)` | Parse selector string |
| `preusable` | `()` | Create context for reuse |
### Selector Parsing
Selectors are parsed into a structured format:
```typescript
type ParsedSelector = {
parsed: {
engineName: string;
strict: boolean;
chain: {
engine: string;
selector: string;
distance: number;
shadow: ShadowRootLevel[];
}[];
};
};
```
资料来源：[packages/injected/src/selectorEvaluator.ts](packages/injected/src/selectorEvaluator.ts)
## Selector Generator
The selector generator suggests optimal selectors for elements during codegen and when using `playwright codegen`.
### Generation Strategy
| Priority | Selector Type | Example |
|----------|---------------|---------|
| 1 | Test ID | `[data-testid="submit"]` |
| 2 | Accessible | `role=button[name="Submit"]` |
| 3 | Text | `text="Submit"` |
| 4 | CSS | `#submit-btn` |
| 5 | Relative | `nth=5` |
### Generator Implementation
The generator analyzes elements and ranks candidate selectors by:
1. **Uniqueness** - Does this selector match exactly one element?
2. **Stability** - Will this selector survive UI changes?
3. **Readability** - Is this selector meaningful to humans?
4. **Brevity** - Shorter selectors preferred when equivalent
资料来源：[packages/injected/src/selectorGenerator.ts](packages/injected/src/selectorGenerator.ts)
## Injected Script Integration
The `InjectedScript` class provides the bridge between Node.js and browser contexts.
### Architecture
```mermaid
graph TD
A[Playwright Node.js] -->|Evaluate| B[InjectedScript]
B --> C[Query Selector Engines]
B --> D[Locator Generation]
B --> E[ARIA Snapshot]
B --> F[Console API]
C --> G[DOM Manipulation]
D --> H[Selector Suggestions]
E --> I[Accessibility Tree]
G --> J[User Actions]
J -->|click, hover, type| K[Event Dispatch]
```
### Console API Methods
| Method | Description |
|--------|-------------|
| `playwright.$()` | Query single element |
| `playwright.$$()` | Query all elements |
| `playwright.inspect()` | Highlight element |
| `playwright.selector()` | Generate selector for element |
| `playwright.generateLocator()` | Generate in specific language |
| `playwright.ariaSnapshot()` | Get accessibility snapshot |
资料来源：[packages/injected/src/injectedScript.ts](packages/injected/src/injectedScript.ts)
## Using Locators with playwright-cli
The CLI tool supports all selector types for element interaction:
### Element Targeting Methods
```bash
# Using snapshot refs (from playwright-cli snapshot)
playwright-cli click e15
# CSS selectors
playwright-cli click "#main > button.submit"
# Role locators
playwright-cli click "getByRole('button', { name: 'Submit' })"
# Test IDs
playwright-cli click "getByTestId('submit-button')"
```
### Interaction Commands
| Command | Description | Example |
|---------|-------------|---------|
| `click` | Click element | `playwright-cli click e5` |
| `fill` | Type into input | `playwright-cli fill e4 "hello world"` |
| `hover` | Hover over element | `playwright-cli hover e4` |
| `select` | Select dropdown option | `playwright-cli select e9 "option-value"` |
| `check/uncheck` | Toggle checkbox | `playwright-cli check e12` |
| `drag` | Drag and drop | `playwright-cli drop e4 --data="text/plain=hello"` |
| `upload` | Upload file | `playwright-cli upload ./document.pdf` |
资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md](packages/playwright-core/src/tools/cli-client/skill/SKILL.md)
## Selector Manager
The server-side `SelectorManager` handles registration and lifecycle of selector engines across browser contexts.
### Manager Responsibilities
| Responsibility | Description |
|----------------|-------------|
| Engine Registration | Register built-in and custom engines |
| Context Management | Create/destroy selector contexts |
| Session Handling | Maintain state across browser sessions |
| Channel Communication | Bridge between server and injected script |
### Custom Selector Registration
```typescript
// Register a custom selector engine
await test.selectors.register({
name: 'my-selector',
query: async (root, selector) => {
return root.querySelector(selector);
},
queryAll: async (root, selector) => {
return [...root.querySelectorAll(selector)];
}
});
```
资料来源：[packages/playwright-core/src/server/selectors.ts](packages/playwright-core/src/server/selectors.ts)
## Element Interaction Flow
```mermaid
sequenceDiagram
participant T as Test Code
participant L as Locator API
participant S as Selector Manager
participant I as Injected Script
participant B as Browser DOM
T->>L: locator.click("button")
L->>S: query("button")
S->>I: evaluate querySelector
I->>B: query DOM
B->>I: return Element
I->>S: return Element
S->>L: return Element
L->>L: waitForElement
L->>T: click complete
```
## Best Practices
### Preferred Selector Order
1. **Test IDs** (`data-testid`) — Most stable and explicit
2. **Role + Name** — Semantically meaningful and accessible
3. **Text Content** — Human-readable but may change
4. **CSS Classes/IDs** — Fast but brittle
5. **XPath** — Last resort; hard to maintain
### Anti-Patterns to Avoid
| Anti-Pattern | Problem | Alternative |
|--------------|---------|-------------|
| Index-based `nth=` | Breaks with layout changes | Use role/name filtering |
| Deep CSS paths | Fragile to DOM changes | Use semantic selectors |
| Dynamic attributes | Unstable in CI | Use stable test IDs |
| Coordinates | Resolution-dependent | Use element targets |
## Summary
Playwright's locator and selector system provides a flexible, multi-engine approach to DOM element identification:
- **Locator API** offers a fluent, retry-based interface for test authors
- **Multiple selector engines** handle CSS, ARIA roles, text, and custom selectors
- **Injected Script** enables browser-side evaluation without round-trips
- **Selector Generator** helps discover optimal selectors during development
The architecture prioritizes accessibility (role selectors), stability (test IDs), and developer experience (fluent API) while maintaining performance through optimized DOM queries.
---
## Assertions, Matchers, and Expect API
### 相关页面
相关主题：[Test Runner and Execution Engine](#page-5), [Locators, Selectors, and Element Interaction](#page-6)
Relevant Source Files
以下源码文件用于生成本页说明：
- [packages/playwright/src/matchers/expect.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/expect.ts)
- [packages/playwright/src/matchers/matchers.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/matchers.ts)
- [packages/playwright/src/matchers/toMatchSnapshot.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/toMatchSnapshot.ts)
- [packages/playwright/src/matchers/toMatchAriaSnapshot.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/toMatchAriaSnapshot.ts)
- [packages/isomorphic/expectUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/expectUtils.ts)
- [packages/isomorphic/assert.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/assert.ts)
# Assertions, Matchers, and Expect API
Playwright's assertion system provides a powerful, auto-retrying mechanism for validating application state during end-to-end testing. The `expect` API combined with matchers enables test authors to write expressive, readable assertions that automatically wait for conditions to be met rather than requiring manual polling or arbitrary timeouts.
## Overview
Playwright's assertion framework is built on three core concepts that work together to provide reliable test assertions:
| Component | Purpose |
|-----------|---------|
| **Expect API** | Core assertion function that wraps values and provides matcher methods |
| **Matchers** | Individual comparison functions that validate specific conditions |
| **Expect Utils** | Shared utility functions for handling timeouts, polling, and error messages |
The architecture follows a layered approach where the `expect` function creates an expectation object that chains matcher methods. Each matcher returns either a pass result or throws an error with detailed context about what failed.
```mermaid
graph TD
A[Test Code] --> B[expect value]
B --> C[Expectation Object]
C --> D[Matcher Methods]
D --> E{Auto-retry Loop}
E -->|condition met| F[Pass - Continue]
E -->|condition not met| G[Wait and Retry]
G --> E
E -->|timeout exceeded| H[Throw ExpectationError]
F --> I[Test Continues]
H --> J[Test Fails]
```
## Core Files and Structure
### Expect Implementation
The main `expect` function is defined in `packages/playwright/src/matchers/expect.ts`. This file exports the `expect` function and the `Expect` class that handles the retry logic and matcher invocation.
Key responsibilities:
- Creating expectation objects from actual values
- Managing auto-retry mechanisms with configurable timeouts
- Formatting error messages with expected vs. actual values
- Supporting both synchronous and asynchronous expectations
### Matchers Module
The matchers are defined in `packages/playwright/src/matchers/matchers.ts`. This file contains all built-in matcher functions that can be chained off the `expect` call.
### Isomorphic Utilities
Shared assertion utilities in `packages/isomorphic/expectUtils.ts` and `packages/isomorphic/assert.ts` provide platform-agnostic functionality used across different Playwright packages.
## Expect API Reference
### Basic Usage
```typescript
import { test, expect } from '@playwright/test';
test('login page', async ({ page }) => {
await page.goto('/login');
// Basic equality assertion
await expect(page).toHaveTitle('Login');
// Locator assertion with auto-wait
await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();
// Text content assertion
await expect(page.locator('.error')).toHaveText('Invalid credentials');
});
```
### Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timeout` | `number` | Matcher's default | Maximum time to retry the assertion |
| `message` | `string \| function` | auto-generated | Custom error message on failure |
| `containsText` | `string \| RegExp` | - | Pattern that should appear in error |
## Built-in Matchers
### Web-First Assertions
Playwright provides specialized "web-first" assertions optimized for UI testing. These assertions automatically wait for the expected state before failing.
#### Visibility and Presence
| Matcher | Description |
|---------|-------------|
| `toBeVisible()` | Element is visible and not obscured |
| `toBeHidden()` | Element is not visible |
| `toBeAttached()` | Element is present in DOM |
| `toBeEnabled()` | Element is enabled (not disabled) |
| `toBeDisabled()` | Element is disabled |
| `toBeEditable()` | Element is editable |
| `toBeFocused()` | Element has focus |
#### Content Assertions
| Matcher | Description |
|---------|-------------|
| `toHaveText(expected, options?)` | Element contains exact or partial text |
| `toContainText(expected)` | Element contains text (partial match) |
| `toHaveValue(value)` | Input element has specific value |
| `toHaveValues(values)` | Multiple select or checkbox group values |
| `toHaveTitle(title)` | Page has specific title |
| `toHaveURL(url)` | Page has specific URL |
| `toHaveScreenshot(name, options?)` | Element/page matches screenshot |
#### Form and Input Assertions
| Matcher | Description |
|---------|-------------|
| `toBeChecked()` | Checkbox or radio is checked |
| `toHaveChecked()` | Checkbox with specific state |
| `toBeSelected()` | Option is selected in select element |
| `toBeRequired()` | Input is marked as required |
| `toBeValid()` | Input passes validation constraints |
### Negation
All matchers support negation using `.not`:
```typescript
await expect(page.getByRole('button')).not.toBeDisabled();
await expect(page.locator('.loading')).not.toBeVisible();
```
## Snapshot Testing
Playwright supports snapshot testing through dedicated matchers that compare rendered output against stored baselines.
### Visual Snapshots
The `toMatchSnapshot` matcher captures and compares images:
```typescript
test('screenshot comparison', async ({ page }) => {
await page.goto('/dashboard');
await expect(page).toMatchScreenshot('dashboard.png', {
fullPage: true,
animations: 'disabled'
});
});
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | Snapshot file name |
| `options?.fullPage` | `boolean` | Capture entire scrollable page |
| `options?.animations` | `'disabled' \| 'allow'` | Animation handling |
| `options?.mask` | `locator[]` | Elements to mask in screenshot |
| `options?.threshold` | `number` | Pixel matching threshold 0-1 |
### Aria Snapshots
The `toMatchAriaSnapshot` matcher compares the semantic structure of the page:
```typescript
test('page structure', async ({ page }) => {
await page.goto('/form');
await expect(page).toMatchAriaSnapshot(`
- heading "Create Account"
- textbox "Email"
- textbox "Password"
- button "Submit"
`);
});
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `snapshot` | `string` | Expected ARIA tree structure |
| `options?.timeout` | `number` | Retry timeout in ms |
| `options?.matcher` | `string \| RegExp` | Custom snapshot matcher |
### Updating Snapshots
When UI changes are intentional, update snapshots using the CLI:
```bash
npx playwright test --update-snapshots
# or
npx playwright test -u
```
## Custom Matchers
### Defining Custom Matchers
Extend the `expect` object with custom matchers for project-specific assertions:
```typescript
// expect.d.ts or custom expect file
import { expect as baseExpect } from '@playwright/test';
export { test } from '@playwright/test';
export const expect = baseExpect.extend({
async toHaveAnalyticsEvent(
locator: Locator,
eventName: string,
options?: { timeout?: number }
) {
const timeout = options?.timeout ?? 1000;
const analyticsData: string[] = [];
const listener = (event: ConsoleMessage) => {
if (event.type() === 'log') {
analyticsData.push(event.text());
}
};
locator.page().on('console', listener);
try {
await page.waitForFunction(
(name) => window.analytics?.events?.includes(name),
eventName,
{ timeout }
);
return { pass: true };
} catch {
return {
pass: false,
message: () => `Expected analytics event "${eventName}" was not fired`,
};
} finally {
locator.page().off('console', listener);
}
},
});
```
### Using Custom Matchers
```typescript
import { expect } from './expect';
test('analytics tracking', async ({ page }) => {
await page.goto('/products');
await page.click('.buy-button');
// Uses custom matcher
await expect(page).toHaveAnalyticsEvent('purchase_initiated');
});
```
## Auto-Retry Behavior
Playwright assertions automatically retry until the condition is met or timeout expires. This eliminates flaky tests caused by timing issues.
### Retry Loop Flow
```mermaid
sequenceDiagram
participant T as Test
participant E as Expect
participant M as Matcher
participant P as Page
T->>E: expect(locator).toBeVisible()
Note over E: Create Expectation
loop Retry until timeout
E->>M: Compare current state
M->>P: Query element state
alt Condition met
M-->>E: Pass
E-->>T: Continue
else Condition not met
M-->>E: Fail
E->>E: Wait (default: 100ms)
end
end
Note over E: Timeout exceeded
E-->>T: Throw ExpectationError
```
### Timeout Configuration
```typescript
// Per-assertion timeout
await expect(page.locator('.loading')).toBeHidden({ timeout: 5000 });
// Global default timeout
// In playwright.config.ts:
export default {
expect: {
timeout: 5000,
},
};
```
### Timeout Inheritance
| Configuration Location | Value |
|------------------------|-------|
| Assertion option | `{ timeout: 3000 }` |
| `expect` config section | `5000` |
| Test fixture | Inherited |
| Default | `1000` (1 second) |
## Error Messages
Playwright generates detailed, actionable error messages when assertions fail.
### Error Message Structure
```
expect(received).toHaveText(expected)
Expected string: "Welcome, John"
Received string: "Welcome, Guest"
```
### Custom Messages
```typescript
await expect(page.locator('.balance')).toHaveText(
'$100.00',
{ message: 'Balance should reflect completed transaction' }
);
// Or use a function for dynamic messages
await expect(page.locator('.status')).toHaveText(
'Active',
{ message: () => `Expected status for user ${userId} to be Active` }
);
```
## TypeScript Integration
### Type Safety
All matchers are fully typed and provide autocomplete support:
```typescript
// TypeScript infers expected type
await expect(page.locator('input')).toHaveValue('hello');
// For complex matchers, types are enforced
await expect(page).toHaveScreenshot('button.png', {
// options type is inferred
fullPage: true,
animations: 'disabled'
});
```
### Generic Assertions
For custom assertion types, use generics:
```typescript
expect.extend({
async toHaveData属性(
this: jest.MatcherContext,
received: T,
key: string,
value: unknown
) {
const data = (received as any)[key];
return {
pass: data === value,
message: () => `Expected ${key} to be ${value}, got ${data}`,
};
},
});
```
## Best Practices
### Prefer Web-First Assertions
Always use Playwright's built-in web-first assertions over raw comparisons:
```typescript
// ❌ Fragile - no auto-wait
expect(await page.textContent('button')).toBe('Submit');
// ✅ Reliable - auto-waits and handles timing
await expect(page.getByRole('button')).toHaveText('Submit');
```
### Combine Matchers
Chain multiple matchers for comprehensive checks:
```typescript
await expect(page.getByRole('textbox', { name: 'Email' }))
.toBeVisible()
.toBeEnabled()
.toBeFocused()
.toHaveAttribute('type', 'email');
```
### Use Descriptive Names
Name expectations clearly for better test output:
```typescript
// ❌ Unclear
await expect(page.locator('.main')).toHaveScreenshot('shot.png');
// ✅ Clear intent
await expect(page).toMatchScreenshot('checkout-page-cart-items.png');
```
## Summary
The Assertions, Matchers, and Expect API form the foundation of Playwright's verification capabilities. Key takeaways:
| Aspect | Key Point |
|--------|-----------|
| **Auto-retry** | Assertions automatically wait for conditions, reducing flakiness |
| **Web-first** | Built specifically for dynamic web applications |
| **Rich matchers** | Comprehensive set of UI-specific assertions |
| **Snapshot support** | Visual and semantic snapshot testing built-in |
| **Extensibility** | Custom matchers via `expect.extend` |
| **TypeScript** | Full type safety and autocomplete support |
The system is designed to make tests reliable by default, allowing developers to focus on test logic rather than timing and synchronization concerns.
---
## Browser Implementations and Protocol Support
### 相关页面
相关主题：[Browser Launch and Process Management](#page-4), [CLI, MCP Server, and Agent Integration](#page-10)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/server/chromium/chromium.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/chromium.ts)
- [packages/playwright-core/src/server/chromium/crBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/crBrowser.ts)
- [packages/playwright-core/src/server/firefox/firefox.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/firefox/firefox.ts)
- [packages/playwright-core/src/server/firefox/ffBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/firefox/ffBrowser.ts)
- [packages/playwright-core/src/server/webkit/webkit.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/webkit/webkit.ts)
- [packages/playwright-core/src/server/webkit/wkBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/webkit/wkBrowser.ts)
- [packages/playwright-core/src/server/bidi/bidiBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/bidi/bidiBrowser.ts)
- [browser_patches/firefox/juggler](https://github.com/microsoft/playwright/blob/main/browser_patches/firefox/juggler)
# Browser Implementations and Protocol Support
## Overview
Playwright's browser implementation architecture provides a unified automation API across three major browser engines: Chromium, Firefox, and WebKit. The architecture abstracts browser-specific differences through a common interface while supporting multiple protocols for communication between the Node.js process and browser instances. This design enables developers to write browser automation code once and execute it across different browsers without modification.
The browser implementations are organized in the `packages/playwright-core/src/server/` directory, with each browser type having its own subdirectory containing browser-specific initialization, connection, and protocol handling code. This modular structure allows for independent development and maintenance of each browser's implementation while sharing common infrastructure through the core playwright-core package.
## Architecture Overview
```mermaid
graph TD
subgraph "Playwright Core API"
A[chromium.launch()] --> B[BrowserType]
C[firefox.launch()] --> B
D[webkit.launch()] --> B
end
subgraph "Protocol Layer"
B --> E[CDP Connection]
B --> F[BiDi Protocol]
end
subgraph "Browser Implementations"
E --> G[Chromium Browser]
E --> H[WebKit Browser]
F --> I[Firefox Browser]
F --> J[Chromium via BiDi]
F --> K[WebKit via BiDi]
end
subgraph "Browser Processes"
G --> L[Chromium Process]
H --> M[WebKit Process]
I --> N[Firefox + Juggler]
end
```
## Browser Package Structure
Playwright provides separate packages for each browser to optimize installation and distribution. The packages enable automatic installation of browser binaries when imported.
| Package Name | Description | Auto-Install | Main Export |
|--------------|-------------|--------------|-------------|
| `playwright-chromium` | Chromium browser support | Yes | `chromium` |
| `@playwright/browser-chromium` | Chromium browser support | Yes | `chromium` |
| `playwright` | All browsers | Yes | `chromium`, `firefox`, `webkit` |
| `playwright-core` | All browsers | No | `chromium`, `firefox`, `webkit` |
| `@playwright/browser-webkit` | WebKit browser support | Yes | `webkit` |
| `playwright-browser-webkit` | WebKit browser support | Yes | `webkit` |
Each package exports a `chromium`, `firefox`, or `webkit` object that provides the `BrowserType` interface for launching browser instances. The packages share common dependencies through `playwright-core`, which contains the actual implementation logic.
## Chromium Implementation
The Chromium implementation consists of two main components: the browser type definition and the actual browser instance management.
### Chromium Architecture
```mermaid
graph TD
A[chromium.launch()] --> B[Chromium#44;BrowserType]
B --> C[ChromiumBrowser#44;ConnectedBrowser]
C --> D[CDP Session]
C --> E[ChromiumBrowserContext]
D --> F[Chrome DevTools Protocol]
E --> G[ChromiumPage]
G --> F
```
### Browser Type (`chromium.ts`)
The Chromium browser type class extends the base `BrowserType` interface and provides the specific configuration for launching Chromium instances. This file contains:
- **Launch options**: Configuration for headless mode, viewport, user agent, and other browser settings
- **Browser binary path**: Resolution logic for finding the Chromium executable
- **Connection establishment**: Code for establishing CDP connections to the browser
- **Feature detection**: Capabilities and features specific to Chromium
### Browser Instance (`crBrowser.ts`)
The Chromium browser instance class manages the lifecycle of a connected Chromium browser. Key responsibilities include:
- **Page management**: Creating and tracking page instances
- **Context management**: Handling browser contexts for isolation
- **CDP session handling**: Managing DevTools protocol sessions
- **Process management**: Monitoring and terminating the browser process
## Firefox Implementation
Firefox requires special handling due to its architecture. Unlike Chromium and WebKit which support CDP directly, Firefox uses a patched version called Juggler.
### Firefox Architecture with Juggler
```mermaid
graph TD
A[firefox.launch()] --> B[Firefox#44;BrowserType]
B --> C[FFBrowser#44;ConnectedBrowser]
C --> D[Juggler Bridge]
D --> E[CDP to Juggler Translation]
E --> F[Firefox Browser Process]
subgraph "Browser Patches"
G[Juggler Protocol]
H[CDP Emulator]
I[Automation Hooks]
end
D --> G
G --> H
G --> I
```
### Juggler Protocol Handler
The Firefox implementation uses Juggler, a custom protocol handler that bridges Playwright's CDP-based API with Firefox's automation capabilities. The Juggler component:
- **Patches Firefox**: Modifies Firefox behavior to enable automation
- **Protocol translation**: Converts CDP commands to Firefox-specific commands
- **Event forwarding**: Streams events from Firefox back to Playwright
This architecture allows Playwright to provide a consistent API across all browsers while accommodating Firefox's different internal architecture.
### Browser Type (`firefox.ts`)
The Firefox browser type handles:
- **Binary detection**: Locating the Firefox executable
- **Profile management**: Creating temporary profiles for isolation
- **Launch configuration**: Setting up Firefox-specific options
- **Juggler injection**: Ensuring Juggler is properly initialized
### Browser Instance (`ffBrowser.ts`)
The Firefox browser instance provides:
- **Page tracking**: Managing page instances within Firefox
- **Context handling**: Isolating browsing contexts
- **Protocol communication**: Managing Juggler-based communication
## WebKit Implementation
WebKit powers Safari and other browsers. Playwright's WebKit implementation provides support for this browser engine through a combination of native CDP support and custom protocol handling.
### WebKit Architecture
```mermaid
graph TD
A[webkit.launch()] --> B[WebKit#44;BrowserType]
B --> C[WKBrowser#44;ConnectedBrowser]
C --> D[WebKit Protocol Handler]
D --> E[CDP Compatible Layer]
E --> F[WebKit Browser Process]
C --> G[WebKitBrowserContext]
G --> H[WKPage]
H --> D
```
### Browser Type (`webkit.ts`)
The WebKit browser type includes:
- **Executable resolution**: Finding WebKit-based browsers
- **Launch parameters**: Configuring WebKit-specific options
- **Connection setup**: Establishing protocol communication
### Browser Instance (`wkBrowser.ts`)
The WebKit browser instance manages:
- **Page lifecycle**: Creating and managing page instances
- **Protocol sessions**: Handling WebKit's protocol communication
- **Feature compatibility**: Ensuring WebKit-specific features work correctly
## BiDi Protocol Support
The WebDriver BiDi (Bidirectional) protocol is a standardized web automation protocol that provides bidirectional communication between automation tools and browsers. Playwright's support for BiDi enables:
- **Standardization**: Using the W3C-standardized protocol
- **Cross-browser compatibility**: A single protocol approach
- **Reduced complexity**: Simpler protocol handling compared to CDP
### BiDi Architecture
```mermaid
graph TD
A[BiDi Browser Connection] --> B[BidiBrowser#44;ConnectedBrowser]
B --> C[BiDi Session]
C --> D[Command Handler]
C --> E[Event Handler]
D --> F[Browser Commands]
E --> G[Browser Events]
B --> H[BrowserContext]
H --> I[Page]
subgraph "BiDi Protocol Messages"
J[JSON-RPC 2.0]
K[WebSocket Transport]
end
C --> J
J --> K
```
### BiDi Browser (`bidiBrowser.ts`)
The BiDi browser implementation provides:
- **Session management**: Creating and maintaining BiDi sessions
- **Command routing**: Dispatching commands to appropriate handlers
- **Event subscription**: Managing browser event subscriptions
- **Context isolation**: Supporting multiple browser contexts
## Protocol Communication
Playwright supports multiple communication protocols for interacting with browsers. Understanding these protocols helps in debugging and extending Playwright's capabilities.
### Chrome DevTools Protocol (CDP)
CDP is the primary protocol used by Chromium and partially by WebKit. It provides:
- **Complete browser control**: Full access to browser features
- **Rich debugging**: Detailed debugging capabilities
- **Real-time events**: Immediate event notifications
### WebDriver BiDi
BiDi is the W3C-standardized protocol for browser automation:
- **Cross-browser support**: Standard protocol across all browsers
- **Bidirectional communication**: Events flow both directions
- **Simpler model**: Less complex than CDP for basic operations
### Protocol Selection
| Feature | CDP | BiDi |
|---------|-----|------|
| Browser support | Chromium, WebKit | All browsers |
| Event subscription | Full | Full |
| Performance | Optimized | Standard |
| Standardization | Google-specific | W3C standard |
## Launch Configuration
Each browser type accepts launch options that configure how the browser instance is created.
### Common Launch Options
| Option | Type | Description | Chromium | Firefox | WebKit |
|--------|------|-------------|----------|---------|--------|
| `headless` | boolean | Run without visible UI | ✓ | ✓ | ✓ |
| `args` | string[] | Additional browser arguments | ✓ | ✓ | ✓ |
| `executablePath` | string | Custom browser executable | ✓ | ✓ | ✓ |
| `timeout` | number | Launch timeout in ms | ✓ | ✓ | ✓ |
| `viewport` | Viewport | Default page viewport | ✓ | ✓ | ✓ |
| `userAgent` | string | Custom user agent | ✓ | ✓ | ✓ |
| `locale` | string | Browser locale | ✓ | ✓ | ✓ |
| `proxy` | ProxyConfig | Proxy settings | ✓ | ✓ | ✓ |
### Headless Mode
Headless mode runs the browser without visible UI, essential for CI/CD environments and server-side automation. All three browsers support headless execution with identical behavior.
### Persistent Contexts
Playwright supports persistent browser contexts that maintain state across sessions:
```mermaid
graph LR
A[User Data Directory] --> B[Browser Profile]
B --> C[Cookies]
B --> D[Local Storage]
B --> E[Session Storage]
B --> F[Cache]
```
## Browser Contexts and Pages
### Architecture
```mermaid
graph TD
Browser --> Context1[BrowserContext]
Browser --> Context2[BrowserContext]
Context1 --> Page1[Page]
Context1 --> Page2[Page]
Context2 --> Page3[Page]
Page1 --> CDPSession[CDP Session]
Page2 --> CDPSession
```
### BrowserContext
Browser contexts provide isolation between different automation sessions:
- **Separate storage**: Each context has its own cookies, cache, and storage
- **Independent state**: Actions in one context don't affect others
- **Parallel execution**: Contexts can run simultaneously
- **Resource isolation**: Memory and process isolation
### Page
Pages represent individual browser tabs or windows:
- **Navigation**: Loading URLs and managing history
- **Interaction**: Clicking, typing, and other user actions
- **Evaluation**: Running JavaScript in the page context
- **Capture**: Taking screenshots and generating PDFs
## Process Architecture
### Browser Process Model
```mermaid
graph TD
subgraph "Node.js Process"
A[Playwright API]
B[Connection]
end
subgraph "Browser Process"
C[Browser Main Process]
D[Renderer Process 1]
E[Renderer Process 2]
F[Renderer Process N]
end
B --> C
C --> D
C --> E
C --> F
```
### Process Communication
The communication between Node.js and browser processes varies by browser:
- **Chromium**: Direct CDP over WebSocket or pipe
- **Firefox**: Juggler bridge acting as intermediary
- **WebKit**: CDP-compatible protocol over WebSocket
## Version Compatibility
Playwright maintains compatibility matrices for browser versions to ensure stable automation:
| Playwright Version | Chromium | Firefox | WebKit |
|-------------------|----------|---------|--------|
| 1.61.0-next | Latest | Latest | Latest |
| Stable releases | Bundled | Bundled | Bundled |
Browser binaries are downloaded and managed by Playwright's installer, ensuring version compatibility between the library and browser binaries.
## Extension Points
The browser implementation architecture supports extension through:
### Custom Browser Executables
```typescript
const browser = await chromium.launch({
executablePath: '/path/to/custom/chromium'
});
```
### Protocol Interceptors
Extensions can intercept and modify protocol messages for debugging or custom behavior.
### Custom Context Options
Browser contexts accept custom options specific to each browser implementation.
## Troubleshooting
### Browser Installation Issues
```bash
# Install all browsers
npx playwright install
# Install specific browser
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
```
### Connection Issues
Connection problems typically manifest as timeout errors during launch or operation. The trace viewer tool (`npx playwright trace`) helps diagnose these issues by capturing detailed protocol communication.
### Platform-Specific Considerations
Each browser may have platform-specific requirements:
- **Chromium**: Generally has few platform-specific issues
- **Firefox**: Requires Juggler patches for all platforms
- **WebKit**: May require platform-specific dependencies
## Summary
Playwright's browser implementation architecture provides a robust, extensible foundation for cross-browser automation. By abstracting browser-specific details through a common interface while supporting multiple communication protocols, Playwright enables developers to write reliable browser automation code that works consistently across Chromium, Firefox, and WebKit.
The architecture's modular design allows for independent browser implementations while sharing common infrastructure, making it possible to add new browser support or extend existing capabilities without affecting the overall system.
---
## Trace Viewer and Debugging Tools
### 相关页面
相关主题：[Test Runner and Execution Engine](#page-5), [CLI, MCP Server, and Agent Integration](#page-10)
Relevant Source Files
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/server/trace/recorder/tracing.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/trace/recorder/tracing.ts)
- [packages/playwright-core/src/server/trace/recorder/snapshotter.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/trace/recorder/snapshotter.ts)
- [packages/trace-viewer/src/index.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/index.tsx)
- [packages/trace-viewer/src/ui/workbench.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/workbench.tsx)
- [packages/isomorphic/trace/traceLoader.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/trace/traceLoader.ts)
- [packages/isomorphic/trace/traceModel.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/trace/traceModel.ts)
- [packages/trace/src/trace.ts](https://github.com/microsoft/playwright/blob/main/packages/trace/src/trace.ts)
# Trace Viewer and Debugging Tools
## Overview
Playwright's Trace Viewer and Debugging Tools provide comprehensive execution tracing capabilities for debugging and analyzing browser automation tests. The tracing system captures detailed execution traces including DOM snapshots, screenshots, network activity, and console logs, enabling developers to reconstruct and analyze exactly what happened during test execution.
The trace infrastructure consists of three main components:
| Component | Purpose | Location |
|-----------|---------|----------|
| Trace Recorder | Captures actions, snapshots, and metadata during test execution | `packages/playwright-core/src/server/trace/recorder/` |
| Trace Viewer | Progressive Web App for visual trace inspection | `packages/trace-viewer/` |
| Trace Model | Data structures and loading logic for trace files | `packages/isomorphic/trace/` |
资料来源：[packages/trace-viewer/src/index.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/index.tsx)
## Architecture
```mermaid
graph TD
A[Test Execution] --> B[Tracing Recorder]
B --> C[Snapshotter]
B --> D[Action Logger]
B --> E[Network Monitor]
C --> F[DOM Snapshots]
D --> G[Action Log]
E --> H[Network Events]
F --> I[trace-{timestamp}.trace]
G --> I
H --> J[trace-{timestamp}.network]
I --> K[Trace ZIP Archive]
J --> K
K --> L[Trace Viewer PWA]
K --> M[playwright trace CLI]
```
### Core Components
#### Trace Recorder (`packages/playwright-core/src/server/trace/recorder/tracing.ts`)
The `Tracing` class manages the recording process for browser contexts. It initializes snapshot capture, action logging, and network monitoring.
| Method | Description |
|--------|-------------|
| `start()` | Initializes trace recording with snapshotter and action collectors |
| `stop()` | Finalizes and writes trace files |
| `snapshot()` | Captures current DOM state |
#### Snapshotter (`packages/playwright-core/src/server/trace/recorder/snapshotter.ts`)
Captures DOM snapshots before and after each action, enabling reconstruction of page state at any point during test execution.
资料来源：[packages/playwright-core/src/server/trace/recorder/snapshotter.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/trace/recorder/snapshotter.ts)
#### Trace Model (`packages/isomorphic/trace/traceModel.ts`)
The `TraceModel` class represents the in-memory structure of a trace file, containing:
| Property | Type | Description |
|----------|------|-------------|
| `actions` | `ActionTrace[]` | All recorded actions |
| `events` | `TraceEvent[]` | Network, console, and other events |
| `snapshots` | `Snapshot[]` | DOM snapshots |
#### Trace Loader (`packages/isomorphic/trace/traceLoader.ts`)
Handles parsing and loading of trace files from disk or network.
资料来源：[packages/isomorphic/trace/traceLoader.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/trace/traceLoader.ts)
## Trace File Format
When tracing starts, Playwright creates a `traces/` directory containing several files:
### File Structure
| File | Format | Contents |
|------|--------|----------|
| `trace-{timestamp}.trace` | Binary/JSON | Action log with DOM snapshots, screenshots, timing |
| `trace-{timestamp}.network` | Binary/JSON | Complete network activity including headers, bodies, timing |
| `resources/` | Directory | Cached resources (images, fonts, scripts) |
### Trace Archive
All trace files are packaged into a `.zip` archive for easy sharing and analysis:
```bash
# Default location
test-results/{test-name}/trace.zip
```
### Captured Data Categories
| Category | Details |
|----------|---------|
| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
| **DOM** | Full DOM snapshot before/after each action |
| **Screenshots** | Visual state at each step |
| **Network** | All requests, responses, headers, bodies, timing |
| **Console** | Browser console messages and stdout/stderr |
| **Errors** | Error messages with stack traces |
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/tracing.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/tracing.md)
## Trace Viewer UI
The Trace Viewer is a Progressive Web App that runs locally in the browser without sending trace data anywhere.
```mermaid
graph LR
A[Open trace.zip] --> B[Extract & Parse]
B --> C[Action Timeline]
B --> D[Snapshot View]
B --> E[Network Log]
B --> F[Console Output]
```
### Key Features
| Feature | Description |
|---------|-------------|
| **Action Timeline** | Visual representation of all actions with timing |
| **DOM Snapshots** | Interactive DOM inspection at any action point |
| **Network Log** | Filterable view of all HTTP requests/responses |
| **Console View** | Console messages with filtering by type |
| **Error Tracking** | Consolidated view of all errors with stack traces |
### Loading Traces
Traces can be loaded in multiple ways:
1. **Local File**: Drop `.zip` file directly into the viewer
2. **URL Parameter**: Pass `?trace=` with trace URL
3. **Upload Button**: Select file via browser dialog
The viewer displays a progress indicator during trace loading:
```tsx
```
资料来源：[packages/trace-viewer/src/ui/workbench.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/workbench.tsx)
## CLI Commands
### Trace Recording Commands
| Command | Description |
|---------|-------------|
| `playwright-cli tracing-start` | Start trace recording |
| `playwright-cli tracing-stop` | Stop trace recording and save |
### Trace Inspection Commands
| Command | Description |
|---------|-------------|
| `npx playwright trace open ` | Open and extract trace |
| `npx playwright trace close` | Remove extracted trace data |
| `npx playwright trace actions` | List all actions |
| `npx playwright trace actions --grep "click"` | Filter actions by pattern |
| `npx playwright trace actions --errors-only` | Show only failed actions |
| `npx playwright trace action ` | Show details for one action |
| `npx playwright trace requests` | List all network requests |
| `npx playwright trace requests --failed` | Show only failed requests |
| `npx playwright trace request ` | Show request details |
| `npx playwright trace console` | Show console messages |
| `npx playwright trace console --errors-only` | Show only errors |
| `npx playwright trace errors` | Show all errors with stack traces |
| `npx playwright trace snapshot ` | Get DOM snapshot |
| `npx playwright trace attachments` | List trace attachments |
### Example Workflow
```bash
# 1. Open trace and view metadata
npx playwright trace open test-results/my-test/trace.zip
# 2. List all actions
npx playwright trace actions
# 3. Show only failed actions
npx playwright trace actions --errors-only
# 4. Get details for specific action
npx playwright trace action 12
# 5. View DOM at that point
npx playwright trace snapshot 12
# 6. Check for network failures
npx playwright trace requests --failed
# 7. View console errors
npx playwright trace console --errors-only
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)
## Integration with Test Debugging
### Debug Mode
Run tests in debug mode with CLI integration:
```bash
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
```
This command:
1. Pauses test execution at start
2. Prints debugging instructions with session name
3. Allows attaching via `playwright-cli` to explore the page
### Attaching to Test Session
```bash
# After starting debug mode, attach to the printed session
playwright-cli attach tw-abcdef
```
Available exploration commands while attached:
| Command | Description |
|---------|-------------|
| `playwright-cli snapshot` | Get current DOM snapshot |
| `playwright-cli click [` | Interact with elements |
| `playwright-cli eval ` | Execute JavaScript |
| `playwright-cli show --annotate` | Launch annotation dashboard |
| `playwright-cli resume` | Resume test execution |
### Spec-Driven Testing Workflow
The debugging tools integrate with Playwright's spec-driven testing approach:
1. **Create seed test** that navigates to the application
2. **Run seed in debug mode** and attach via CLI
3. **Explore the app** to understand interactive surfaces
4. **Write spec file** documenting expected behavior
5. **Generate tests** from the spec
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md)
## API Reference
### JavaScript Execution in CLI
Execute arbitrary JavaScript in the browser context:
```bash
# Basic evaluation
playwright-cli eval "document.title"
# With return value
playwright-cli run-code "async page => await page.title()"
# Read from clipboard
playwright-cli run-code "async page => {
await page.context().grantPermissions(['clipboard-read']);
return await page.evaluate(() => navigator.clipboard.readText());
}"
```
### Page Information
```bash
# Get page title
playwright-cli run-code "async page => await page.title()"
# Get current URL
playwright-cli run-code "async page => page.url()"
# Get viewport size
playwright-cli run-code "async page => page.viewportSize()"
```
### Snapshot with Custom Depth
```bash
# Default snapshot
playwright-cli snapshot
# Snapshot with element bounding boxes
playwright-cli snapshot --boxes
# Limited depth for performance
playwright-cli snapshot --depth=4
# Snapshot specific element
playwright-cli snapshot "#main"
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/running-code.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/running-code.md)
## Storage State Management
### Saving Authentication State
```bash
# Step 1: Login and save state
playwright-cli open https://app.example.com/login
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
playwright-cli state-save auth.json
# Step 2: Later, restore state
playwright-cli state-load auth.json
playwright-cli open https://app.example.com/dashboard
# Already authenticated
```
### Cookie Management
| Command | Description |
|---------|-------------|
| `playwright-cli cookie-list` | List all cookies |
| `playwright-cli cookie-get ` | Get specific cookie |
| `playwright-cli cookie-set ` | Set a cookie |
| `playwright-cli cookie-delete ` | Delete a cookie |
| `playwright-cli cookie-clear` | Clear all cookies |
### Local/Session Storage
```bash
# List storage items
playwright-cli localstorage-list
playwright-cli sessionstorage-list
# Get specific value
playwright-cli localstorage-get theme
playwright-cli sessionstorage-get step
# Set value
playwright-cli localstorage-set theme dark
playwright-cli sessionstorage-set step 3
# Delete/Clear
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/storage-state.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/storage-state.md)
## Advanced Features
### Persistent Profiles
Browser profiles can be persisted to disk for testing scenarios requiring persistent state:
```bash
# Auto-generated profile location
playwright-cli open https://example.com --persistent
# Custom profile directory
playwright-cli open https://example.com --profile=/path/to/profile
# Create named session with persistent profile
playwright-cli -s=mysession open example.com --persistent
```
### Network Interception
```bash
# Mock responses
playwright-cli route "**/*.jpg" --status=404
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
# List and remove routes
playwright-cli route-list
playwright-cli unroute "**/*.jpg"
```
### Highlighting Elements
```bash
# Highlight an element
playwright-cli highlight e5
# Highlight with custom style
playwright-cli highlight e5 --style="outline: 3px dashed red"
# Hide highlights
playwright-cli highlight --hide
```
### Video Recording
```bash
# Start video recording
playwright-cli video-start video.webm
# Add chapter markers
playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
# Stop recording
playwright-cli video-stop
```
## Best Practices
| Practice | Description |
|----------|-------------|
| **Use `--debug=cli`** | Always debug through test execution, not direct URL opening |
| **Capture specific actions** | Use `--grep` flags to narrow focus during investigation |
| **Save authentication state** | Reuse authenticated sessions instead of repeating login |
| **Use raw output** | Pipe CLI output to tools like `jq` for scripting |
| **Clean up traces** | Run `playwright-cli trace close` after investigation |
### Raw Output for Scripting
```bash
# Get JSON output for processing
playwright-cli list --json
# Pipe to jq for data extraction
playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
# Save to file
playwright-cli --raw snapshot > before.yml
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/SKILL.md)
---
## CLI, MCP Server, and Agent Integration
### 相关页面
相关主题：[Trace Viewer and Debugging Tools](#page-9)
]
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/tools/cli-client/cli.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/cli.ts)
- [packages/playwright-core/src/tools/mcp/index.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp/index.ts)
- [packages/playwright-core/src/tools/mcp/browserFactory.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserFactory.ts)
- [packages/playwright-core/src/tools/mcp/browserModel.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserModel.ts)
- [packages/playwright-core/src/tools/dashboard/dashboardApp.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/dashboard/dashboardApp.ts)
- [packages/dashboard/src/dashboard.tsx](https://github.com/microsoft/playwright/blob/main/packages/dashboard/src/dashboard.tsx)
- [packages/playwright-core/src/tools/backend/tools.ts](https://github.com/microsoft/microsoft/playwright/blob/main/packages/playwright-core/src/tools/backend/tools.ts)
# CLI, MCP Server, and Agent Integration
## Overview
Playwright provides a comprehensive command-line interface (CLI), MCP (Model Context Protocol) server, and agent integration system that enables automated browser control, testing, and inspection workflows. These three interconnected components form the foundation of Playwright's external interaction layer, allowing developers and AI agents to programmatically control browsers, execute tests, and analyze application behavior.
The CLI layer (`playwright-cli`) provides a human-readable command interface for browser automation, while the MCP server exposes these capabilities to AI agents and automated systems. The agent integration system coordinates between tools, manages browser sessions, and maintains state across operations.
## Architecture Overview
```mermaid
graph TD
A[User / AI Agent] --> B[CLI Interface
playwright-cli]
A --> C[MCP Server
Model Context Protocol]
B --> D[Tool Backend
packages/playwright-core/src/tools/backend/tools.ts]
C --> D
D --> E[Browser Factory
browserFactory.ts]
E --> F[Browser Pool
Chromium, Firefox, WebKit]
D --> G[Session Manager]
G --> H[State: Cookies, LocalStorage,
SessionStorage]
D --> I[Trace Viewer
trace viewer package]
```
## CLI (`playwright-cli`)
### Purpose and Scope
The `playwright-cli` tool provides a command-line interface for browser automation and testing. It is defined in `packages/playwright-core/src/tools/cli-client/cli.ts` and offers a comprehensive set of commands for interacting with browsers without writing code directly.
The CLI accepts commands like `open`, `goto`, `click`, `fill`, `snapshot`, and many others, making browser automation accessible through a simple shell interface.
### Core Commands
#### Browser Lifecycle
| Command | Description |
|---------|-------------|
| `playwright-cli open [url]` | Opens a new browser and optionally navigates to URL |
| `playwright-cli close` | Closes the current browser session |
| `playwright-cli close-all` | Closes all browser sessions |
| `playwright-cli kill-all` | Forcefully terminates all browser processes |
#### Navigation
| Command | Description |
|---------|-------------|
| `playwright-cli goto ` | Navigate to the specified URL |
| `playwright-cli go-back` | Navigate back in browser history |
| `playwright-cli go-forward` | Navigate forward in browser history |
| `playwright-cli reload` | Reload the current page |
#### Element Interaction
| Command | Description | Example |
|---------|-------------|---------|
| `playwright-cli click [` | Click an element by ref | `playwright-cli click e15` |
| `playwright-cli dblclick ][` | Double-click an element | `playwright-cli dblclick e7` |
| `playwright-cli fill ][ ` | Fill input field | `playwright-cli fill e5 "text"` |
| `playwright-cli type ` | Type text into focused element | `playwright-cli type "search"` |
| `playwright-cli press ` | Press a keyboard key | `playwright-cli press Enter` |
| `playwright-cli select ][ ` | Select dropdown option | `playwright-cli select e9 "value"` |
| `playwright-cli check ][` | Check a checkbox | `playwright-cli check e12` |
| `playwright-cli uncheck ][` | Uncheck a checkbox | `playwright-cli uncheck e12` |
| `playwright-cli hover ][` | Hover over an element | `playwright-cli hover e4` |
| `playwright-cli drag ` | Drag element to target | `playwright-cli drag e2 e8` |
#### Data Input
| Command | Description |
|---------|-------------|
| `playwright-cli upload ` | Upload file to element |
| `playwright-cli drop ][ --path=` | Drop file onto element |
| `playwright-cli drop ][ --data==` | Drop data onto element |
### Snapshot and Inspection
The snapshot command captures the current page state, including interactive elements with their refs:
```bash
playwright-cli snapshot
playwright-cli snapshot --filename=state.yaml
playwright-cli snapshot "#main"
playwright-cli snapshot --depth=4
playwright-cli snapshot --boxes
```
Elements can be targeted using refs from snapshots, CSS selectors, or Playwright locators:
```bash
# Using ref
playwright-cli click e15
# Using CSS selector
playwright-cli click "#main > button.submit"
# Using role locator
playwright-cli click "getByRole('button', { name: 'Submit' })"
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/SKILL.md)
### Storage Management
```bash
# State persistence
playwright-cli state-save [filename]
playwright-cli state-load [filename]
# Cookies
playwright-cli cookie-list [--domain=]
playwright-cli cookie-get
playwright-cli cookie-set [--domain=] [--httpOnly] [--secure]
playwright-cli cookie-delete
playwright-cli cookie-clear
# LocalStorage
playwright-cli localstorage-list
playwright-cli localstorage-get
playwright-cli localstorage-set
playwright-cli localstorage-delete
playwright-cli localstorage-clear
# SessionStorage
playwright-cli sessionstorage-list
playwright-cli sessionstorage-get
playwright-cli sessionstorage-set
playwright-cli sessionstorage-delete
playwright-cli sessionstorage-clear
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/session-management.md)
### Network Interception
```bash
# Mock network responses
playwright-cli route "**/*.jpg" --status=404
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
playwright-cli route-list
playwright-cli unroute "**/*.jpg"
playwright-cli unroute
```
### Tracing
```bash
# Start/stop trace recording
playwright-cli tracing-start
playwright-cli tracing-stop
# Video chapters
playwright-cli video-start
playwright-cli video-chapter "Title" --description="Details" --duration=2000
playwright-cli video-stop
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/tracing.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/tracing.md)
### Tab Management
```bash
playwright-cli tab-list
playwright-cli tab-new [url]
playwright-cli tab-close [index]
playwright-cli tab-select
```
### Dialog Handling
```bash
playwright-cli dialog-accept [text]
playwright-cli dialog-dismiss
```
### Advanced: JavaScript Execution
```bash
playwright-cli run-code "async page => await page.title()"
playwright-cli eval "document.title"
playwright-cli eval "el => el.textContent" ][
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/running-code.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/running-code.md)
### Browser Sessions
Sessions allow multiple independent browser instances with optional persistence:
```bash
# Named session with persistent profile
playwright-cli -s=mysession open https://example.com --persistent
# With custom profile directory
playwright-cli -s=mysession open https://example.com --profile=/path/to/profile
# Session management
playwright-cli -s=mysession click e6
playwright-cli -s=mysession close
playwright-cli -s=mysession delete-data
# List and cleanup
playwright-cli list
playwright-cli close-all
playwright-cli kill-all
```
Session name can be set via environment variable:
```bash
export PLAYWRIGHT_CLI_SESSION="mysession"
```
## MCP Server Integration
### Purpose and Architecture
The MCP (Model Context Protocol) server provides programmatic access to Playwright's browser automation capabilities for AI agents. The server is defined in `packages/playwright-core/src/tools/mcp/index.ts` and exposes a standardized interface for browser control operations.
```mermaid
graph LR
A[AI Agent] -->|MCP Protocol| B[MCP Server]
index.ts]
B --> C[Browser Factory
browserFactory.ts]
B --> D[Browser Model
browserModel.ts]
C --> E[Chromium]
C --> F[Firefox]
C --> G[WebKit]
D --> H[Browser State
and Context]
```
### Browser Factory (`browserFactory.ts`)
The `BrowserFactory` class is responsible for creating and managing browser instances. It provides methods for launching browsers with various configurations:
```typescript
class BrowserFactory {
async launch(options?: BrowserLaunchOptions): Promise;
async connect(browserWSEndpoint: string): Promise;
async close(): Promise;
}
```
The factory handles:
- Browser type selection (Chromium, Firefox, WebKit)
- Launch option configuration
- Browser connection management
- Resource cleanup
资料来源：[packages/playwright-core/src/tools/mcp/browserFactory.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserFactory.ts)
### Browser Model (`browserModel.ts`)
The `BrowserModel` maintains state and context for browser instances:
```typescript
class BrowserModel {
id: string;
browser: Browser;
context: BrowserContext;
pages: Page[];
sessionName?: string;
createdAt: Date;
}
```
Key responsibilities:
- Tracking active pages and contexts
- Managing browser lifecycle
- Providing access to current state
- Handling browser events
资料来源：[packages/playwright-core/src/tools/mcp/browserModel.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/mcp/browserModel.ts)
### MCP Tool Interface
The MCP server exposes tools through the `tools.ts` backend:
```typescript
// Defined in packages/playwright-core/src/tools/backend/tools.ts
export interface Tool {
name: string;
description: string;
execute(params: ToolParams): Promise;
}
```
Available tool categories include:
- Navigation tools (goto, back, forward, reload)
- Interaction tools (click, fill, select, hover)
- Inspection tools (snapshot, screenshot, content)
- Storage tools (cookies, localStorage, sessionStorage)
## Dashboard and Visualization
### Dashboard Application (`dashboardApp.ts`)
The Playwright dashboard provides a visual interface for analyzing test results and traces:
```mermaid
graph TD
A[Test Execution] --> B[Trace Files
.zip format]
B --> C[Trace Viewer]
C --> D[Dashboard App
dashboardApp.ts]
D --> E[Action Timeline]
D --> F[Network Log]
D --> G[Console Output]
D --> H[Screenshots]
```
The dashboard displays:
- Test action timeline with timing information
- Network request/response logs
- Console messages and errors
- DOM snapshots at each step
- Screenshots for visual verification
资料来源：[packages/playwright-core/src/tools/dashboard/dashboardApp.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/dashboard/dashboardApp.ts)
### Trace Viewer (`workbenchLoader.tsx`)
The trace viewer is a Progressive Web App that loads locally without sending data externally:
```typescript
// Loading states
interface LoadState {
showFileUploadDropArea: boolean;
showProgressDialog: boolean;
processingErrorMessage?: string;
traceURL?: string;
}
```
Key features:
- Drag-and-drop trace file loading
- File browser selection
- Progress indication during trace parsing
- Local-only processing for privacy
资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/workbenchLoader.tsx)
### Dashboard React Component
The main dashboard component renders the UI:
```typescript
// packages/dashboard/src/dashboard.tsx
export const Dashboard: React.FC = ({ traceData }) => {
// Renders action tree, network log, console output, snapshots
};
```
## Spec-Driven Testing Workflow
The CLI supports a specification-driven testing workflow documented in `spec-driven-testing.md`:
```mermaid
graph LR
A[Write Spec File
specs/feature.plan.md] --> B[Generate Tests]
B --> C[Execute Tests]
C --> D[Generate Traces]
D --> E[Analyze Results]
E --> F[Annotate & Feedback]
```
### Spec File Structure
```markdown
# Test Plan
## Application Overview
## Test Scenarios
### 1.
**Seed:** `tests/seed.spec.ts`
#### 1.1.
**File:** `tests//.spec.ts`
**Steps:**
1.
- expect:
2.
- expect:
```
### Test Generation Flow
1. Create seed test that navigates to the app
2. Explore app using `playwright-cli attach` and `snapshot`
3. Write spec file with test scenarios
4. Generate actual test code from spec
5. Execute and capture traces
6. Review results in trace viewer
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md)
## Trace CLI Tool
### Command Reference
```bash
# Open and analyze traces
npx playwright trace open
npx playwright trace close
# List actions
npx playwright trace actions
npx playwright trace actions --grep "click"
npx playwright trace actions --errors-only
# View specific action
npx playwright trace action
# View requests, console, errors
npx playwright trace requests
npx playwright trace console
npx playwright trace errors
# Get DOM snapshot
npx playwright trace snapshot
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)
### Trace File Structure
When tracing is enabled, Playwright creates:
| File/Directory | Content |
|---------------|---------|
| `trace-{timestamp}.trace` | Action log with DOM snapshots, screenshots, timing |
| `trace-{timestamp}.network` | Complete network activity log |
| `resources/` | Cached resources for replay |
## Tool Backend Architecture
The tool backend (`packages/playwright-core/src/tools/backend/tools.ts`) serves as the coordination layer:
```mermaid
graph TD
A[CLI / MCP Server] --> B[Tool Backend
tools.ts]
B --> C[Browser Tool]
B --> D[Page Tool]
B --> E[Storage Tool]
B --> F[Trace Tool]
C --> G[Playwright Core API]
D --> G
E --> G
F --> G
```
### Tool Categories
| Category | Tools |
|----------|-------|
| Browser | launch, connect, close, context |
| Navigation | goto, back, forward, reload |
| Interaction | click, fill, select, hover, drag, type, press |
| Snapshot | snapshot, screenshot, pdf |
| Storage | cookies, localStorage, sessionStorage |
| Network | route, unroute, route-list |
## Package Structure
| Package | Purpose |
|---------|---------|
| `playwright` | Main package with all browser support |
| `@playwright/test` | Testing framework with reporters |
| `playwright-core` | Core API without browser binaries |
| `@playwright/browser-chromium` | Chromium browser support |
| `@playwright/browser-firefox` | Firefox browser support |
| `@playwright/browser-webkit` | WebKit browser support |
资料来源：[package.json](https://github.com/microsoft/playwright/blob/main/package.json), [packages/playwright-test/package.json](https://github.com/microsoft/playwright/blob/main/packages/playwright-test/package.json), [packages/playwright-webkit/package.json](https://github.com/microsoft/playwright/blob/main/packages/playwright-webkit/package.json)
## Environment Variables
| Variable | Purpose |
|----------|---------|
| `PLAYWRIGHT_CLI_SESSION` | Default session name for CLI |
| `PLAYWRIGHT_HTML_OPEN` | Controls browser launch behavior in tests |
| `PLAYWRIGHT_BROWSERS_PATH` | Custom browser installation directory |
## Error Handling Patterns
```bash
# Try-catch in run-code
playwright-cli run-code "async page => {
try {
await page.getByRole('button', { name: 'Submit' }).click({ timeout: 1000 });
return 'clicked';
} catch (e) {
return 'element not found';
}
}"
```
## Installation and Usage
### CLI Installation
```bash
# Use via npx (no installation required)
npx --no-install playwright-cli --version
# Or install globally
npm install -g playwright-cli
```
### Testing Commands
From the root `package.json`:
| Script | Purpose |
|--------|---------|
| `npm run test` | Run library tests |
| `npm run ctest` | Chromium tests only |
| `npm run ftest` | Firefox tests only |
| `npm run wtest` | WebKit tests only |
| `npm run biditest` | Bidi protocol tests |
## Summary
The Playwright CLI, MCP Server, and Agent Integration system provides a layered approach to browser automation:
1. **CLI Layer**: Human-friendly command interface for browser automation tasks
2. **MCP Layer**: Programmatic interface for AI agents and automated systems
3. **Tool Backend**: Coordination layer that manages browser factories and models
4. **Dashboard/Trace Viewer**: Visualization tools for analyzing test results
These components work together to enable comprehensive browser testing and automation workflows, from simple interactive sessions to complex AI-driven testing scenarios.
---
---
## Doramagic 踩坑日志
项目：microsoft/playwright
摘要：发现 38 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature]: Fail tests on page errors。
## 1. 安装坑 · 来源证据：[Feature]: Fail tests on page errors
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Fail tests on page errors
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_347cf8732e73437a9699e4d8bc55d958 | https://github.com/microsoft/playwright/issues/40880 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：[Feature]: Ubuntu 26.04 LTS support
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Ubuntu 26.04 LTS support
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_764e9005d6a94f41b4a8d9f52decca99 | https://github.com/microsoft/playwright/issues/40117 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：[Feature]: trace correlation hooks for external observability/replay systems
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: trace correlation hooks for external observability/replay systems
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3c11bc1bf38e448f82e5b70d9f909037 | https://github.com/microsoft/playwright/issues/40887 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 运行坑 · 来源证据：[Feature]: support signal in waitFor* APIs
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Feature]: support signal in waitFor* APIs
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_500f564d44534739b16e93ed0b6a86eb | https://github.com/microsoft/playwright/issues/40578 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 维护坑 · 来源证据：[BUG] "NS_BINDING_ABORTED" error in Firefox
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG] "NS_BINDING_ABORTED" error in Firefox
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_16f48d22960444cfa514e3e08d959d45 | https://github.com/microsoft/playwright/issues/20749 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 6. 安全/权限坑 · 失败模式：security_permissions: [Bug]: MCP createUserDataDir writes profile data to PLAYWRIGHT_BROWSERS_PATH, fails when path...
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [Bug]: MCP createUserDataDir writes profile data to PLAYWRIGHT_BROWSERS_PATH, fails when path is read-only
- 对用户的影响：Developers may expose sensitive permissions or credentials: [Bug]: MCP createUserDataDir writes profile data to PLAYWRIGHT_BROWSERS_PATH, fails when path is read-only
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: MCP createUserDataDir writes profile data to PLAYWRIGHT_BROWSERS_PATH, fails when path is read-only. Context: Observed when using node, docker, playwright, linux
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/microsoft/playwright/issues/40892
- 证据：failure_mode_cluster:github_issue | fmev_32d5131674a6cea46a3dd9fea57edcee | https://github.com/microsoft/playwright/issues/40892 | [Bug]: MCP createUserDataDir writes profile data to PLAYWRIGHT_BROWSERS_PATH, fails when path is read-only, failure_mode_cluster:github_issue | fmev_5eb5ff7b9134ac254ca127feb48992d6 | https://github.com/microsoft/playwright/issues/40892 | [Bug]: MCP createUserDataDir writes profile data to PLAYWRIGHT_BROWSERS_PATH, fails when path is read-only
## 7. 安全/权限坑 · 来源证据：[Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_641150bc817a45af974903e3c724aa41 | https://github.com/microsoft/playwright/issues/40681 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 失败模式：installation: [Bug]: In VS Code, tests are not displayed in the Testing section.
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: In VS Code, tests are not displayed in the Testing section.
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: In VS Code, tests are not displayed in the Testing section.
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: In VS Code, tests are not displayed in the Testing section.. Context: Observed when using node, playwright, windows, macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_429f2bbd1fa3334bca8aae5ee7df68b8 | https://github.com/microsoft/playwright/issues/40481 | [Bug]: In VS Code, tests are not displayed in the Testing section.
## 9. 安装坑 · 失败模式：installation: [Bug]: Reporter ignores NO_COLOR — colors and cursor codes still emitted with NO_COLOR=1
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: Reporter ignores NO_COLOR — colors and cursor codes still emitted with NO_COLOR=1
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: Reporter ignores NO_COLOR — colors and cursor codes still emitted with NO_COLOR=1
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Reporter ignores NO_COLOR — colors and cursor codes still emitted with NO_COLOR=1. Context: Observed when using node, playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_09c75aac9731971717426ccfbe72651b | https://github.com/microsoft/playwright/issues/40904 | [Bug]: Reporter ignores NO_COLOR — colors and cursor codes still emitted with NO_COLOR=1
## 10. 安装坑 · 失败模式：installation: [Bug]: VSCode extension aborts run after a single slow (>10s) API test — subsequent tests nev...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: VSCode extension aborts run after a single slow (>10s) API test — subsequent tests never execute despite
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: VSCode extension aborts run after a single slow (>10s) API test — subsequent tests never execute despite
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: VSCode extension aborts run after a single slow (>10s) API test — subsequent tests never execute despite. Context: Observed when using node, playwright, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_bd2b1ca9bdfc4104afb98768ab5f87d4 | https://github.com/microsoft/playwright/issues/40889 | [Bug]: VSCode extension aborts run after a single slow (>10s) API test — subsequent tests never execute despite
## 11. 安装坑 · 失败模式：installation: [Bug]: WebKit on Windows hangs when CONNECT proxy closes socket after 407 doesn't reconnect w...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: WebKit on Windows hangs when CONNECT proxy closes socket after 407 doesn't reconnect with credentials
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: WebKit on Windows hangs when CONNECT proxy closes socket after 407 doesn't reconnect with credentials
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: WebKit on Windows hangs when CONNECT proxy closes socket after 407 doesn't reconnect with credentials. Context: Observed when using node, playwright, windows, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_f50999f1a6066b929ea1a2971fefc95a | https://github.com/microsoft/playwright/issues/40768 | [Bug]: WebKit on Windows hangs when CONNECT proxy closes socket after 407 doesn't reconnect with credentials
## 12. 安装坑 · 失败模式：installation: [Bug]: playwright-cli open fails with EINVAL when session name is long on macOS due to unix s...
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug]: playwright-cli open fails with EINVAL when session name is long on macOS due to unix socket path length
- 对用户的影响：Developers may fail before the first successful local run: [Bug]: playwright-cli open fails with EINVAL when session name is long on macOS due to unix socket path length
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: playwright-cli open fails with EINVAL when session name is long on macOS due to unix socket path length. Context: Observed when using node, playwright, macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_0f40df2fb212e08cdc02306a91f914c1 | https://github.com/microsoft/playwright/issues/40878 | [Bug]: playwright-cli open fails with EINVAL when session name is long on macOS due to unix socket path length, failure_mode_cluster:github_issue | fmev_a8ab1c8959a949b8aee2604c9969fcc4 | https://github.com/microsoft/playwright/issues/40878 | [Bug]: playwright-cli open fails with EINVAL when session name is long on macOS due to unix socket path length
## 13. 安装坑 · 失败模式：installation: [Feature] Configure web servers per project
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Feature] Configure web servers per project
- 对用户的影响：Developers may fail before the first successful local run: [Feature] Configure web servers per project
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature] Configure web servers per project. Context: Observed when using node, python, playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_4722870d2dbf6cec9abf1c0c8bcde960 | https://github.com/microsoft/playwright/issues/22496 | [Feature] Configure web servers per project
## 14. 安装坑 · 失败模式：installation: [Regression]: install-deps --dry-run can no longer be used to generate install script
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Regression]: install-deps --dry-run can no longer be used to generate install script
- 对用户的影响：Developers may fail before the first successful local run: [Regression]: install-deps --dry-run can no longer be used to generate install script
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Regression]: install-deps --dry-run can no longer be used to generate install script. Context: Observed when using node, docker, playwright, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_c8dd7be64694731b0c1d899e67c604ae | https://github.com/microsoft/playwright/issues/40885 | [Regression]: install-deps --dry-run can no longer be used to generate install script
## 15. 安装坑 · 来源证据：[BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2c207034cca249f7b5c12ac82005f46f | https://github.com/microsoft/playwright/issues/13027 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 16. 安装坑 · 来源证据：[Bug]: Compound ANSI SGR codes lose styling in HTML reporter and trace viewer
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Compound ANSI SGR codes lose styling in HTML reporter and trace viewer
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1099381b0b074addae62105e5328e211 | https://github.com/microsoft/playwright/issues/40826 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 17. 安装坑 · 来源证据：[Bug]: In VS Code, tests are not displayed in the Testing section.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: In VS Code, tests are not displayed in the Testing section.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_37a2f26303c64848818cc2f7865f7426 | https://github.com/microsoft/playwright/issues/40481 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 18. 安装坑 · 来源证据：[Feature] Configure web servers per project
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Configure web servers per project
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_528a2b31f563446684290d7dc62c0b9f | https://github.com/microsoft/playwright/issues/22496 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 19. 安装坑 · 来源证据：[Feature]: Configurable last-run file location for improved CI shard use
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Configurable last-run file location for improved CI shard use
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0e5ae6ed54b0470dad14f33379cd267a | https://github.com/microsoft/playwright/issues/40805 | 来源类型 github_issue 暴露的待验证使用条件。
## 20. 安装坑 · 来源证据：[Feature]: keyboard.pressSequence() for batched named key presses
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: keyboard.pressSequence() for batched named key presses
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0ea0c22b305a43d48f3cd020cb99d222 | https://github.com/microsoft/playwright/issues/40740 | 来源类型 github_issue 暴露的待验证使用条件。
## 21. 安装坑 · 来源证据：[Regression]: install-deps --dry-run can no longer be used to generate install script
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Regression]: install-deps --dry-run can no longer be used to generate install script
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f01d9cdd9bf0431b887c561d41e500d4 | https://github.com/microsoft/playwright/issues/40885 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 22. 配置坑 · 失败模式：configuration: [Bug]: newPage sometimes hangs indefinitely on Firefox
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Bug]: newPage sometimes hangs indefinitely on Firefox
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]: newPage sometimes hangs indefinitely on Firefox
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: newPage sometimes hangs indefinitely on Firefox. Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_e47d5fda2471b4288d1427ec676e3942 | https://github.com/microsoft/playwright/issues/40882 | [Bug]: newPage sometimes hangs indefinitely on Firefox
## 23. 配置坑 · 失败模式：configuration: [Feature]: Configurable last-run file location for improved CI shard use
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Feature]: Configurable last-run file location for improved CI shard use
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: Configurable last-run file location for improved CI shard use
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Configurable last-run file location for improved CI shard use. Context: Observed when using python, playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_7cbc84a1a300e023acd52c21ad246467 | https://github.com/microsoft/playwright/issues/40805 | [Feature]: Configurable last-run file location for improved CI shard use
## 24. 配置坑 · 失败模式：configuration: [Feature]: Fail tests on page errors
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Feature]: Fail tests on page errors
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: Fail tests on page errors
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Fail tests on page errors. Context: Observed when using playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_face5b21f87e009618730d0ba96565c5 | https://github.com/microsoft/playwright/issues/40880 | [Feature]: Fail tests on page errors
## 25. 配置坑 · 失败模式：configuration: [Feature]: Hierarchal Projects
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Feature]: Hierarchal Projects
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: Hierarchal Projects
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Hierarchal Projects. Context: Observed when using playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_4c57d49ac0e7f3d85ed34fcff015d2c1 | https://github.com/microsoft/playwright/issues/40890 | [Feature]: Hierarchal Projects
## 26. 配置坑 · 失败模式：configuration: [Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces. Context: Observed when using python, playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_8ef6929f8ee894946dadbc5a2e818841 | https://github.com/microsoft/playwright/issues/40681 | [Feature]: Trace viewer: Add timeout-risk highlighting for actions in Playwright traces
## 27. 配置坑 · 来源证据：[Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_eefd168ed7194785a44744e0d489dc34 | https://github.com/microsoft/playwright/issues/31162 | 来源类型 github_issue 暴露的待验证使用条件。
## 28. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:221981891 | https://github.com/microsoft/playwright | README/documentation is current enough for a first validation pass.
## 29. 运行坑 · 失败模式：runtime: [BUG] "NS_BINDING_ABORTED" error in Firefox
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: [BUG] "NS_BINDING_ABORTED" error in Firefox
- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] "NS_BINDING_ABORTED" error in Firefox
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] "NS_BINDING_ABORTED" error in Firefox. Context: Observed when using node, playwright, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_21f0858060c2b2d6c7f5f8f26ec42f3e | https://github.com/microsoft/playwright/issues/20749 | [BUG] "NS_BINDING_ABORTED" error in Firefox
## 30. 运行坑 · 失败模式：runtime: [BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: [BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox
- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox. Context: Observed when using node, docker, playwright, macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_fb1936317ab9129c8d5d5dc060c212ee | https://github.com/microsoft/playwright/issues/13027 | [BUG] page.goto: NS_ERROR_NET_TIMEOUT in Firefox
## 31. 运行坑 · 失败模式：runtime: [Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: [Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker. Context: Observed when using playwright
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_18f4dc6435817d05134a997d1ad7134e | https://github.com/microsoft/playwright/issues/31162 | [Bug]: Unable to Listen to Download Event While Using window.showSaveFilePicker
## 32. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | last_activity_observed missing
## 33. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium
## 34. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium
## 35. 安全/权限坑 · 来源证据：[Feature] support WebAuthn
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] support WebAuthn
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_874db657219c4a63a90b030fed024459 | https://github.com/microsoft/playwright/issues/7276 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 36. 安全/权限坑 · 来源证据：[Feature]: Multi-Tab and Multi-Browser Recording Support
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Multi-Tab and Multi-Browser Recording Support
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_dcba5ea273d149518992b7a0beaa9868 | https://github.com/microsoft/playwright/issues/40769 | 来源类型 github_issue 暴露的待验证使用条件。
## 37. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | issue_or_pr_quality=unknown
## 38. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | release_recency=unknown