# 列出所有操作
npx playwright trace actions
# 查看特定操作详情
npx playwright trace action 12
# 查看快照
npx playwright trace snapshot 12
# 查看网络请求
npx playwright trace requests --failed
# 查看控制台错误
npx playwright trace console --errors-only
```
### 典型调查流程
```bash
# 1. 打开追踪
npx playwright trace open test-results/my-test/trace.zip
# 2. 查看操作列表
npx playwright trace actions
# 3. 找出失败的操作
npx playwright trace actions --errors-only
# 4. 分析失败详情
npx playwright trace action 12
# 5. 查看页面快照
npx playwright trace snapshot 12
# 6. 查询 DOM 获取更多信息
npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent"
# 7. 检查网络失败
npx playwright trace requests --failed
# 8. 检查控制台错误
npx playwright trace console --errors-only
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()
### Trace Viewer Web 应用
Trace Viewer 也是一个渐进式 Web 应用（PWA），可通过 `trace.playwright.dev` 在线访问：
```tsx
1. Download the trace from the download shelf
3. Drop the trace from the download shelf into the page
```
资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx:1-20]()
## 代码生成
Playwright 支持多种编程语言的测试代码生成，包括 JavaScript、TypeScript、C# 等。
资料来源：[packages/playwright-core/src/server/codegen/csharp.ts]()
### C# 代码生成
```csharp
// 创建新页面
var page = await context.NewPageAsync();
await page.GotoAsync("https://example.com");
// 对话框处理
void Page_Dialog_EventHandler(object sender, IDialog dialog)
{
Console.WriteLine($"Dialog message: {dialog.Message}");
dialog.DismissAsync();
Page.Dialog -= Page_Dialog_EventHandler;
}
Page.Dialog += Page_Dialog_EventHandler;
// 下载处理
var download = await Page.RunAndWaitForDownloadAsync(async () =>
{
// 执行下载操作
});
```
资料来源：[packages/playwright-core/src/server/codegen/csharp.ts:1-30]()
## HTML 报告器
Playwright HTML Reporter 用于生成可视化的测试报告，包含测试用例状态、持续时间、注释等信息。
```tsx
({
id: String(index),
title:
{statusIcon(result.status)} {retryLabel(index)}
{(test.results.length > 1) && {msToString(result.duration)}}
,
render: () => { /* 渲染测试结果 */ }
}))
} />
```
资料来源：[packages/html-reporter/src/testCaseView.tsx:1-30]()
### 报告功能
| 功能 | 说明 |
|------|------|
| 测试状态图标 | 显示通过/失败/跳过等状态 |
| 重试标签 | 标记重试次数 |
| 持续时间 | 显示每个测试的执行时长 |
| 注释展示 | 显示测试注释和注解 |
| 追踪链接 | 提供到追踪文件的链接 |
资料来源：[packages/html-reporter/src/testCaseView.tsx:30-50]()
## 页面注入 API
Playwright 在浏览器上下文中注入了 `window.playwright` 对象，提供调试和测试辅助功能：
```typescript
install() {
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:18-35]()
### 可用方法
| 方法 | 功能描述 |
|------|----------|
| `$.query()` | 使用 Playwright 选择器语法查询单个元素 |
| `$$.queryAll()` | 查询所有匹配的元素 |
| `inspect()` | 检查元素的定位器信息 |
| `selector()` | 生成元素的选择器 |
| `generateLocator()` | 生成可用的定位器代码 |
| `ariaSnapshot()` | 获取 ARIA 树快照 |
| `resume()` | 恢复测试执行 |
## 规范驱动测试
Playwright 支持基于规范的测试工作流，帮助团队从用户故事生成可执行的测试用例。
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()
### 测试工作流
```mermaid
graph LR
A[编写规范] --> B[生成 Seed 测试]
B --> C[探索应用]
C --> D[完善规范]
D --> E[生成测试代码]
E --> F[运行测试]
```
### 规范文件结构
```markdown
# <功能> 测试计划
## 应用概述
<描述功能做什么以及为什么重要>
## 测试场景
### 1. <分组名称>
**Seed:** `tests/seed.spec.ts`
#### 1.1. <场景名称>
**文件:** `tests//.spec.ts`
**步骤:**
1. <具体用户操作>
- expect: <可观察的结果>
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()
### 探索应用
```bash
# 启动应用进行探索
PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli
# 附加到调试会话
playwright-cli attach tw-XXXX
# 探索命令
playwright-cli resume # 运行 seed 测试
playwright-cli snapshot # 元素清单
playwright-cli click e5 # 点击元素
playwright-cli eval "location.href" # 读取 URL/状态
playwright-cli show --annotate # 请求用户指向
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()
## 总结
Playwright 是一个功能完整的跨浏览器测试框架，主要特点包括：
- **多浏览器支持**：Chromium、Firefox、WebKit
- **丰富的 CLI 工具**：playwright-cli 和 playwright-trace
- **代码生成能力**：支持多种编程语言
- **追踪可视化**：支持离线查看测试执行过程
- **规范驱动测试**：支持从用户规范生成测试
- **页面注入调试**：提供浏览器内调试 API
---
## 快速入门
### 相关页面
相关主题：[项目概述](#project-overview), [测试框架](#test-framework), [命令行工具](#cli-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/microsoft/playwright/blob/main/package.json)
- [examples/svgomg/package.json](https://github.com/microsoft/playwright/blob/main/examples/svgomg/package.json)
- [examples/todomvc/package.json](https://github.com/microsoft/playwright/blob/main/examples/todomvc/package.json)
- [packages/playwright/package.json](https://github.com/microsoft/playwright/blob/main/packages/playwright/package.json)
- [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)
- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)
# 快速入门
## 概述
Playwright 是一个用于自动化 Web 浏览器的 Node.js 库，由 Microsoft 开发维护。它提供了高层次的 API，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎。Playwright 的主要特性包括：跨浏览器自动化、自动化等待机制、自动录制功能、以及强大的调试工具。
当前版本为 **1.61.0-next**，最低要求 Node.js 18 及以上版本。
## 安装 Playwright
### 系统要求
| 组件 | 要求 |
|------|------|
| Node.js | >= 18 |
| 操作系统 | Windows、macOS、Linux |
| 浏览器 | Chromium、Firefox、WebKit |
### 安装命令
```bash
# 使用 npm 安装
npm install @playwright/test
# 使用 yarn 安装
yarn add @playwright/test
# 使用 pnpm 安装
pnpm add @playwright/test
```
安装完成后，需要下载浏览器依赖：
```bash
# 下载所有浏览器
npx playwright install
# 仅安装特定浏览器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
```
## 创建第一个测试
### 项目结构
Playwright 测试项目通常包含以下文件：
```
my-playwright-project/
├── package.json
├── playwright.config.ts
├── tests/
│ └── example.spec.ts
└── playwright-report/
```
### 配置文件
在项目根目录创建 `playwright.config.ts`：
```typescript
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
{
name: 'webkit',
use: { ...devices['Desktop Safari'] },
},
],
});
```
资料来源：[examples/svgomg/package.json:1-13]()
### 编写测试用例
创建 `tests/example.spec.ts` 文件：
```typescript
import { test, expect } from '@playwright/test';
test('has title', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveTitle(/Example Domain/);
});
test('get started link', async ({ page }) => {
await page.goto('https://example.com');
await page.getByRole('link', { name: 'More information' }).click();
await expect(page).toHaveURL(/.*more/);
});
```
## 运行测试
### 基本命令
| 命令 | 说明 |
|------|------|
| `npx playwright test` | 运行所有测试 |
| `npx playwright test --project=chromium` | 仅运行 Chromium 测试 |
| `npx playwright test tests/example.spec.ts` | 运行指定文件 |
| `npx playwright test --grep "login"` | 运行匹配的测试 |
### 调试模式
使用 CLI 调试模式启动测试：
```bash
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
```
调试时会输出会话名称，格式为 `tw-XXXX`。使用 `playwright-cli` 附加到该会话进行调试：
```bash
playwright-cli attach tw-XXXX
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md:1-21]()
## Playwright CLI 工具
`playwright-cli` 是 Playwright 提供的命令行交互工具，支持浏览器会话管理、元素交互、快照获取等功能。
### 常用命令
#### 浏览器会话管理
```bash
# 打开浏览器
playwright-cli open https://example.com
# 使用指定浏览器
playwright-cli open https://example.com --browser=firefox
# 有头模式
playwright-cli open https://example.com --headed
# 关闭所有浏览器
playwright-cli close-all
# 强制终止所有浏览器进程
playwright-cli kill-all
```
#### 页面交互
```bash
# 点击元素（使用快照中的 ref）
playwright-cli click e5
# 使用 CSS 选择器
playwright-cli click "#main > button.submit"
# 填写输入框
playwright-cli fill e2 "test input"
# 获取快照
playwright-cli snapshot
# 截图
playwright-cli screenshot --filename=page.png
```
#### 元素定位
Playwright 支持多种定位策略：
| 定位方式 | 示例 |
|----------|------|
| CSS 选择器 | `"#main > button.submit"` |
| Role 定位器 | `"getByRole('button', { name: 'Submit' })"` |
| 测试 ID | `"getByTestId('submit-button')"` |
| 快照引用 | `e5`, `e15` |
#### 网络拦截
```bash
# 拦截请求返回 404
playwright-cli route "**/*.jpg" --status=404
# 拦截并返回 mock 数据
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
# 列出所有路由规则
playwright-cli route-list
# 移除路由规则
playwright-cli unroute "**/*.jpg"
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md:1-120]()
### 持久化会话
使用命名会话可以保持浏览器状态：
```bash
# 创建持久化会话
playwright-cli -s=mysession open https://example.com --persistent
# 附加到会话
playwright-cli -s=mysession click e6
# 关闭会话
playwright-cli -s=mysession close
# 删除会话数据
playwright-cli -s=mysession delete-data
```
## 追踪与调试
### 追踪功能
Playwright 可以录制完整的测试执行轨迹，包含 DOM 快照、截图、网络活动和控制台日志。
#### 使用 CLI 录制追踪
```bash
# 开始录制
playwright-cli tracing-start
# 执行操作
playwright-cli open https://example.com
playwright-cli click e1
playwright-cli fill e2 "test"
# 停止录制
playwright-cli tracing-stop
```
录制完成后，会在 `traces/` 目录下生成以下文件：
| 文件 | 说明 |
|------|------|
| `trace-{timestamp}.trace` | 动作日志，包含所有操作、DOM 快照、截图 |
| `trace-{timestamp}.network` | 网络日志，包含所有请求和响应 |
| `resources/` | 缓存的资源文件 |
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/tracing.md:1-45]()
### Trace Viewer
使用 Playwright Trace CLI 查看追踪文件：
```bash
# 打开追踪文件
npx playwright trace open
# 查看所有动作
npx playwright trace actions
# 查看失败的动作
npx playwright trace actions --errors-only
# 查看动作详情
npx playwright trace action
# 查看快照
npx playwright trace snapshot
# 查看控制台错误
npx playwright trace console --errors-only
# 查看失败的请求
npx playwright trace requests --failed
# 关闭追踪
npx playwright trace close
```
典型调查流程：
```bash
# 1. 打开追踪文件
npx playwright trace open test-results/my-test/trace.zip
# 2. 查看执行的动作
npx playwright trace actions
# 3. 查看失败的动作
npx playwright trace actions --errors-only
# 4. 查看详情
npx playwright trace action 12
# 5. 查看页面快照
npx playwright trace snapshot 12
# 6. 查询 DOM 获取更多细节
npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent"
# 7. 检查网络失败
npx playwright trace requests --failed
# 8. 检查控制台错误
npx playwright trace console --errors-only
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md:1-75]()
## 浏览器会话与存储
### 保存和加载状态
```bash
# 保存状态
playwright-cli state-save auth.json
# 加载状态
playwright-cli state-load auth.json
```
### Cookie 管理
```bash
# 列出所有 Cookie
playwright-cli cookie-list
# 按域名过滤
playwright-cli cookie-list --domain=example.com
# 获取指定 Cookie
playwright-cli cookie-get session_id
# 设置 Cookie
playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
# 删除 Cookie
playwright-cli cookie-delete session_id
# 清除所有 Cookie
playwright-cli cookie-clear
```
### 本地存储
```bash
# LocalStorage
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear
# SessionStorage
playwright-cli sessionstorage-list
playwright-cli sessionstorage-set step 3
playwright-cli sessionstorage-delete step
playwright-cli sessionstorage-clear
```
## 代码执行
### 使用 run-code 执行自定义代码
```bash
# 获取页面标题
playwright-cli run-code "async page => {
return await page.title();
}"
# 获取当前 URL
playwright-cli run-code "async page => {
return page.url();
}"
# 读取剪贴板
playwright-cli run-code "async page => {
await page.context().grantPermissions(['clipboard-read']);
return await page.evaluate(() => navigator.clipboard.readText());
}"
# 从文件执行代码
playwright-cli run-code --filename=script.js
```
### 使用 eval 执行 JavaScript
```bash
# 获取页面标题
playwright-cli eval "document.title"
# 获取元素内容
playwright-cli eval "el => el.textContent" e5
# 获取元素属性
playwright-cli eval "el => el.getAttribute('data-testid')" e5
# 保存结果到文件
playwright-cli eval "document.body.outerHTML" --filename=page.html
```
## 运行 npm 脚本示例
项目中的 `package.json` 定义了常用的测试脚本：
| 脚本 | 说明 |
|------|------|
| `npm run test` | 运行所有浏览器测试 |
| `npm run ctest` | 仅运行 Chromium 测试 |
| `npm run ftest` | 仅运行 Firefox 测试 |
| `npm run wtest` | 仅运行 WebKit 测试 |
资料来源：[package.json:19-35]()
## 快速参考
### 一分钟启动
```bash
# 1. 初始化项目
npm init -y
# 2. 安装 Playwright
npm install @playwright/test
# 3. 安装浏览器
npx playwright install
# 4. 创建配置
cat > playwright.config.ts << 'EOF'
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
use: { baseURL: 'http://localhost:3000' },
});
EOF
# 5. 运行测试
npx playwright test
```
### 常用命令速查
| 操作 | 命令 |
|------|------|
| 运行所有测试 | `npx playwright test` |
| 运行指定浏览器 | `npx playwright test --project=chromium` |
| 生成测试 | `npx playwright test --generate` |
| 显示 HTML 报告 | `npx playwright show-report` |
| 调试测试 | `npx playwright test --debug` |
| 录制追踪 | `npx playwright show-trace trace.zip` |
---
## 架构概览
### 相关页面
相关主题：[客户端实现](#client-implementation), [服务器端实现](#server-implementation), [浏览器支持](#browser-support)
相关源码文件
以下源码文件用于生成本页说明：
- [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/remote/playwrightServer.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/remote/playwrightServer.ts)
- [packages/playwright-core/src/inprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/inprocess.ts)
- [packages/playwright-core/src/outofprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/outofprocess.ts)
# 架构概览
Playwright 是一个用于自动化浏览器操作的高级 API 库。本页面详细介绍其核心架构设计，包括进程模型、客户端-服务器通信机制以及主要组件的职责划分。
## 核心设计理念
Playwright 的架构围绕两个核心目标设计：
| 目标 | 说明 |
|------|------|
| **跨浏览器一致性** | 提供统一的 API 接口，支持 Chromium、Firefox 和 WebKit 三种浏览器引擎 |
| **灵活的进程模型** | 支持进程内（in-process）和进程外（out-of-process）两种执行模式 |
Playwright 的核心代码位于 `packages/playwright-core/` 包中，负责处理底层浏览器通信和 API 实现。
## 进程模型
Playwright 支持两种进程模型，开发者可以根据场景选择适合的模式。
### 进程外模式（Out-of-Process）
进程外模式是 Playwright 的默认和推荐模式。在此模式下，Playwright 会在独立进程中启动浏览器，并通过 IPC（进程间通信）与浏览器进行交互。
```mermaid
graph TD
A[Playwright Client] -->|IPC| B[Playwright Server Process]
B -->|CDP Protocol| C[Chromium]
B -->|CDP Protocol| D[Firefox]
B -->|CDP Protocol| E[WebKit]
B --> F[Browser Processes]
F --> G[Renderer Processes]
F --> H[GPU Process]
```
**特点：**
- 隔离性强，浏览器崩溃不会影响主进程
- 支持远程连接（Remote Connection）
- 便于调试和监控
- 通过 `playwright-core/src/outofprocess.ts` 实现
资料来源：[packages/playwright-core/src/outofprocess.ts:1-50]()
### 进程内模式（In-Process）
进程内模式将 Playwright 和浏览器运行在同一进程中，减少了进程间通信的开销。此模式主要用于：
- 测试框架集成（如 `@playwright/test`）
- 需要快速执行的场景
- 与宿主应用紧密集成的用例
```mermaid
graph LR
A[Host Application] -->|Direct API| B[Playwright In-Process]
B --> C[Browser Instance]
```
资料来源：[packages/playwright-core/src/inprocess.ts:1-30]()
## 客户端连接架构
Playwright 的客户端通过 `Connection` 类建立与服务器端的通信通道。
### 连接类型
| 连接类型 | 适用场景 | 实现文件 |
|----------|----------|----------|
| **远程连接（Remote）** | 连接到独立的 Playwright 服务器进程 | `connection.ts` |
| **本地连接（Local）** | 直接连接到同进程或子进程的服务器 | `connection.ts` |
| **CDP 连接** | 直接使用 Chrome DevTools Protocol | `connection.ts` |
### 连接生命周期
```mermaid
sequenceDiagram
participant Client as Playwright Client
participant Conn as Connection
participant Server as Playwright Server
Client->>Conn: createConnection()
Conn->>Server: establishTransport()
Server-->>Conn: transportEstablished
Conn-->>Client: connected
Client->>Conn: sendMessage()
Conn->>Server: dispatch()
Server-->>Conn: response
Conn-->>Client: callback
Client->>Conn: close()
Conn->>Server: disconnect()
```
资料来源：[packages/playwright-core/src/client/connection.ts:1-100]()
## 服务器端架构
Playwright 服务器端负责管理浏览器实例和处理来自客户端的请求。
### 服务器组件
| 组件 | 职责 |
|------|------|
| **PlaywrightServer** | 主服务器类，管理所有浏览器会话 |
| **BrowserSession** | 管理单个浏览器实例的生命周期 |
| **ChromiumBrowser** | Chromium 特定实现 |
| **FirefoxBrowser** | Firefox 特定实现 |
| **WebKitBrowser** | WebKit 特定实现 |
### 服务器传输层
服务器支持多种传输协议：
- **stdio 传输**：用于父子进程通信
- **WebSocket 传输**：用于远程连接
- **CDP 传输**：直接与浏览器 DevTools 端口通信
资料来源：[packages/playwright-core/src/remote/playwrightServer.ts:1-80]()
## 浏览器会话管理
Playwright 通过会话（Session）机制管理多个独立的浏览器上下文。
### 会话类型
```mermaid
graph TD
A[PlaywrightServer] --> B[BrowserSession 1]
A --> C[BrowserSession 2]
A --> D[BrowserSession N]
B --> E[BrowserContext 1]
B --> F[BrowserContext 2]
E --> G[Page 1]
E --> H[Page 2]
G --> I[Frame]
```
### 持久化会话
Playwright 支持持久化会话（Persistent Context），允许保存和恢复浏览器状态：
```bash
# 创建命名会话
playwright-cli -s=mysession open https://example.com --persistent
# 指定配置文件目录
playwright-cli -s=mysession open https://example.com --profile=/path/to/profile
```
这对于需要保持登录状态的测试场景非常有用。
## 命令执行流程
Playwright CLI 提供了丰富的命令行接口来与浏览器交互。
### 核心命令处理
```
playwright-cli open → Browser.open()
playwright-cli goto → Page.goto()
playwright-cli click → Page.click()
playwright-cli fill → Page.fill()
```
### 元素定位策略
Playwright 支持多种元素定位方式：
| 定位方式 | 示例 | 优先级 |
|----------|------|--------|
| **Ref 引用** | `e15` | 最高（快照生成） |
| **CSS 选择器** | `#main > button` | 高 |
| **角色定位器** | `getByRole('button')` | 高 |
| **测试 ID** | `getByTestId('submit')` | 中 |
| **文本内容** | `getByText('Submit')` | 中 |
## 网络拦截
Playwright 提供了强大的网络拦截功能，用于测试和调试。
### 路由（Route）操作
```bash
# 拦截特定请求
playwright-cli route "**/*.jpg" --status=404
# 修改响应内容
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
# 列出所有路由规则
playwright-cli route-list
# 移除路由规则
playwright-cli unroute "**/*.jpg"
```
### 存储管理
| 存储类型 | 列表 | 获取 | 设置 | 删除 |
|----------|------|------|------|------|
| **Cookies** | `cookie-list` | `cookie-get` | `cookie-set` | `cookie-delete` |
| **LocalStorage** | `localstorage-list` | `localstorage-get` | `localstorage-set` | `localstorage-delete` |
| **SessionStorage** | `sessionstorage-list` | `sessionstorage-get` | `sessionstorage-set` | `sessionstorage-delete` |
## 跟踪与调试
Playwright 的跟踪功能可以捕获详细的执行信息，用于问题排查和性能分析。
### 跟踪文件结构
```
traces/
├── trace-{timestamp}.trace # 操作日志
├── trace-{timestamp}.network # 网络活动
└── resources/ # 缓存资源
```
### CLI 跟踪命令
```bash
# 开始跟踪
playwright-cli tracing-start
# 执行测试操作
playwright-cli click e1
playwright-cli fill e2 "test"
# 停止跟踪
playwright-cli tracing-stop
```
## 扩展机制
Playwright 支持通过插件扩展功能。
### MCP 集成
Playwright 提供了 MCP（Model Context Protocol）服务器集成，可以通过 AI 助手控制浏览器：
```bash
# 运行 MCP 测试
npm run test-mcp
```
### 扩展测试
```bash
# 测试扩展功能
npm run test-extension
```
## 包结构
| 包名 | 说明 |
|------|------|
| `playwright-core` | 核心库，包含所有底层实现 |
| `@playwright/test` | 测试框架，提供 `test()` 和 `expect()` |
| `playwright` | 完整包，包含浏览器驱动 |
| `@playwright/browser-chromium` | Chromium 浏览器驱动 |
| `@playwright/browser-firefox` | Firefox 浏览器驱动 |
| `@playwright/browser-webkit` | WebKit 浏览器驱动 |
| `playwright-chromium` | Chromium 便捷包 |
| `playwright-firefox` | Firefox 便捷包 |
| `playwright-webkit` | WebKit 便捷包 |
## 总结
Playwright 的架构设计体现了现代浏览器自动化的最佳实践：
1. **双进程模型**：灵活支持进程内和进程外执行
2. **统一 API**：跨浏览器提供一致的接口
3. **可扩展设计**：支持插件和 MCP 集成
4. **强大的调试能力**：内置跟踪、快照和 CLI 工具
---
## 客户端实现
### 相关页面
相关主题：[架构概览](#architecture-overview), [服务器端实现](#server-implementation), [定位器和选择器](#locators-and-selectors)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/client/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/page.ts)
- [packages/playwright-core/src/client/frame.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/frame.ts)
- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)
- [packages/playwright-core/src/client/elementHandle.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/elementHandle.ts)
- [packages/playwright-core/src/client/browserContext.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/browserContext.ts)
- [packages/playwright-core/src/client/channelOwner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/channelOwner.ts)
# 客户端实现
## 概述
Playwright 的客户端实现是库的核心组成部分，它为开发者提供了操作浏览器的编程接口。客户端层封装了与浏览器驱动程序通信的底层细节，提供了高级 API 用于页面导航、元素交互、表单填写、截图等操作。
Playwright 采用 **Channel（通道）** 架构进行客户端与服务端通信。客户端实现位于 `packages/playwright-core/src/client/` 目录下，包含了所有与浏览器交互的 TypeScript 类和接口。
## 架构概览
```mermaid
graph TD
A[开发者代码] --> B[Client API]
B --> C[Locator API]
B --> D[Page API]
B --> E[BrowserContext API]
C --> F[ChannelOwner]
D --> F
E --> F
F --> G[Playwright Driver]
G --> H[Browser Process]
G --> I[CDP Connection]
H --> J[Chromium/Firefox/WebKit]
```
客户端实现采用了分层架构设计：
| 层级 | 组件 | 职责 |
|------|------|------|
| API 层 | Page, Frame, Locator, ElementHandle | 提供高级用户接口 |
| 通道层 | ChannelOwner | 管理与驱动程序的通信通道 |
| 传输层 | Playwright Driver | 处理协议编解码和消息传递 |
## 核心组件
### ChannelOwner 基类
`ChannelOwner` 是所有客户端对象的基类，负责：
- 管理与 Playwright Driver 的底层通信通道
- 处理远程过程调用（RPC）
- 管理对象的生命周期
- 处理事件订阅和分发
所有客户端对象（Page、Frame、BrowserContext、Locator 等）都继承自 `ChannelOwner`，共享相同的通信机制和生命周期管理模式。
### Page 类
`Page` 代表浏览器中的一个页面，是最常用的交互入口。主要功能包括：
| 功能类别 | 方法示例 | 说明 |
|----------|----------|------|
| 导航 | goto, goBack, goForward, reload | 页面导航控制 |
| 交互 | click, fill, hover, type | 用户操作模拟 |
| 状态 | title, url, content | 获取页面信息 |
| 截图 | screenshot, pdf | 页面内容导出 |
| 等待 | waitForSelector, waitForLoadState | 条件等待机制 |
### Frame 类
`Frame` 表示页面中的一个 iframe 或主框架。Playwright 中的 Frame 实现支持：
- 嵌套框架的遍历和定位
- 框架级别的操作隔离
- 跨框架元素交互
### Locator API
Locator 是 Playwright 现代化的元素定位和交互方式，相比传统的 `ElementHandle`，Locator 具有以下优势：
| 特性 | ElementHandle | Locator |
|------|---------------|---------|
| 定位时机 | 创建时立即定位 | 操作时延迟定位 |
| 重试机制 | 无自动重试 | 自动重试直到元素可操作 |
| 稳定性 | 可能因 DOM 变化失效 | 每次操作重新定位 |
| 链式调用 | 不支持 | 支持链式定位 |
Locator 提供了丰富的方法链：
```typescript
// 链式定位示例
locator
.frameLocator('#iframe')
.locator('button.submit')
.click();
```
### ElementHandle 类
`ElementHandle` 代表 DOM 中的一个元素，提供直接的元素级操作：
- `click()` - 点击元素
- `fill()` - 填写表单
- `hover()` - 鼠标悬停
- `evaluate()` - 在元素上下文中执行 JavaScript
### BrowserContext 类
`BrowserContext` 表示一个独立的浏览器会话，具有以下特性：
| 特性 | 说明 |
|------|------|
| 隔离存储 | 独立的 Cookie、LocalStorage、SessionStorage |
| 并行执行 | 可创建多个 Context 同时运行 |
| 权限控制 | 可精细控制地理位置、摄像头等权限 |
| 隐私模式 | 每个 Context 相互隔离 |
## 对象关系图
```mermaid
graph LR
A[Browser] --> B[BrowserContext]
B --> C[Page]
C --> D[Frame]
D --> E[ElementHandle]
C --> F[Locator]
F -.-> E
B --> G[BrowserServer]
B --> H[Tracing]
```
核心对象关系：
- **Browser** 可以包含多个独立的 **BrowserContext**
- 每个 **BrowserContext** 可以包含多个 **Page**
- **Page** 包含一个主 **Frame** 和可能的嵌套 **Frame**
- **ElementHandle** 和 **Locator** 都用于定位和操作 **Frame** 中的 DOM 元素
## 生命周期管理
### 对象创建
```mermaid
sequenceDiagram
participant User as 用户代码
participant API as Client API
participant Channel as ChannelOwner
participant Driver as Playwright Driver
User->>API: new Page(channel)
API->>Channel: 初始化通道
Channel->>Driver: 创建远程对象
Driver-->>Channel: 返回对象引用
Channel-->>API: 返回实例
API-->>User: Page 实例
```
### 资源释放
客户端对象在以下情况下会被自动或手动释放：
1. **显式关闭**：调用 `page.close()`, `context.close()`
2. **作用域结束**：在测试框架中，测试完成后自动清理
3. **强制关闭**：调用 `browser.close()` 关闭整个浏览器
## 事件系统
客户端实现了基于订阅的事件系统：
| 事件类型 | 触发时机 | 使用场景 |
|----------|----------|----------|
| `load` | 页面加载完成 | 等待页面就绪 |
| `domcontentloaded` | DOM 解析完成 | 快速验证 |
| `console` | 控制台消息 | 调试和日志 |
| `request` | 网络请求发起 | 流量监控 |
| `response` | 网络响应接收 | 断言验证 |
| `crash` | 页面崩溃 | 错误处理 |
## 等待机制
Playwright 客户端提供了智能的等待机制来处理异步操作：
### 内置等待
| 等待类型 | 说明 |
|----------|------|
| 导航等待 | 自动等待页面加载完成 |
| 元素等待 | 等待元素出现、可见、可点击 |
| 函数等待 | 等待条件满足 |
| 超时控制 | 可配置全局或单次超时 |
### 自定义等待
```typescript
// 等待元素包含特定文本
await page.locator('div.status').waitFor({
hasText: 'Success'
});
// 等待函数返回 true
await page.waitForFunction(() => {
return document.querySelectorAll('li').length > 10;
});
```
## 错误处理
客户端实现了完善的错误处理机制：
| 错误类型 | 触发条件 | 处理建议 |
|----------|----------|----------|
| TimeoutError | 操作超时 | 增加超时时间或检查页面状态 |
| TargetClosedError | 目标已关闭 | 检查对象生命周期 |
| NotFoundError | 元素未找到 | 验证选择器或等待条件 |
| NavigationError | 导航失败 | 检查网络或 URL |
## 与 CLI 的集成
Playwright CLI (`playwright-cli`) 提供了命令行界面的浏览器自动化能力，与客户端 API 共享相同的底层实现：
```bash
# CLI 命令对应客户端 API
playwright-cli click e15 # => page.locator('#selector').click()
playwright-cli screenshot # => page.screenshot()
playwright-cli goto url # => page.goto(url)
```
CLI 和客户端共享相同的 Page、Frame、Locator 实现，保证了行为一致性。
## 源码结构
```
packages/playwright-core/src/client/
├── channelOwner.ts # 基础通道所有者类
├── page.ts # 页面实现
├── frame.ts # 框架实现
├── locator.ts # 定位器实现
├── elementHandle.ts # 元素句柄实现
├── browserContext.ts # 浏览器上下文
├── browser.ts # 浏览器实例
└── ...
```
## 总结
Playwright 的客户端实现提供了一套完整、高层次的浏览器自动化 API。其核心设计理念包括：
1. **统一通道架构**：所有客户端对象通过 ChannelOwner 与驱动程序通信
2. **延迟定位**：Locator 机制确保元素操作的稳定性
3. **智能等待**：内置自动等待，减少 flaky tests
4. **丰富的事件系统**：支持各种页面状态和行为的监控
5. **完善的错误处理**：清晰的错误类型和合理的默认行为
这套客户端架构使得开发者能够以声明式的方式编写浏览器自动化测试和脚本，同时保证了跨浏览器的一致性。
---
## 服务器端实现
### 相关页面
相关主题：[架构概览](#architecture-overview), [客户端实现](#client-implementation), [浏览器支持](#browser-support)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/server/browser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browser.ts)
- [packages/playwright-core/src/server/browserContext.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browserContext.ts)
- [packages/playwright-core/src/server/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/page.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/server/network.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/network.ts)
- [packages/playwright-core/src/server/index.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/index.ts)
# 服务器端实现
## 概述
Playwright 的服务器端实现是框架的核心架构层，负责在 Node.js 环境中管理与浏览器实例的通信。该层封装了浏览器启动、页面操作、网络拦截、上下文隔离等底层功能，为上层 API 提供统一的接口抽象。
服务器端实现的主要职责包括：
- 管理浏览器进程的生命周期
- 处理跨进程通信协议
- 协调浏览器上下文和页面状态
- 处理网络请求和响应
- 分发器（Dispatcher）模式的消息路由
资料来源：[packages/playwright-core/src/server/index.ts:1-20]()
## 架构设计
### 核心组件关系
```mermaid
graph TD
A[playwright-core] --> B[Server Index]
B --> C[Browser]
B --> D[BrowserContext]
B --> E[Page]
B --> F[Network]
C --> D
D --> E
E --> F
B --> G[Dispatcher]
G --> C
G --> D
G --> E
G --> F
```
### 层次结构
Playwright 服务器端采用分层架构设计，从底层到高层依次为：
| 层级 | 组件 | 职责 |
|------|------|------|
| 传输层 | Protocol 协议 | 定义客户端与服务端的消息格式 |
| 路由层 | Dispatcher | 消息分发与路由 |
| 业务层 | Browser/Context/Page | 核心业务逻辑 |
| 实现层 | Browser API | 与底层浏览器通信 |
资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts:1-30]()
## Browser 服务器实现
### Browser 类职责
Browser 类是服务器端的核心入口，负责以下功能：
- 浏览器进程启动与关闭
- 浏览器类型检测（Chromium/Firefox/WebKit）
- 版本信息管理
- 发射器（Launch Server）管理
### 主要方法
```typescript
class Browser {
// 启动浏览器
async launch(options: LaunchOptions): Promise
// 连接已存在的浏览器
async connect(wsEndpoint: string): Promise
// 创建新上下文
async newContext(options?: ContextOptions): Promise
// 关闭浏览器
async close(): Promise
// 获取所有上下文
contexts(): BrowserContext[]
}
```
资料来源：[packages/playwright-core/src/server/browser.ts:30-100]()
### 浏览器上下文管理
```mermaid
graph LR
A[Browser] -->|创建| B[BrowserContext 1]
A -->|创建| C[BrowserContext 2]
A -->|创建| D[BrowserContext N]
B --> E[Page 1]
B --> F[Page 2]
C --> G[Page 3]
D --> H[Page 4]
```
## BrowserContext 服务器实现
BrowserContext 代表一个独立的浏览器会话，每个上下文拥有独立的存储空间、Cookie、缓存等。
### 核心特性
| 特性 | 说明 |
|------|------|
| 隔离存储 | 独立的 localStorage、sessionStorage |
| Cookie 隔离 | 每个上下文维护独立的 Cookie 存储 |
| 权限管理 | 可独立控制地理位置、摄像头等权限 |
| 代理配置 | 支持为单个上下文配置代理服务器 |
### 主要方法
```typescript
class BrowserContext {
// 创建新页面
async newPage(): Promise
// 添加 cookies
async addCookies(cookies: Cookie[]): Promise
// 获取 cookies
async cookies(urls?: string[]): Promise
// 清除所有 cookies
async clearCookies(): Promise
// 授权权限
async grantPermissions(permissions: string[]): Promise
// 截图
async screenshot(options?: ScreenshotOptions): Promise
// 关闭上下文
async close(): Promise
}
```
资料来源：[packages/playwright-core/src/server/browserContext.ts:50-150]()
## Page 服务器实现
Page 类代表浏览器中的一个标签页或框架，是与网页内容交互的主要接口。
### 元素定位与交互
```typescript
class Page {
// 元素定位
locator(selector: string): Locator
getByRole(role: AriaRole, options?: GetByRoleOptions): Locator
getByText(text: string, options?: GetByTextOptions): Locator
getByTestId(testId: string): Locator
// 交互操作
async click(selector: string, options?: ClickOptions): Promise
async fill(selector: string, value: string): Promise
async type(selector: string, text: string, options?: TypeOptions): Promise
async hover(selector: string): Promise
async dragAndDrop(source: string, target: string): Promise
}
```
### 导航操作
```typescript
class Page {
// 页面导航
async goto(url: string, options?: GotoOptions): Promise
async goBack(options?: NavigationOptions): Promise
async goForward(options?: NavigationOptions): Promise
async reload(options?: NavigationOptions): Promise
// 等待导航完成
async waitForNavigation(options?: WaitForNavigationOptions): Promise
// 事件监听
async waitForLoadState(state: LoadState): Promise
waitForURL(url: string | RegExp): Promise
}
```
资料来源：[packages/playwright-core/src/server/page.ts:100-250]()
## Dispatcher 分发器
Dispatcher 是 Playwright 服务器端的消息路由核心，采用发布-订阅模式处理客户端请求。
### 工作原理
```mermaid
graph TD
A[客户端请求] --> B[Protocol Handler]
B --> C[Dispatcher]
C --> D{路由判断}
D -->|Browser| E[BrowserDispatcher]
D -->|Context| F[BrowserContextDispatcher]
D -->|Page| G[PageDispatcher]
D -->|Network| H[NetworkDispatcher]
E --> I[执行结果]
F --> I
G --> I
H --> I
```
### 消息流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Protocol as Protocol Handler
participant Dispatcher as Dispatcher
participant Handler as 业务处理器
Client->>Protocol: 发送命令
Protocol->>Dispatcher: 路由消息
Dispatcher->>Handler: 分发请求
Handler->>Handler: 处理业务逻辑
Handler-->>Dispatcher: 返回结果
Dispatcher-->>Protocol: 格式化响应
Protocol-->>Client: 返回执行结果
```
### Dispatcher 基类
```typescript
class Dispatcher {
// 构造函数接收根对象和唯一标识
constructor(scope: object, uid: number)
// 内部对象引用
protected _scope: object
protected _uid: number
// 回调方法
protected _dispatchEvent(method: string, params: any): void
protected _writeObjectToLog(logName: string, obj: any): void
}
```
资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts:30-80]()
## Network 网络管理
Network 模块负责处理页面的网络请求和响应，支持请求拦截、修改、模拟等功能。
### 网络拦截
```typescript
class Route {
// 继续请求（可选修改）
async continue(options?: ContinueRequestOptions): Promise
// 完成响应
async fulfill(response: Partial): Promise
// 中止请求
async abort(errorCode?: string): Promise
}
class Request {
// 获取请求信息
url(): string
method(): string
headers(): Record
postData(): string | null
// 响应对象
response(): Response | null
}
```
### 路由规则配置
| 方法 | 说明 |
|------|------|
| `route(url, handler)` | 为匹配 URL 的请求设置处理函数 |
| `unroute(url, handler?)` | 移除路由规则 |
| `routeList()` | 列出所有活动路由 |
资料来源：[packages/playwright-core/src/server/network.ts:50-120]()
## 服务器启动流程
```mermaid
graph TD
A[导入 Server Index] --> B[初始化传输层]
B --> C[加载浏览器驱动]
C --> D{检查浏览器安装}
D -->|未安装| E[触发自动安装]
D -->|已安装| F[启动浏览器进程]
F --> G[建立 WebSocket 连接]
G --> H[初始化 Dispatcher]
H --> I[导出公共 API]
I --> J[服务器就绪]
```
## 关键配置选项
### 浏览器启动配置
| 选项 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `headless` | boolean | 是否无头模式运行 | true |
| `args` | string[] | 浏览器启动参数 | [] |
| `proxy` | ProxyOptions | 代理服务器配置 | undefined |
| `viewport` | Viewport | 视口大小 | 800x600 |
| `userAgent` | string | 用户代理字符串 | 浏览器默认 |
| `timeout` | number | 操作超时时间(毫秒) | 30000 |
### 上下文配置
| 选项 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `storageState` | string/StorageState | 预加载存储状态 | undefined |
| `permissions` | string[] | 默认授权的权限 | [] |
| `geolocation` | Geolocation | 地理位置模拟 | undefined |
| `ignoreHTTPSErrors` | boolean | 忽略 HTTPS 错误 | false |
| `baseURL` | string | 相对 URL 的基础地址 | undefined |
资料来源：[packages/playwright-core/src/server/browserContext.ts:200-280]()
## 与客户端的通信
Playwright 服务器端通过 CDP（Chrome DevTools Protocol）协议与浏览器通信，同时通过自定义协议与 Node.js 客户端交互。
```mermaid
graph LR
A[Node.js 客户端] <-->|Playwright Protocol| B[Server]
B <-->|CDP Protocol| C[Chromium]
B <-->|CDP Protocol| D[Firefox]
B <-->|WebKit Protocol| E[WebKit]
```
## 扩展与定制
### 自定义浏览器驱动
开发者可以通过继承 Browser 类来支持自定义浏览器：
```typescript
class CustomBrowser extends Browser {
protected async _launchServer(): Promise {
// 自定义启动逻辑
}
}
```
### 添加新的协议处理器
通过扩展 Dispatcher 基类，可以添加新的协议处理能力：
```typescript
class CustomDispatcher extends Dispatcher {
constructor(scope: object, uid: number) {
super(scope, uid);
}
// 实现自定义方法
async customMethod(params: any): Promise {
// 处理逻辑
}
}
```
## 最佳实践
### 资源管理
- 及时关闭不再使用的 Page、BrowserContext
- 使用 `async/await` 确保资源释放
- 设置合理的超时时间避免资源泄漏
### 错误处理
```typescript
try {
await page.goto('https://example.com', { timeout: 10000 });
} catch (error) {
if (error instanceof TimeoutError) {
// 处理超时
} else if (error instanceof net.Error) {
// 处理网络错误
}
}
```
### 并发控制
| 场景 | 推荐做法 |
|------|----------|
| 多页面并发 | 使用多个 BrowserContext |
| 批量操作 | 控制并发数量避免资源耗尽 |
| 资源密集型 | 考虑使用 `browser.close()` 释放资源 |
## 相关模块索引
| 模块路径 | 职责 |
|----------|------|
| `src/server/browser.ts` | 浏览器进程管理 |
| `src/server/browserContext.ts` | 会话上下文管理 |
| `src/server/page.ts` | 页面操作与交互 |
| `src/server/dispatchers/dispatcher.ts` | 消息路由分发 |
| `src/server/network.ts` | 网络请求拦截 |
| `src/server/index.ts` | 服务端导出入口 |
---
本页面持续更新中，如有问题请提交 Issue 或 Pull Request。
---
## 浏览器支持
### 相关页面
相关主题：[架构概览](#architecture-overview), [服务器端实现](#server-implementation)
相关源码文件
以下源码文件用于生成本页说明：
- [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/ffBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/firefox/ffBrowser.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/browserType.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browserType.ts)
- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)
- [packages/trace-viewer/src/ui/browserFrame.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/browserFrame.tsx)
- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)
- [packages/playwright-core/src/server/codegen/csharp.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/codegen/csharp.ts)
# 浏览器支持
Playwright 是一个跨浏览器自动化测试框架，支持三大主流浏览器引擎：Chromium、Firefox 和 WebKit。每个浏览器都通过独立的实现模块进行抽象和管理，使得上层 API 能够以统一的方式与不同浏览器进行交互。
## 支持的浏览器类型
Playwright 原生支持以下三种浏览器：
| 浏览器 | 渲染引擎 | 协议实现 | 源码目录 |
|--------|----------|----------|----------|
| Chromium | Blink/V8 | Chrome DevTools Protocol (CDP) | `packages/playwright-core/src/server/chromium/` |
| Firefox | Gecko/SpiderMonkey | Firefox DevTools Protocol (FDP) | `packages/playwright-core/src/server/firefox/` |
| WebKit | WebKit/JavaScriptCore | Apple WebKit Protocol (WKP) | `packages/playwright-core/src/server/webkit/` |
资料来源：[packages/playwright-core/src/server/browserType.ts]()
## 浏览器启动流程
Playwright 的浏览器启动遵循统一的工厂模式，通过 `browserType.ts` 中的 `launch()` 方法创建浏览器实例。
```mermaid
graph TD
A[launchBrowser] --> B{浏览器类型}
B -->|Chromium| C[createChromiumBrowser]
B -->|Firefox| D[createFirefoxBrowser]
B -->|WebKit| E[createWebKitBrowser]
C --> F[连接 CDP 端口]
D --> G[启动 Juggler 进程]
E --> H[连接 WebKit 调试器]
F --> I[返回 Browser 实例]
G --> I
H --> I
```
### 启动参数配置
`launch()` 方法支持丰富的配置选项：
| 参数 | 类型 | 说明 |
|------|------|------|
| `headless` | boolean | 是否以无头模式运行，默认 `true` |
| `channel` | string | 浏览器渠道，如 `chrome`, `chrome-beta`, `msedge` |
| `args` | string[] | 传递给浏览器的额外命令行参数 |
| `proxy` | object | 代理服务器配置 |
| `downloadPath` | string | 下载文件保存路径 |
| `viewport` | object | 视口尺寸配置 |
| `userAgent` | string | 自定义 User-Agent |
| `slowMo` | number | 操作延迟（毫秒），用于调试 |
资料来源：[packages/playwright-core/src/server/browserType.ts]()
## 浏览器会话管理
### CLI 会话管理
Playwright CLI (`playwright-cli`) 提供了完整的浏览器会话管理能力：
```bash
# 创建新的命名会话
playwright-cli -s=mysession open https://example.com
# 使用持久化配置文件
playwright-cli -s=mysession open https://example.com --persistent
# 删除会话数据
playwright-cli -s=mysession delete-data
# 关闭所有浏览器
playwright-cli close-all
# 强制终止所有浏览器进程
playwright-cli kill-all
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md]()
### 会话状态持久化
浏览器状态可以通过以下方式保存和恢复：
| 存储类型 | 命令 | 说明 |
|----------|------|------|
| 完整状态 | `state-save`, `state-load` | 保存/恢复 cookies、localStorage、sessionStorage |
| Cookies | `cookie-list`, `cookie-set`, `cookie-delete` | 独立管理 cookies |
| LocalStorage | `localstorage-list`, `localstorage-set` | 键值对存储 |
| SessionStorage | `sessionstorage-list`, `sessionstorage-set` | 会话级存储 |
```bash
# 保存当前状态
playwright-cli state-save auth.json
# 恢复状态
playwright-cli state-load auth.json
```
## 浏览器帧组件
Trace Viewer 使用 `browserFrame.tsx` 组件渲染浏览器外观模拟，该组件展示地址栏、菜单栏等 UI 元素：
```tsx
{url || 'about:blank'}
{url && }
```
资料来源：[packages/trace-viewer/src/ui/browserFrame.tsx]()
## 网络路由与拦截
Playwright 支持对网络请求进行拦截和修改：
```bash
# 拦截特定 URL 并返回自定义状态
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 内置了基于 ARIA 角色的定位器支持，通过 `roleUtils.ts` 实现：
| HTML 元素 | 默认 ARIA 角色 |
|-----------|---------------|
| `BUTTON` | button |
| `A` | link |
| `INPUT[type="search"]` | searchbox |
| `INPUT[type="email"]` | textbox |
| `SELECT` | listbox |
| `DIALOG` | dialog |
| `FORM` | form (仅当有显式可访问名称时) |
| `IMG[alt=""]` | presentation |
| `IMG[alt!=""]` | img |
| `H1-H6` | heading |
| `HEADER` | banner |
| `FOOTER` | contentinfo |
```typescript
'INPUT': (e: Element) => {
const type = (e as HTMLInputElement).type.toLowerCase();
if (type === 'search')
return e.hasAttribute('list') ? 'combobox' : 'searchbox';
if (['email', 'tel', 'url'].includes(type))
return 'textbox';
}
```
资料来源：[packages/injected/src/roleUtils.ts]()
### 元素交互命令
Playwright CLI 支持多种元素定位方式：
```bash
# 使用快照引用
playwright-cli click e15
# CSS 选择器
playwright-cli click "#main > button.submit"
# 角色定位器
playwright-cli click "getByRole('button', { name: 'Submit' })"
# 测试 ID
playwright-cli click "getByTestId('submit-button')"
```
## 代码生成中的浏览器支持
代码生成模块针对不同浏览器生成优化代码。以 C# 为例：
```csharp
// 检测是否为新页面操作
if (action.name === 'openPage' || action.name === 'closePage')
return '';
// 生成页面变量
var page = await context.NewPageAsync();
// 根据 URL 导航
if (action.url)
await page.GotoAsync(action.url);
// 处理对话框事件
void page_Dialog_EventHandler(object sender, IDialog dialog)
{
dialog.DismissAsync();
}
```
资料来源：[packages/playwright-core/src/server/codegen/csharp.ts]()
## Trace 与浏览器状态
Trace Viewer 能够在不打开浏览器的情况下查看浏览器状态快照：
```bash
# 打开 trace 文件
npx playwright trace open test-results/my-test/trace.zip
# 查看特定操作后的快照
npx playwright trace snapshot 12
# 获取 DOM 内容
npx playwright trace snapshot 12 -- eval "document.body.outerHTML"
```
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()
### Trace 元数据展示
Trace Viewer 通过 `MetadataView` 组件展示浏览器元数据：
| 元数据字段 | 说明 |
|-----------|------|
| playwrightVersion | Playwright 版本 |
| userAgent | 用户代理字符串 |
| baseURL | 基础 URL 配置 |
| viewport | 视口尺寸 (width × height) |
| isMobile | 是否移动设备模拟 |
| deviceScaleFactor | 设备像素比 |
资料来源：[packages/trace-viewer/src/ui/metadataView.tsx]()
## 浏览器环境变量
| 环境变量 | 作用 |
|----------|------|
| `PLAYWRIGHT_CLI_SESSION` | 设置默认浏览器会话名称 |
| `PLAYWRIGHT_HTML_OPEN` | 控制 HTML 报告打开行为 |
| `PLAYWRIGHT_BROWSERS_PATH` | 浏览器可执行文件存储路径 |
## 最佳实践
### 会话命名规范
```bash
# 推荐：清晰的命名
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com
# 避免：通用命名
playwright-cli -s=s1 open https://github.com
```
### 清理策略
| 场景 | 建议操作 |
|------|----------|
| 正常完成 | 使用 `close` 优雅关闭 |
| 异常退出 | 使用 `kill-all` 强制终止 |
| 磁盘空间不足 | 使用 `delete-data` 清理旧会话 |
### 无头模式与有头模式
```bash
# 无头模式（默认）
playwright-cli open https://example.com
# 有头模式（可见浏览器窗口）
playwright-cli open https://example.com --headed
```
## 架构总结
Playwright 的浏览器支持层采用适配器模式设计：
```mermaid
graph LR
A[用户代码] --> B[Playwright API]
B --> C[BrowserType 工厂]
C --> D[ChromiumBrowser]
C --> E[FirefoxBrowser]
C --> E --> F[Juggler 桥接]
C --> G[WebKitBrowser]
D --> H[CDP 连接]
G --> I[WKP 连接]
```
这种设计使得：
- 新增浏览器支持只需实现新的适配器
- 上层 API 保持稳定
- 协议差异被隔离在各自的实现模块中
---
## 测试框架
### 相关页面
相关主题：[断言系统](#assertions), [定位器和选择器](#locators-and-selectors)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright/src/common/config.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/config.ts)
- [packages/playwright/src/common/fixtures.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/fixtures.ts)
- [packages/playwright/src/common/test.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/test.ts)
- [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/worker/workerMain.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/worker/workerMain.ts)
- [packages/playwright/src/common/poolBuilder.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/poolBuilder.ts)
# 测试框架
Playwright 测试框架是微软开发的一个端到端测试框架，提供了用于编写、管理和执行浏览器自动化测试的完整工具链。该框架支持多浏览器（Chromium、Firefox、WebKit）、多语言（JavaScript/TypeScript、Python、Java、.NET）以及丰富的断言和定位器 API。
## 架构概述
Playwright 测试框架采用分层架构设计，核心组件包括配置管理、Fixtures 系统、测试运行器和 Worker 进程池。
```mermaid
graph TD
A[Playwright Test CLI] --> B[Test Runner]
B --> C[Configuration]
B --> D[Dispatcher]
D --> E[Worker Pool]
E --> F[Worker Process 1]
E --> G[Worker Process 2]
E --> H[Worker Process N]
F --> I[Browser Context]
G --> J[Browser Context]
I --> K[Test Fixture]
J --> L[Test Fixture]
```
## 核心组件
### 配置系统
配置系统负责管理测试运行的全局参数，包括测试目录、测试超时、并发配置等。
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| testDir | 测试文件目录 | 当前工作目录 |
| timeout | 单个测试超时时间 | 30000ms |
| retries | 失败测试重试次数 | 0 |
| workers | 并发 Worker 数量 | CPU 核心数 |
| reporter | 测试报告格式 | list |
配置通过 `playwright.config.ts` 文件定义，框架在启动时加载并验证配置的有效性。资料来源：[packages/playwright/src/common/config.ts]()
### Fixtures 系统
Fixtures 是 Playwright 测试框架的核心特性之一，用于在测试运行时提供上下文和资源管理。Fixtures 可以是浏览器上下文、页面对象、认证状态或任何测试所需的数据。
```typescript
// Fixtures 定义示例结构
export interface TestFixtures {
page: Page;
context: BrowserContext;
request: APIRequestContext;
}
```
Fixtures 支持以下特性：
- **自动生命周期管理**：自动处理资源的创建和销毁
- **依赖注入**：Fixtures 可以依赖其他 Fixtures
- **参数化支持**：支持动态参数化配置
- **作用域控制**：可设置 Function Scope（Function、Test、Worker、Project）
资料来源：[packages/playwright/src/common/fixtures.ts]()
### 测试定义
测试通过 `test` 函数定义，支持分组、标注和元数据管理。
```typescript
test.describe('测试分组', () => {
test.beforeEach(async ({ page }) => {
// 前置条件
});
test('示例测试', async ({ page }) => {
await page.goto('https://example.com');
// 测试步骤
});
test.afterEach(async ({ page }) => {
// 清理工作
});
});
```
资料来源：[packages/playwright/src/common/test.ts]()
## 运行机制
### 测试运行器
测试运行器（Test Runner）是框架的核心调度引擎，负责解析配置、加载测试文件并协调整个测试执行流程。
```mermaid
graph LR
A[Load Config] --> B[Discover Tests]
B --> C[Build Worker Pool]
C --> D[Dispatch Tests]
D --> E[Execute in Worker]
E --> F[Report Results]
F --> G[Cleanup]
```
运行器的主要职责包括：
1. 解析命令行参数和配置文件
2. 发现并加载测试文件
3. 构建 Worker 进程池
4. 分发测试任务到 Worker
5. 收集并汇总测试结果
资料来源：[packages/playwright/src/runner/testRunner.ts]()
### 分发器
分发器（Dispatcher）负责将测试任务分配给可用的 Worker 进程，支持智能负载均衡和失败重试机制。
| 特性 | 说明 |
|------|------|
| 动态分配 | 根据 Worker 负载动态分配测试 |
| 失败重试 | 支持按测试或全局配置重试 |
| 超时控制 | 监控测试执行时间 |
| 进度追踪 | 实时汇报测试执行进度 |
分发器采用基于队列的模型，新测试被发现后立即加入执行队列。每个 Worker 进程独立运行，可以并行执行多个测试。
资料来源：[packages/playwright/src/runner/dispatcher.ts]()
### Worker 进程
Worker 进程是测试代码的实际执行环境，每个 Worker 拥有独立的浏览器实例和上下文池。
```mermaid
graph TD
A[Worker Main] --> B[Load Fixtures]
B --> C[Create Browser Context]
C --> D[Run Test]
D --> E[Assert Results]
E --> F{Cleanup}
F --> G[Destroy Context]
G --> H[Ready for Next Test]
```
Worker 的生命周期管理包括：
- 初始化阶段：加载必要的 Fixtures 和依赖
- 执行阶段：运行单个测试用例
- 清理阶段：销毁浏览器上下文，释放资源
资料来源：[packages/playwright/src/worker/workerMain.ts]()
### 进程池构建器
进程池构建器（Pool Builder）负责创建和管理 Worker 进程池，优化资源利用率。
```mermaid
graph TD
A[Pool Request] --> B{Check Pool}
B -->|有可用 Worker| C[Reuse Worker]
B -->|无可用 Worker| D[Create Worker]
D --> E[Initialize]
C --> F[Execute Test]
E --> F
F --> G[Return to Pool]
```
进程池支持以下配置策略：
| 策略 | 说明 |
|------|------|
| 并发数量 | 最大同时运行的 Worker 数 |
| 空闲超时 | 空闲 Worker 的存活时间 |
| 启动延迟 | 预热 Worker 的延迟配置 |
资料来源：[packages/playwright/src/common/poolBuilder.ts]()
## 追踪与调试
### 追踪查看器
Playwright 提供追踪查看器（Trace Viewer）用于回放和调试测试执行过程。追踪文件是包含快照、网络请求、控制台日志的 ZIP 包。
```bash
# 打开追踪文件
npx playwright trace open
# 查看特定 action 的详细信息
npx playwright trace action
# 获取 DOM 快照
npx playwright trace snapshot
```
追踪查看器支持以下功能：
- 时间线视图：可视化测试执行的时间轴
- 快照回放：查看每一步操作后的页面状态
- 网络监控：分析请求和响应详情
- 控制台日志：捕获 JavaScript 控制台输出
- 错误追踪：定位测试失败的具体原因
资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx]()
### CLI 工具
playwright-cli 提供命令行界面用于调试和探索性测试。
| 命令 | 功能 |
|------|------|
| `goto` | 导航到指定 URL |
| `click` | 点击页面元素 |
| `snapshot` | 获取页面快照 |
| `screenshot` | 截取页面截图 |
| `pdf` | 生成 PDF 文档 |
| `console` | 查看控制台输出 |
| `requests` | 查看网络请求 |
| `eval` | 执行 JavaScript 代码 |
```bash
# 启动调试会话
playwright-cli open https://example.com
# 获取带引用标记的快照
playwright-cli snapshot
# 使用引用标记交互
playwright-cli click e15
```
## 报告生成
### HTML 报告器
Playwright 生成详细的 HTML 测试报告，包含测试结果统计、失败原因分析、截图对比等信息。
报告界面主要组件：
| 组件 | 说明 |
|------|------|
| 测试摘要 | 通过/失败/跳过统计 |
| 测试列表 | 按项目分组的测试项 |
| 测试详情 | 单个测试的执行信息 |
| 元数据视图 | 测试环境配置信息 |
资料来源：[packages/html-reporter/src/testCaseView.tsx]()
报告支持以下数据展示：
- 测试执行时长（毫秒转换显示）
- 测试标签和项目分组
- 重试次数和历史记录
- 注释和标注信息
- 追踪链接（跳转到 Trace Viewer）
## 浏览器支持
Playwright 支持三大主流浏览器引擎：
| 浏览器 | 引擎 | 平台支持 |
|--------|------|----------|
| Chromium | Blink | Windows、macOS、Linux |
| Firefox | Gecko | Windows、macOS、Linux |
| WebKit | WebKit | Windows、macOS、Linux |
每个浏览器通过独立的项目（Project）配置，支持不同的视口大小、用户代理、设备模拟等参数。
## 相关资源
- 官方文档：https://playwright.dev
- 追踪查看器：https://trace.playwright.dev
- 测试配置参考：Playwright 配置文件规范
- Fixtures API：自定义 Fixtures 开发指南
---
## 定位器和选择器
### 相关页面
相关主题：[客户端实现](#client-implementation), [测试框架](#test-framework)
相关源码文件
以下源码文件用于生成本页说明：
- [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/roleSelectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleSelectorEngine.ts)
- [packages/injected/src/selectorGenerator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorGenerator.ts)
- [packages/injected/src/selectorEvaluator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEvaluator.ts)
- [packages/isomorphic/locatorUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/locatorUtils.ts)
# 定位器和选择器
## 概述
Playwright 中的**定位器（Locator）**和**选择器（Selector）**是自动化浏览器交互的核心组件。定位器是 Playwright 推荐的元素定位方式，提供了比传统 `Page.locator()` API 更加健壮的元素查找机制。选择器则是用于匹配 DOM 元素的字符串表达式，支持多种定位策略。
定位器与选择器的关系可以通过以下架构图说明：
```mermaid
graph TD
A[用户代码] --> B[Locator API]
B --> C{查找策略}
C --> D[CSS 选择器]
C --> E[Role 选择器]
C --> F[文本选择器]
C --> G[测试ID选择器]
C --> H[XPath 选择器]
D --> I[selectorEngine.ts]
E --> J[roleSelectorEngine.ts]
F --> I
G --> I
H --> I
I --> K[selectorEvaluator.ts]
K --> L[DOM 元素]
style A fill:#e1f5ff
style L fill:#c8e6c9
```
## 核心概念
### 定位器（Locator）
定位器是 Playwright 用来定位页面元素的异步可重用对象。与传统的 `querySelector` 不同，定位器具有以下特点：
| 特性 | 说明 |
|------|------|
| **自动重试** | 元素未找到时自动等待并重试 |
| **可复用** | 定位器对象可以多次使用 |
| **惰性执行** | 定位器在交互时才执行查询 |
| **可组合** | 支持链式调用构建复杂定位器 |
定位器 API 提供了丰富的交互方法，包括 `click()`、`fill()`、`hover()`、`getByRole()` 等。
### 选择器（Selector）
选择器是用于匹配 DOM 元素的字符串表达式。Playwright 支持多种选择器类型：
| 类型 | 语法示例 | 说明 |
|------|----------|------|
| CSS | `#id`, `.class`, `div > span` | 标准 CSS 选择器 |
| Role | `getByRole('button')` | ARIA 角色选择器 |
| 文本 | `getByText('Submit')` | 按文本内容定位 |
| 测试ID | `getByTestId('submit')` | data-testid 属性 |
| XPath | `xpath=//button` | XPath 表达式 |
| 混合 | `role=button[name='Login']` | 属性组合 |
## 源码架构
### 模块职责划分
```mermaid
graph LR
A[packages/playwright-core
客户端封装] --> B[packages/isomorphic
跨平台工具]
B --> C[packages/injected
注入脚本]
A1[locator.ts] --> B1[locatorUtils.ts]
C1[selectorEngine.ts] --> C4[selectorEvaluator.ts]
C2[roleSelectorEngine.ts] --> C4
C3[selectorGenerator.ts] --> C4
style A fill:#fff3e0
style B fill:#e3f2fd
style C fill:#f3e5f5
```
### 关键源文件
| 文件路径 | 职责 |
|----------|------|
| `client/locator.ts` | 定义Locator类，提供元素交互API |
| `injected/selectorEngine.ts` | 实现基础选择器引擎 |
| `injected/roleSelectorEngine.ts` | 实现ARIA角色选择器引擎 |
| `injected/selectorGenerator.ts` | 自动生成健壮的选择器 |
| `injected/selectorEvaluator.ts` | 评估和验证选择器匹配 |
| `isomorphic/locatorUtils.ts` | 提供跨平台的定位器工具函数 |
## 选择器引擎
### 选择器引擎架构
选择器引擎是 Playwright 解析和执行选择器的核心组件，采用插件化架构支持多种选择器类型。
```mermaid
graph TD
A[选择器字符串] --> B[解析器]
B --> C{选择器类型}
C -->|CSS| D[CSS Engine]
C -->|role| E[Role Engine]
C -->|text| F[Text Engine]
C -->|test-id| G[TestId Engine]
C -->|xpath| H[XPath Engine]
D --> I[querySelector]
E --> J[roleSelectorEngine.ts]
F --> K[文本匹配]
G --> L[data-testid]
H --> M[XPath 评估]
I --> N[selectorEvaluator.ts]
J --> N
K --> N
L --> N
M --> N
N --> O[匹配结果]
```
### 角色选择器引擎
角色选择器（Role Selector）是 Playwright 推荐的元素定位方式，基于 ARIA 规范实现。
```mermaid
graph LR
A[getByRole
'button'] --> B[roleSelectorEngine.ts]
B --> C[ARIA 属性检查]
C --> D{匹配类型}
D -->|implicit| E[通过角色推断]
D -->|explicit| F[通过 aria-* 属性]
E --> G[返回元素]
F --> G
style A fill:#e1f5ff
style G fill:#c8e6c9
```
角色选择器支持的选项参数：
| 参数 | 类型 | 说明 |
|------|------|------|
| `name` | string \| RegExp | 角色关联的 accessible name |
| `level` | number | ARIA level（如 heading 角色） |
| `checked` | boolean | checkbox/radio 的选中状态 |
| `pressed` | boolean | button 的按下状态 |
| `expanded` | boolean | 展开/折叠状态 |
| `selected` | boolean | option 的选中状态 |
## Locator API
### 创建定位器
定位器可以通过多种方式创建：
```typescript
// 通过 CSS 选择器
page.locator('css=.submit-button');
// 通过角色
page.locator('role=button[name="Submit"]');
// 通过文本内容
page.locator('text=Click here');
// 通过测试ID
page.locator('test-id=submit-btn');
// 链式定位器
page.locator('form').locator('button[type="submit"]');
```
### 交互方法
| 方法 | 说明 | 示例 |
|------|------|------|
| `click()` | 点击元素 | `locator.click()` |
| `dblclick()` | 双击元素 | `locator.dblclick()` |
| `fill()` | 填充输入框 | `locator.fill('text')` |
| `hover()` | 鼠标悬停 | `locator.hover()` |
| `type()` | 逐字符输入 | `locator.type('hello')` |
| `press()` | 按下按键 | `locator.press('Enter')` |
| `check()` | 勾选复选框 | `locator.check()` |
| `selectOption()` | 选择下拉选项 | `locator.selectOption('value')` |
| `waitFor()` | 等待元素可见 | `locator.waitFor()` |
| `getAttribute()` | 获取属性值 | `locator.getAttribute('href')` |
### 过滤与断言
定位器支持通过 `filter()` 方法进一步过滤元素：
```typescript
// 过滤条件示例
page.locator('li').filter({ hasText: 'Item 1' });
page.locator('button').filter({ hasNotText: 'Disabled' });
page.locator('tr').filter({ has: page.locator('td.name') });
```
## 选择器生成
### 自动生成选择器
Playwright 提供自动生成健壮选择器的功能。`selectorGenerator.ts` 分析 DOM 元素并生成可靠的选择器字符串。
```mermaid
graph TD
A[DOM 元素] --> B[selectorGenerator.ts]
B --> C[收集元素信息]
C --> D{检查优先级}
D -->|测试ID| E[优先使用 test-id]
D -->|角色+名称| F[回退到 role+name]
D -->|CSS| G[最后使用 CSS 路径]
E --> H[返回选择器字符串]
F --> H
G --> H
style A fill:#e1f5ff
style H fill:#c8e6c9
```
选择器生成优先级：
1. `data-testid` 属性
2. ARIA role + accessible name 组合
3. 其他 ARIA 属性组合
4. 文本内容
5. CSS 路径
### 生成 API
在浏览器控制台中可以使用 `playwright` 对象生成选择器：
```javascript
// 获取元素的选择器
playwright.selector(element);
// 生成特定语言的定位器
playwright.generateLocator(element, 'playwright');
playwright.generateLocator(element, 'cypress');
playwright.generateLocator(element, 'puppeteer');
```
## 选择器评估
### 评估器职责
`selectorEvaluator.ts` 负责评估选择器表达式与 DOM 元素的匹配关系：
| 功能 | 说明 |
|------|------|
| **匹配验证** | 验证元素是否匹配选择器 |
| **唯一性检查** | 确保选择器匹配唯一元素 |
| **可见性检查** | 考虑元素可见性状态 |
| **优先级排序** | 对多个匹配结果排序 |
### 评估流程
```mermaid
sequenceDiagram
participant U as 用户代码
participant L as Locator
participant E as selectorEvaluator
participant D as DOM
U->>L: locator.click()
L->>E: evaluate(selector)
E->>D: querySelectorAll()
D-->>E: [elements]
E->>E: filterByVisibility()
E->>E: sortByPriority()
E-->>L: [matchedElements]
L->>L: waitForMatch()
L->>D: performAction()
```
## 最佳实践
### 选择器选择优先级
| 优先级 | 方法 | 示例 | 适用场景 |
|--------|------|------|----------|
| 1 | `getByRole()` | `getByRole('button', {name:'Submit'})` | 推荐首选 |
| 2 | `getByLabel()` | `getByLabel('Username')` | 表单输入 |
| 3 | `getByText()` | `getByText('Submit')` | 可见文本 |
| 4 | `getByTestId()` | `getByTestId('submit-btn')` | 测试专用 |
| 5 | CSS/XPath | `locator('.class')` | 复杂定位 |
### 健壮性原则
1. **避免脆弱选择器** - 不要依赖随机生成的类名
2. **使用语义角色** - 优先使用 `getByRole()` 而非 CSS 类
3. **添加 name 约束** - 角色选择器配合 accessible name 更可靠
4. **避免绝对路径** - XPath 不使用 `html/body/div[1]/div[2]`
5. **保持测试ID稳定** - 避免频繁更改 `data-testid`
### 性能优化
| 问题 | 解决方案 |
|------|----------|
| 元素查找慢 | 使用更具体的选择器 |
| 频繁重试 | 减少选择器复杂度 |
| 跨框架定位 | 使用 `frameLocator()` |
## 控制台 API
Playwright 注入脚本在浏览器控制台暴露了调试工具：
```javascript
// 查找单个元素
playwright.$('button.submit');
// 查找所有匹配元素
playwright.$$('li.item');
// 检查元素信息
playwright.inspect('button');
// 获取元素选择器
playwright.selector(element);
// 生成定位器代码
playwright.generateLocator(element, 'playwright');
// 获取 ARIA 快照
playwright.ariaSnapshot();
```
这些 API 用于 `playwright-cli` 工具的调试和诊断功能。
## 总结
Playwright 的定位器和选择器系统提供了强大而灵活的页面元素定位能力：
- **Locator API** 是高级封装，提供自动重试和惰性执行
- **选择器引擎** 支持多种定位策略，采用插件化架构
- **角色选择器** 基于 ARIA 规范，是推荐的定位方式
- **选择器生成器** 自动创建健壮的选择器表达式
- **评估器** 确保选择器正确匹配目标元素
合理使用这些组件可以编写出稳定、可维护的浏览器自动化测试脚本。
---
**相关资料：**
- Locator 客户端实现：`packages/playwright-core/src/client/locator.ts`
- 选择器引擎核心：`packages/injected/src/selectorEngine.ts`
- 角色选择器：`packages/injected/src/roleSelectorEngine.ts`
- 选择器生成器：`packages/injected/src/selectorGenerator.ts`
- 选择器评估器：`packages/injected/src/selectorEvaluator.ts`
- 跨平台工具：`packages/isomorphic/locatorUtils.ts`
---
## 断言系统
### 相关页面
相关主题：[测试框架](#test-framework), [定位器和选择器](#locators-and-selectors)
相关源码文件
以下源码文件用于生成本页说明：
- [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-core/src/client/locator.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)
- [packages/isomorphic/assert.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/assert.ts)
- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)
- [README.md](https://github.com/microsoft/playwright/blob/main/README.md)
# 断言系统
## 概述
Playwright 断言系统是端到端测试框架的核心组件，提供了一套完整的 Web 页面状态验证机制。该系统基于"Web-First 断言"理念设计，具有自动等待、可重试、软断言等关键特性，旨在消除人工设置超时和避免 flaky 测试。
断言系统的核心设计目标包括：
- **自动等待**：在断言执行前自动等待目标元素达到预期状态
- **可重试机制**：断言会自动重试直到条件满足或超时
- **软断言支持**：允许收集多个失败而非立即中断测试
- **丰富的匹配器**：覆盖 Web 交互中的各类验证场景
资料来源：[README.md:1-100]()
## 核心架构
Playwright 断言系统采用分层架构设计，主要包含以下层次：
```mermaid
graph TD
A[用户测试代码] --> B[expect API]
B --> C[软断言控制器]
C --> D[匹配器集合]
D --> E[等待策略]
E --> F[Locator/Page 对象]
F --> G[底层 CDP 通信]
H[自定义匹配器] --> D
I[toBe/toHave/toContain...] --> D
```
### 核心组件表
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| expect | `packages/playwright/src/matchers/expect.ts` | 入口函数，创建断言上下文 |
| 匹配器 | `packages/playwright/src/matchers/matchers.ts` | 实现具体断言逻辑 |
| Locator | `packages/playwright-core/src/client/locator.ts` | 元素定位与断言绑定 |
| 断言工具 | `packages/isomorphic/assert.ts` | 底层断言辅助函数 |
资料来源：[packages/playwright/src/matchers/expect.ts:1-50]()
## expect API
### 基本用法
`expect` 是 Playwright 断言系统的入口函数，支持多种使用方式：
```typescript
import { test, expect } from '@playwright/test';
// 页面级断言
await expect(page).toHaveTitle('Playwright');
// 定位器断言
await expect(page.getByRole('button')).toBeVisible();
// 期望值断言
expect(value).toBe(42);
```
### expect 函数实现
`expect` 函数接受一个实际值作为参数，返回一个包含所有断言方法的 Expect 对象：
```typescript
// packages/playwright/src/matchers/expect.ts 核心签名
function expect(value: any): Expect
```
Expect 对象提供的方法分为两类：
1. **布尔匹配器**：直接返回布尔结果的断言
2. **可等待匹配器**：返回 Promise 并自动等待的断言
资料来源：[packages/playwright/src/matchers/expect.ts:50-150]()
### 软断言
软断言允许在测试执行过程中收集多个失败断言，而不是在第一个失败时立即停止：
```typescript
test('soft assertions example', async ({ page }) => {
await expect.soft(page).toHaveTitle('Expected Title');
await expect.soft(page.getByRole('button')).toBeVisible();
// 即使前一个失败，后续断言仍会执行
});
```
软断言的失败会在测试结束时统一报告，测试状态标记为失败。
资料来源：[packages/playwright/src/matchers/expect.ts:150-200]()
## 内置匹配器
### 页面级匹配器
页面级匹配器直接作用于 `Page` 对象，验证页面整体状态：
| 匹配器 | 描述 | 示例 |
|--------|------|------|
| `toHaveTitle(title)` | 验证页面标题 | `await expect(page).toHaveTitle(/Playwright/)` |
| `toHaveURL(url)` | 验证当前 URL | `await expect(page).toHaveURL('**/docs**')` |
| `toHaveScreenshot(name)` | 验证页面截图 | `await expect(page).toHaveScreenshot('home.png')` |
资料来源：[packages/playwright/src/matchers/matchers.ts:1-100]()
### 元素级匹配器
元素级匹配器通过 Locator 链式调用，用于验证单个或多个元素的状态：
```typescript
// 可见性断言
await expect(page.locator('#submit')).toBeVisible();
await expect(page.locator('.loading')).toBeHidden();
// 内容断言
await expect(page.getByRole('button')).toHaveText('Submit');
await expect(page.locator('.error')).toContainText('Invalid');
// 属性断言
await expect(page.getByRole('input')).toHaveAttribute('required');
await expect(page.locator('img')).toHaveAttribute('src', /logo/);
// 表单值断言
await expect(page.getByRole('textbox')).toHaveValue('default text');
```
资料来源：[packages/playwright/src/matchers/matchers.ts:100-300]()
### 可访问性匹配器
Playwright 提供 ARIA 角色相关的匹配器，用于验证元素的可访问性语义：
```typescript
// 验证元素角色
await expect(page.locator('dialog')).toHaveRole('dialog');
await expect(page.locator('nav')).toHaveRole('navigation');
```
角色映射定义在 `roleUtils.ts` 中，涵盖了 HTML 语义化元素到 ARIA 角色的转换规则。
资料来源：[packages/injected/src/roleUtils.ts:1-50]()
### 计数与状态匹配器
| 匹配器 | 描述 |
|--------|------|
| `toHaveCount(count)` | 验证元素数量 |
| `toBeChecked()` | 验证复选框/单选框状态 |
| `toBeEnabled()` | 验证元素可用状态 |
| `toBeDisabled()` | 验证元素禁用状态 |
| `toBeFocused()` | 验证焦点状态 |
```typescript
await expect(page.getByRole('checkbox', { name: 'Remember me' })).toBeChecked();
await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();
```
资料来源：[packages/playwright/src/matchers/matchers.ts:300-400]()
## Locator 集成
### Locator 断言方法
Locator 对象直接集成了断言方法，允许链式调用：
```typescript
// Locator 类中的断言方法
// packages/playwright-core/src/client/locator.ts
class Locator {
// 可见性断言
async toBeVisible(options?: VisibilityOption): Promise
// 内容断言
async toHaveText(expected: string | RegExp | (string | RegExp)[]): Promise
// 属性断言
async toHaveAttribute(name: string, value?: string | RegExp): Promise
// 值断言
async toHaveValue(value: string | RegExp): Promise
}
```
Locator 断言的显著特点是**自动等待**：如果目标元素尚未满足条件，Playwright 会自动等待直到超时。
资料来源：[packages/playwright-core/src/client/locator.ts:200-350]()
### 等待策略
Playwright 断言内置智能等待策略：
```mermaid
graph LR
A[执行断言] --> B{元素存在?}
B -->|否| C[等待 DOM 出现]
C --> D{条件满足?}
D -->|否| E[重试]
E --> D
D -->|是| F[断言通过]
B -->|是| G{条件满足?}
G -->|否| H[等待条件变化]
H --> G
G -->|是| F
```
默认超时时间为 30 秒，可通过配置或方法参数覆盖：
```typescript
// 使用配置超时
await expect(page.locator('.loading')).toBeHidden({ timeout: 5000 });
// 使用全局配置
test.setTimeout(10000);
```
## 底层断言工具
### 断言辅助函数
`packages/isomorphic/assert.ts` 提供了底层断言实现：
```typescript
// 核心断言函数签名
export function expect(value: any, options?: ExpectOptions): ExpectResult
// 软断言标记
export type ExpectOptions = {
isSoft?: boolean
}
// 断言结果
export type ExpectResult = {
pass: boolean
message?: string
}
```
这些底层函数处理：
- 布尔值比较
- 正则表达式匹配
- 对象深度比较
- 数组包含检查
资料来源：[packages/isomorphic/assert.ts:1-100]()
## 配置与选项
### 断言超时配置
| 配置方式 | 优先级 | 示例 |
|----------|--------|------|
| 方法参数 | 最高 | `toBeVisible({ timeout: 1000 })` |
| 测试超时 | 中 | `test.setTimeout(10000)` |
| 全局配置 | 最低 | `playwright.config.ts` 中设置 |
### expect 配置
```typescript
// 自定义 expect 配置
test.use({
expect: {
timeout: 5000,
soft: false
}
});
```
## 最佳实践
### 1. 使用语义化定位器
```typescript
// 推荐：使用角色定位器
await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();
// 避免：过度依赖 CSS 选择器
await expect(page.locator('.btn-primary')).toBeVisible();
```
### 2. 利用自动等待
```typescript
// 正确：依赖自动等待
await expect(page.getByRole('status')).toHaveText('Saved');
// 错误：手动等待（容易导致 flaky）
await page.waitForTimeout(1000);
await expect(page.getByRole('status')).toHaveText('Saved');
```
### 3. 软断言收集错误
```typescript
test('form validation', async ({ page }) => {
await expect.soft(page.getByLabel('Email')).toHaveValue(/@/);
await expect.soft(page.getByLabel('Phone')).toHaveValue(/^\d+$/);
// 两个验证都会执行，错误会一起报告
});
```
### 4. 正则表达式匹配
```typescript
// 动态内容匹配
await expect(page.locator('.status')).toContainText(/saved|updated/i);
// URL 模式匹配
await expect(page).toHaveURL(/\?page=\d+/);
```
## 错误处理与调试
### 断言错误信息
Playwright 断言失败时会提供详细的诊断信息：
```
expect(received).toHaveText(expected)
Expected string: "Submit"
Received string: "Cancel"
```
### 调试模式
使用 Playwright CLI 进行断言调试：
```bash
# 运行测试并进入调试模式
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
# 附加到测试会话
playwright-cli attach
```
## 总结
Playwright 断言系统通过以下设计实现了可靠的 Web 测试：
| 特性 | 优势 |
|------|------|
| Web-First 断言 | 自动等待元素就绪，消除人工超时 |
| 语义化匹配器 | 符合 ARIA 规范，支持可访问性测试 |
| 软断言支持 | 收集多个失败，提供完整错误报告 |
| Locator 集成 | 链式调用，代码可读性高 |
| 可配置超时 | 灵活适应不同测试场景 |
该系统是 Playwright 测试框架的核心支柱，为开发者提供了简洁、可靠、语义化的断言 API。
---
## 命令行工具
### 相关页面
相关主题：[快速入门](#getting-started)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/playwright-core/src/cli/program.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/program.ts)
- [packages/playwright-core/src/cli/browserActions.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/browserActions.ts)
- [packages/playwright-core/src/cli/installActions.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/installActions.ts)
- [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/backend/tools.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/backend/tools.ts)
- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)
- [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)
# 命令行工具
Playwright 提供了一套完整的命令行工具体系，用于浏览器自动化、测试执行、轨迹分析和 CLI 客户端交互。本页详细介绍 Playwright 命令行工具的整体架构、各子命令的功能以及典型使用场景。
## 1. 架构概述
Playwright 命令行工具由多个层次的组件构成，形成了一个分层式的命令行体系。最上层是用户直接调用的 `playwright` 主命令，中间层是针对不同功能域的子命令模块（如浏览器管理、测试运行、轨迹查看等），底层则是负责具体操作执行的工具后端。
```mermaid
graph TD
A["用户终端"] --> B["playwright 主程序
program.ts"]
B --> C["browserActions
浏览器管理"]
B --> D["installActions
安装管理"]
B --> E["playwright-cli
CLI客户端"]
B --> F["playwright test
测试运行"]
B --> G["playwright trace
轨迹分析"]
E --> H["tools.ts
工具后端"]
H --> I["浏览器会话管理"]
H --> J["快照与截图"]
H --> K["网络拦截"]
H --> L["存储管理"]
```
主程序入口位于 `program.ts`，负责解析命令行参数并将请求分发到对应的子模块。资料来源：[packages/playwright-core/src/cli/program.ts]()
## 2. 主命令模块
### 2.1 浏览器动作命令
`browserActions.ts` 模块封装了所有与浏览器交互相关的底层操作，包括启动浏览器实例、创建页面、执行导航等核心功能。这些动作构成了所有高级自动化操作的基础。
| 命令类别 | 功能描述 |
|---------|---------|
| `open` | 启动新的浏览器会话并导航到指定 URL |
| `goto` | 在当前会话中导航到目标页面 |
| `close` | 关闭当前浏览器会话 |
| `kill-all` | 强制终止所有浏览器进程 |
资料来源：[packages/playwright-core/src/cli/browserActions.ts]()
### 2.2 安装命令
`installActions.ts` 模块负责管理 Playwright 的运行时依赖。最重要的功能是下载和安装浏览器可执行文件。该模块确保所有支持的浏览器（Chromium、Firefox、WebKit）都被正确安装并可用。
```bash
# 安装所有浏览器
npx playwright install
# 安装指定浏览器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
# 安装带驱动依赖
npx playwright install --with-deps
```
资料来源：[packages/playwright-core/src/cli/installActions.ts]()
## 3. playwright-cli 客户端
`playwright-cli` 是 Playwright 提供的交互式命令行客户端，提供了比主命令更丰富的浏览器自动化能力。它支持实时快照查看、元素交互、网络拦截、存储管理等高级功能。
### 3.1 核心命令
```mermaid
graph LR
A["playwright-cli"] --> B["页面操作"]
A --> C["元素定位"]
A --> D["网络控制"]
A --> E["状态管理"]
A --> F["调试工具"]
B --> B1["goto / click / fill / type"]
C --> C1["snapshot / click ref"]
D --> D1["route / unroute"]
E --> E1["cookie / localstorage"]
F --> F1["console / tracing"]
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()
#### 页面操作命令
| 命令 | 功能 | 示例 |
|-----|------|------|
| `open` | 打开浏览器并访问 URL | `playwright-cli open https://example.com` |
| `goto` | 导航到指定页面 | `playwright-cli goto https://example.com` |
| `click` | 点击元素 | `playwright-cli click e15` |
| `fill` | 填充输入框 | `playwright-cli fill e5 "text"` |
| `type` | 模拟键盘输入 | `playwright-cli type "search query"` |
| `press` | 按下按键 | `playwright-cli press Enter` |
| `snapshot` | 获取页面快照 | `playwright-cli snapshot` |
| `screenshot` | 截图保存 | `playwright-cli screenshot --filename=page.png` |
| `pdf` | 生成 PDF | `playwright-cli pdf --filename=page.pdf` |
#### 元素定位系统
playwright-cli 采用基于快照的引用系统来定位页面元素。每个可交互元素在快照中都有一个唯一的引用标识符（如 `e15`），用户可以通过这些引用来执行操作。
```bash
# 获取带引用的快照
playwright-cli snapshot
# 使用引用点击元素
playwright-cli click e15
# 也支持 CSS 选择器和 Playwright 定位器
playwright-cli click "#main > button.submit"
playwright-cli click "getByRole('button', { name: 'Submit' })"
```
### 3.2 浏览器会话管理
playwright-cli 支持多个并发浏览器会话，每个会话可以通过名称标识。这对于同时测试多个场景或进行 A/B 测试非常有用。
```bash
# 创建命名会话
playwright-cli -s=mysession open https://example.com
# 列出所有会话
playwright-cli list
# 关闭指定会话
playwright-cli -s=mysession close
# 关闭所有会话
playwright-cli close-all
# 强制终止所有浏览器进程
playwright-cli kill-all
```
持久化配置文件支持自定义会话设置：
```bash
# 使用配置文件打开
playwright-cli open https://example.com --config=.playwright/my-cli.json
# 指定浏览器类型
playwright-cli open https://example.com --browser=firefox
# 以有头模式打开
playwright-cli open https://example.com --headed
# 使用持久化配置文件
playwright-cli open https://example.com --persistent
playwright-cli open https://example.com --profile=/path/to/profile
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md]()
### 3.3 存储管理
playwright-cli 提供了完整的客户端存储管理能力，支持 Cookie、LocalStorage、SessionStorage 的增删改查操作。
```bash
# 状态持久化
playwright-cli state-save auth.json
playwright-cli state-load auth.json
# Cookie 管理
playwright-cli cookie-list
playwright-cli cookie-list --domain=example.com
playwright-cli cookie-get session_id
playwright-cli cookie-set session_id abc123
playwright-cli cookie-delete session_id
playwright-cli cookie-clear
# LocalStorage 管理
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear
```
### 3.4 网络控制
```bash
# 拦截请求并返回自定义状态
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
```
### 3.5 标签页管理
```bash
# 标签页操作
playwright-cli tab-list
playwright-cli tab-new
playwright-cli tab-new https://example.com/page
playwright-cli tab-close
playwright-cli tab-close 2
playwright-cli tab-select 0
```
## 4. 轨迹工具
`playwright trace` 命令用于分析和调试 `.zip` 格式的轨迹文件，这些文件由 Playwright 测试运行时生成，包含完整的执行过程记录。
### 4.1 轨迹工作流程
```mermaid
graph TD
A["trace open"] --> B["trace actions"]
B --> C{"发现问题?"}
C -->|是| D["trace actions --errors-only"]
C -->|否| E["继续分析"]
D --> F["trace action "]
F --> G["trace snapshot"]
G --> H["trace requests
trace console"]
```
### 4.2 轨迹命令
| 命令 | 功能 |
|-----|------|
| `trace open ` | 打开并提取轨迹文件，显示元数据 |
| `trace close` | 关闭当前轨迹，清理临时文件 |
| `trace actions` | 列出所有动作，支持 `--grep` 过滤 |
| `trace actions --errors-only` | 仅显示失败的动作 |
| `trace action ` | 查看特定动作的详细信息 |
| `trace snapshot ` | 获取动作执行时的 DOM 快照 |
| `trace requests` | 查看网络请求列表 |
| `trace requests --failed` | 仅显示失败的请求 |
| `trace console` | 查看控制台日志 |
| `trace console --errors-only` | 仅显示错误日志 |
| `trace attachments` | 列出所有附件 |
| `trace attachment ` | 提取指定附件 |
资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()
## 5. 调试工具
playwright-cli 集成了多种调试辅助工具，帮助开发者诊断问题。
### 5.1 控制台与网络监控
```bash
# 查看控制台输出
playwright-cli console
playwright-cli console warning
# 查看网络请求
playwright-cli requests
# 查看特定请求详情
playwright-cli request 5
```
### 5.2 追踪录制
```bash
# 开始录制追踪
playwright-cli tracing-start
# 停止录制并保存
playwright-cli tracing-stop
```
追踪文件包含以下内容：
| 文件/目录 | 内容描述 |
|----------|---------|
| `trace-{timestamp}.trace` | 动作日志，包含每个操作的快照和截图 |
| `trace-{timestamp}.network` | 完整的网络活动记录 |
| `resources/` | 缓存的资源文件 |
### 5.3 可视化调试
```bash
# 启动带标注功能的截图工具
playwright-cli show --annotate
# 高亮显示元素
playwright-cli highlight e5
playwright-cli highlight e5 --style="outline: 3px dashed red"
playwright-cli highlight --hide
```
## 6. 代码执行
`run-code` 命令允许在页面上下文中直接执行 JavaScript 代码，这对于动态探测和调试非常有用。
```bash
# 获取页面信息
playwright-cli run-code "async page => {
return await page.title();
}"
# 读写剪贴板
playwright-cli run-code "async page => {
await page.context().grantPermissions(['clipboard-read']);
return await page.evaluate(() => navigator.clipboard.readText());
}"
# 执行复杂逻辑
playwright-cli run-code "async page => {
const multiplier = 5;
return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
}"
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/running-code.md]()
## 7. 测试集成
Playwright CLI 与 Playwright Test 框架紧密集成，提供了便捷的测试调试能力。
```bash
# 运行所有测试
PLAYWRIGHT_HTML_OPEN=never npx playwright test
# 调试模式运行测试
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
```
调试模式会暂停测试执行并提供会话名称，允许通过 playwright-cli 附加到测试会话进行实时调试：
```bash
# 等待调试指令输出 tw-XXXX 会话名
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
# 附加到测试会话
playwright-cli attach tw-XXXX
```
资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md]()
## 8. 工具后端架构
`tools.ts` 模块定义了 CLI 工具的后端实现，封装了所有底层浏览器操作能力。这些工具通过 MCP（Model Context Protocol）协议对外提供服务，使得 AI 代理能够通过标准化接口调用 Playwright 功能。
核心工具类别包括：
- **页面操作工具**：导航、点击、输入、提交等
- **元素查询工具**：快照生成、引用解析、选择器生成
- **状态管理工具**：Cookie、存储、网络路由
- **调试工具**：控制台捕获、追踪录制、截图
资料来源：[packages/playwright-core/src/tools/backend/tools.ts]()
## 9. 使用建议
### 9.1 工具选择指南
| 场景 | 推荐工具 |
|------|---------|
| 快速浏览网页 | `playwright-cli open` |
| 调试测试失败 | `playwright test --debug=cli` + `playwright-cli attach` |
| 分析测试轨迹 | `playwright trace` |
| 复杂自动化脚本 | `playwright-cli run-code` |
| 并发多浏览器测试 | `playwright-cli -s=` |
### 9.2 最佳实践
1. **会话命名**：使用有意义的会话名称，便于管理和清理
2. **资源清理**：完成操作后及时关闭会话或使用 `close-all`
3. **持久化配置**：复杂场景使用配置文件管理会话设置
4. **追踪录制**：遇到问题时录制追踪便于事后分析
5. **快照优先**：使用 `snapshot` 命令而非频繁截图，提高效率
### 9.3 安装与更新
```bash
# 检查版本
npx --no-install playwright-cli --version
# 或使用全局命令
playwright-cli --version
---
---
## Doramagic 踩坑日志
项目：microsoft/playwright
摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized。
## 1. 安装坑 · 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9f8ee5532aee4b6cbf512f4227b0bac6 | https://github.com/microsoft/playwright/issues/40856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9ae154da8c374e95842c5b9fed587329 | https://github.com/microsoft/playwright/issues/40857 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：[Bug]: module.register() deprecation warning (DEP0205) on Node 26
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: module.register() deprecation warning (DEP0205) on Node 26
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d99eb725d0044cc8a856ff77a5034353 | https://github.com/microsoft/playwright/issues/40868 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：[Bug]: test body doesn't accept function with a return type other than void
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: test body doesn't accept function with a return type other than void
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_068a984a4ea348dd8b8de11244fbddd2 | https://github.com/microsoft/playwright/issues/40851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：[Feature] Allow custom command-line arguments in @playwright/test
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Allow custom command-line arguments in @playwright/test
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_27f460cbef7e4489b323fb9fb7cfc515 | https://github.com/microsoft/playwright/issues/10337 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安装坑 · 来源证据：v1.56.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.56.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cc7813a33a854a3c8465dd3548ef7684 | https://github.com/microsoft/playwright/releases/tag/v1.56.0 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 安装坑 · 来源证据：v1.57.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.57.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5d76f3b46992422c8b4a18583cabd192 | https://github.com/microsoft/playwright/releases/tag/v1.57.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 来源证据：v1.59.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.59.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c4296f1e3e0d4e37bbecccf2fe087c00 | https://github.com/microsoft/playwright/releases/tag/v1.59.0 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 能力坑 · 来源证据：v1.60.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v1.60.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2bf82c9b52a6418986114131cd1bd2d3 | https://github.com/microsoft/playwright/releases/tag/v1.60.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 10. 能力坑 · 能力判断依赖假设
- 严重度：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.
## 11. 运行坑 · 来源证据：v1.59.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.59.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fa3aef4aac6e4812b8d1e973fb2e88c5 | https://github.com/microsoft/playwright/releases/tag/v1.59.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 12. 维护坑 · 来源证据：v1.55.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.55.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_66dddad3517842b38fff2a76a1c00ce0 | https://github.com/microsoft/playwright/releases/tag/v1.55.1 | 来源类型 github_release 暴露的待验证使用条件。
## 13. 维护坑 · 来源证据：v1.58.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.58.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_53b55fd4a28c4da791a8160ca677d10d | https://github.com/microsoft/playwright/releases/tag/v1.58.2 | 来源类型 github_release 暴露的待验证使用条件。
## 14. 维护坑 · 维护活跃度未知
- 严重度：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
## 15. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium
## 16. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium
## 17. 安全/权限坑 · 来源证据：v1.56.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.56.1
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e050e46d53424e568cf3a0286a0f2739 | https://github.com/microsoft/playwright/releases/tag/v1.56.1 | 来源类型 github_release 暴露的待验证使用条件。
## 18. 安全/权限坑 · 来源证据：v1.58.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_91fccb17c1534cbfbc86fc6d7d0f7e30 | https://github.com/microsoft/playwright/releases/tag/v1.58.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 19. 安全/权限坑 · 来源证据：v1.58.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.1
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1b5831f013464a809b33b71e270d6a82 | https://github.com/microsoft/playwright/releases/tag/v1.58.1 | 来源类型 github_release 暴露的待验证使用条件。
## 20. 维护坑 · 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
## 21. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | release_recency=unknown