什么是 Playwright

Playwright 是由 Microsoft 开发的一个跨浏览器自动化测试框架，支持 Chromium、Firefox 和 WebKit 浏览器。它提供了可靠的方式来测试现代 Web 应用程序，支持自动化点击、输入、表单提交、截图、PDF 生成等操作。

资料来源：packages/playwright-core/src/tools/cli-client/skill/SKILL.md

核心架构

Playwright 项目采用多包架构，包含以下主要组件：

graph TD
    A[Playwright] --> B[playwright-core]
    A --> C[trace-viewer]
    A --> D[html-reporter]
    A --> E[playwright]
    B --> F[CLI 工具]
    B --> G[浏览器驱动]
    F --> H[playwright-cli]
    F --> I[playwright-trace]

核心包说明

资料来源：packages/injected/src/consoleApi.ts:18-26

CLI 工具集

Playwright CLI 提供了丰富的命令行工具，用于浏览器自动化操作和测试调试。

资料来源：packages/playwright-core/src/tools/cli-client/skill/SKILL.md

页面操作命令

# 导航和页面控制
playwright-cli goto <url>
playwright-cli back
playwright-cli forward
playwright-cli reload
playwright-cli close

元素交互命令

playwright-cli click e15
playwright-cli fill "#search-input" "搜索内容"
playwright-cli screenshot --filename=page.png

资料来源：packages/playwright-core/src/tools/cli-client/skill/SKILL.md

代码执行

使用 run-code 命令在浏览器上下文中执行 JavaScript 代码：

# 读取剪贴板
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['clipboard-read']);
  return await page.evaluate(() => navigator.clipboard.readText());
}"

# 执行 JavaScript 并获取结果
playwright-cli run-code "async page => {
  return await page.evaluate(() => {
    return {
      userAgent: navigator.userAgent,
      language: navigator.language,
      cookiesEnabled: navigator.cookieEnabled
    };
  });
}"

资料来源：packages/playwright-core/src/tools/cli-client/skill/references/running-code.md

存储管理

# 状态持久化
playwright-cli state-save auth.json
playwright-cli state-load auth.json

# Cookie 操作
playwright-cli cookie-list
playwright-cli cookie-get session_id
playwright-cli cookie-set session_id abc123 --httpOnly --secure

# LocalStorage
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark

资料来源：packages/playwright-core/src/tools/cli-client/skill/SKILL.md

标签页管理

playwright-cli tab-list
playwright-cli tab-new https://example.com
playwright-cli tab-close
playwright-cli tab-select 0

Trace 查看器

Playwright Trace CLI 是一个命令行工具，用于检查测试生成的 .zip 追踪文件，无需打开浏览器。

资料来源：packages/playwright-core/src/tools/trace/SKILL.md

追踪命令

# 打开追踪文件
npx playwright trace open <trace.zip>

# 列出所有操作
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

典型调查流程

# 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 在线访问：

<div>1. Download the trace from the download shelf</div>
<div>2. Go to <a href='https://trace.playwright.dev'>trace.playwright.dev</a></div>
<div>3. Drop the trace from the download shelf into the page</div>

资料来源：packages/trace-viewer/src/ui/workbenchLoader.tsx:1-20

代码生成

Playwright 支持多种编程语言的测试代码生成，包括 JavaScript、TypeScript、C# 等。

资料来源：packages/playwright-core/src/server/codegen/csharp.ts

C# 代码生成

// 创建新页面
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 用于生成可视化的测试报告，包含测试用例状态、持续时间、注释等信息。

<TabbedPane tabs={
  test.results.map((result, index) => ({
    id: String(index),
    title: <div style={{ display: 'flex', alignItems: 'center' }}>
      {statusIcon(result.status)} {retryLabel(index)}
      {(test.results.length > 1) && <span className='test-case-run-duration'>{msToString(result.duration)}</span>}
    </div>,
    render: () => { /* 渲染测试结果 */ }
  }))
} />

资料来源：packages/html-reporter/src/testCaseView.tsx:1-30

报告功能

资料来源：packages/html-reporter/src/testCaseView.tsx:30-50

页面注入 API

Playwright 在浏览器上下文中注入了 window.playwright 对象，提供调试和测试辅助功能：

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

可用方法

规范驱动测试

Playwright 支持基于规范的测试工作流，帮助团队从用户故事生成可执行的测试用例。

资料来源：packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md

测试工作流

graph LR
    A[编写规范] --> B[生成 Seed 测试]
    B --> C[探索应用]
    C --> D[完善规范]
    D --> E[生成测试代码]
    E --> F[运行测试]

规范文件结构

# <功能> 测试计划

## 应用概述
<描述功能做什么以及为什么重要>

## 测试场景

### 1. <分组名称>
**Seed:** `tests/seed.spec.ts`

#### 1.1. <场景名称>
**文件:** `tests/<group>/<kebab-case-scenario-name>.spec.ts`

**步骤:**
  1. <具体用户操作>
    - expect: <可观察的结果>

资料来源：packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md

探索应用

# 启动应用进行探索
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

概述

Playwright 是一个用于自动化 Web 浏览器的 Node.js 库，由 Microsoft 开发维护。它提供了高层次的 API，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎。Playwright 的主要特性包括：跨浏览器自动化、自动化等待机制、自动录制功能、以及强大的调试工具。

当前版本为 1.61.0-next，最低要求 Node.js 18 及以上版本。

安装 Playwright

系统要求

安装命令

# 使用 npm 安装
npm install @playwright/test

# 使用 yarn 安装
yarn add @playwright/test

# 使用 pnpm 安装
pnpm add @playwright/test

安装完成后，需要下载浏览器依赖：

# 下载所有浏览器
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：

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 文件：

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/);
});

运行测试

基本命令

调试模式

使用 CLI 调试模式启动测试：

PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli

调试时会输出会话名称，格式为 tw-XXXX。使用 playwright-cli 附加到该会话进行调试：

playwright-cli attach tw-XXXX

资料来源：packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md:1-21

Playwright CLI 工具

playwright-cli 是 Playwright 提供的命令行交互工具，支持浏览器会话管理、元素交互、快照获取等功能。

常用命令

#### 浏览器会话管理

# 打开浏览器
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

#### 页面交互

# 点击元素（使用快照中的 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 支持多种定位策略：

#### 网络拦截

# 拦截请求返回 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

持久化会话

使用命名会话可以保持浏览器状态：

# 创建持久化会话
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 录制追踪

# 开始录制
playwright-cli tracing-start

# 执行操作
playwright-cli open https://example.com
playwright-cli click e1
playwright-cli fill e2 "test"

# 停止录制
playwright-cli tracing-stop

录制完成后，会在 traces/ 目录下生成以下文件：

资料来源：packages/playwright-core/src/tools/cli-client/skill/references/tracing.md:1-45

Trace Viewer

使用 Playwright Trace CLI 查看追踪文件：

# 打开追踪文件
npx playwright trace open <trace.zip>

# 查看所有动作
npx playwright trace actions

# 查看失败的动作
npx playwright trace actions --errors-only

# 查看动作详情
npx playwright trace action <action-id>

# 查看快照
npx playwright trace snapshot <action-id>

# 查看控制台错误
npx playwright trace console --errors-only

# 查看失败的请求
npx playwright trace requests --failed

# 关闭追踪
npx playwright trace close

典型调查流程：

# 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

浏览器会话与存储

保存和加载状态

# 保存状态
playwright-cli state-save auth.json

# 加载状态
playwright-cli state-load auth.json

Cookie 管理

# 列出所有 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

本地存储

# 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 执行自定义代码

# 获取页面标题
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

# 获取页面标题
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 定义了常用的测试脚本：

资料来源：package.json:19-35

快速参考

一分钟启动

# 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

常用命令速查

核心设计理念

Playwright 的架构围绕两个核心目标设计：

Playwright 的核心代码位于 packages/playwright-core/ 包中，负责处理底层浏览器通信和 API 实现。

进程模型

Playwright 支持两种进程模型，开发者可以根据场景选择适合的模式。

进程外模式（Out-of-Process）

进程外模式是 Playwright 的默认和推荐模式。在此模式下，Playwright 会在独立进程中启动浏览器，并通过 IPC（进程间通信）与浏览器进行交互。

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）
• 需要快速执行的场景
• 与宿主应用紧密集成的用例

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 类建立与服务器端的通信通道。

连接类型

连接生命周期

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 服务器端负责管理浏览器实例和处理来自客户端的请求。

服务器组件

服务器传输层

服务器支持多种传输协议：

• stdio 传输：用于父子进程通信
• WebSocket 传输：用于远程连接
• CDP 传输：直接与浏览器 DevTools 端口通信

资料来源：packages/playwright-core/src/remote/playwrightServer.ts:1-80

浏览器会话管理

Playwright 通过会话（Session）机制管理多个独立的浏览器上下文。

会话类型

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），允许保存和恢复浏览器状态：

# 创建命名会话
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 支持多种元素定位方式：

网络拦截

Playwright 提供了强大的网络拦截功能，用于测试和调试。

路由（Route）操作

# 拦截特定请求
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 的跟踪功能可以捕获详细的执行信息，用于问题排查和性能分析。

跟踪文件结构

traces/
├── trace-{timestamp}.trace    # 操作日志
├── trace-{timestamp}.network  # 网络活动
└── resources/                 # 缓存资源

CLI 跟踪命令

# 开始跟踪
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 助手控制浏览器：

# 运行 MCP 测试
npm run test-mcp

扩展测试

# 测试扩展功能
npm run test-extension

包结构

总结

Playwright 的架构设计体现了现代浏览器自动化的最佳实践：

1. 双进程模型：灵活支持进程内和进程外执行
2. 统一 API：跨浏览器提供一致的接口
3. 可扩展设计：支持插件和 MCP 集成
4. 强大的调试能力：内置跟踪、快照和 CLI 工具

概述

Playwright 的客户端实现是库的核心组成部分，它为开发者提供了操作浏览器的编程接口。客户端层封装了与浏览器驱动程序通信的底层细节，提供了高级 API 用于页面导航、元素交互、表单填写、截图等操作。

Playwright 采用 Channel（通道） 架构进行客户端与服务端通信。客户端实现位于 packages/playwright-core/src/client/ 目录下，包含了所有与浏览器交互的 TypeScript 类和接口。

架构概览

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]

客户端实现采用了分层架构设计：

核心组件

ChannelOwner 基类

ChannelOwner 是所有客户端对象的基类，负责：

• 管理与 Playwright Driver 的底层通信通道
• 处理远程过程调用（RPC）
• 管理对象的生命周期
• 处理事件订阅和分发

所有客户端对象（Page、Frame、BrowserContext、Locator 等）都继承自 ChannelOwner，共享相同的通信机制和生命周期管理模式。

Page 类

Page 代表浏览器中的一个页面，是最常用的交互入口。主要功能包括：

Frame 类

Frame 表示页面中的一个 iframe 或主框架。Playwright 中的 Frame 实现支持：

• 嵌套框架的遍历和定位
• 框架级别的操作隔离
• 跨框架元素交互

Locator API

Locator 是 Playwright 现代化的元素定位和交互方式，相比传统的 ElementHandle，Locator 具有以下优势：

Locator 提供了丰富的方法链：

// 链式定位示例
locator
  .frameLocator('#iframe')
  .locator('button.submit')
  .click();

ElementHandle 类

ElementHandle 代表 DOM 中的一个元素，提供直接的元素级操作：

• click() - 点击元素
• fill() - 填写表单
• hover() - 鼠标悬停
• evaluate() - 在元素上下文中执行 JavaScript

BrowserContext 类

BrowserContext 表示一个独立的浏览器会话，具有以下特性：

对象关系图

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 元素

生命周期管理

对象创建

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() 关闭整个浏览器

事件系统

客户端实现了基于订阅的事件系统：

等待机制

Playwright 客户端提供了智能的等待机制来处理异步操作：

内置等待

自定义等待

// 等待元素包含特定文本
await page.locator('div.status').waitFor({ 
  hasText: 'Success' 
});

// 等待函数返回 true
await page.waitForFunction(() => {
  return document.querySelectorAll('li').length > 10;
});

错误处理

客户端实现了完善的错误处理机制：

与 CLI 的集成

Playwright CLI (playwright-cli) 提供了命令行界面的浏览器自动化能力，与客户端 API 共享相同的底层实现：

# 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. 完善的错误处理：清晰的错误类型和合理的默认行为

这套客户端架构使得开发者能够以声明式的方式编写浏览器自动化测试和脚本，同时保证了跨浏览器的一致性。

概述

Playwright 的服务器端实现是框架的核心架构层，负责在 Node.js 环境中管理与浏览器实例的通信。该层封装了浏览器启动、页面操作、网络拦截、上下文隔离等底层功能，为上层 API 提供统一的接口抽象。

服务器端实现的主要职责包括：

• 管理浏览器进程的生命周期
• 处理跨进程通信协议
• 协调浏览器上下文和页面状态
• 处理网络请求和响应
• 分发器（Dispatcher）模式的消息路由

资料来源：packages/playwright-core/src/server/index.ts:1-20

架构设计

核心组件关系

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 服务器端采用分层架构设计，从底层到高层依次为：

资料来源：packages/playwright-core/src/server/dispatchers/dispatcher.ts:1-30

Browser 服务器实现

Browser 类职责

Browser 类是服务器端的核心入口，负责以下功能：

• 浏览器进程启动与关闭
• 浏览器类型检测（Chromium/Firefox/WebKit）
• 版本信息管理
• 发射器（Launch Server）管理

主要方法

class Browser {
  // 启动浏览器
  async launch(options: LaunchOptions): Promise<Browser>
  
  // 连接已存在的浏览器
  async connect(wsEndpoint: string): Promise<Browser>
  
  // 创建新上下文
  async newContext(options?: ContextOptions): Promise<BrowserContext>
  
  // 关闭浏览器
  async close(): Promise<void>
  
  // 获取所有上下文
  contexts(): BrowserContext[]
}

资料来源：packages/playwright-core/src/server/browser.ts:30-100

浏览器上下文管理

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、缓存等。

核心特性

主要方法

class BrowserContext {
  // 创建新页面
  async newPage(): Promise<Page>
  
  // 添加 cookies
  async addCookies(cookies: Cookie[]): Promise<void>
  
  // 获取 cookies
  async cookies(urls?: string[]): Promise<Cookie[]>
  
  // 清除所有 cookies
  async clearCookies(): Promise<void>
  
  // 授权权限
  async grantPermissions(permissions: string[]): Promise<void>
  
  // 截图
  async screenshot(options?: ScreenshotOptions): Promise<Buffer>
  
  // 关闭上下文
  async close(): Promise<void>
}

资料来源：packages/playwright-core/src/server/browserContext.ts:50-150

Page 服务器实现

Page 类代表浏览器中的一个标签页或框架，是与网页内容交互的主要接口。

元素定位与交互

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<void>
  async fill(selector: string, value: string): Promise<void>
  async type(selector: string, text: string, options?: TypeOptions): Promise<void>
  async hover(selector: string): Promise<void>
  async dragAndDrop(source: string, target: string): Promise<void>
}

导航操作

class Page {
  // 页面导航
  async goto(url: string, options?: GotoOptions): Promise<Response | null>
  async goBack(options?: NavigationOptions): Promise<Response | null>
  async goForward(options?: NavigationOptions): Promise<Response | null>
  async reload(options?: NavigationOptions): Promise<Response | null>
  
  // 等待导航完成
  async waitForNavigation(options?: WaitForNavigationOptions): Promise<Response | null>
  
  // 事件监听
  async waitForLoadState(state: LoadState): Promise<void>
  waitForURL(url: string | RegExp): Promise<void>
}

资料来源：packages/playwright-core/src/server/page.ts:100-250

Dispatcher 分发器

Dispatcher 是 Playwright 服务器端的消息路由核心，采用发布-订阅模式处理客户端请求。

工作原理

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

消息流程

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 基类

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 模块负责处理页面的网络请求和响应，支持请求拦截、修改、模拟等功能。

网络拦截

class Route {
  // 继续请求（可选修改）
  async continue(options?: ContinueRequestOptions): Promise<void>
  
  // 完成响应
  async fulfill(response: Partial<Response>): Promise<void>
  
  // 中止请求
  async abort(errorCode?: string): Promise<void>
}

class Request {
  // 获取请求信息
  url(): string
  method(): string
  headers(): Record<string, string>
  postData(): string | null
  
  // 响应对象
  response(): Response | null
}

路由规则配置

资料来源：packages/playwright-core/src/server/network.ts:50-120

服务器启动流程

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[服务器就绪]

关键配置选项

浏览器启动配置

上下文配置

资料来源：packages/playwright-core/src/server/browserContext.ts:200-280

与客户端的通信

Playwright 服务器端通过 CDP（Chrome DevTools Protocol）协议与浏览器通信，同时通过自定义协议与 Node.js 客户端交互。

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 类来支持自定义浏览器：

class CustomBrowser extends Browser {
  protected async _launchServer(): Promise<BrowserServer> {
    // 自定义启动逻辑
  }
}

添加新的协议处理器

通过扩展 Dispatcher 基类，可以添加新的协议处理能力：

class CustomDispatcher extends Dispatcher {
  constructor(scope: object, uid: number) {
    super(scope, uid);
  }
  
  // 实现自定义方法
  async customMethod(params: any): Promise<any> {
    // 处理逻辑
  }
}

最佳实践

资源管理

• 及时关闭不再使用的 Page、BrowserContext
• 使用 async/await 确保资源释放
• 设置合理的超时时间避免资源泄漏

错误处理

try {
  await page.goto('https://example.com', { timeout: 10000 });
} catch (error) {
  if (error instanceof TimeoutError) {
    // 处理超时
  } else if (error instanceof net.Error) {
    // 处理网络错误
  }
}

并发控制

相关模块索引

支持的浏览器类型

Playwright 原生支持以下三种浏览器：

资料来源：packages/playwright-core/src/server/browserType.ts

浏览器启动流程

Playwright 的浏览器启动遵循统一的工厂模式，通过 browserType.ts 中的 launch() 方法创建浏览器实例。

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() 方法支持丰富的配置选项：

资料来源：packages/playwright-core/src/server/browserType.ts

浏览器会话管理

CLI 会话管理

Playwright CLI (playwright-cli) 提供了完整的浏览器会话管理能力：

# 创建新的命名会话
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

会话状态持久化

浏览器状态可以通过以下方式保存和恢复：

# 保存当前状态
playwright-cli state-save auth.json

# 恢复状态
playwright-cli state-load auth.json

浏览器帧组件

Trace Viewer 使用 browserFrame.tsx 组件渲染浏览器外观模拟，该组件展示地址栏、菜单栏等 UI 元素：

<div className='browser-frame-address-bar' title={url || 'about:blank'}>
  <span className='browser-frame-address'>{url || 'about:blank'}</span>
  {url && <CopyToClipboard value={url} />}
</div>

资料来源：packages/trace-viewer/src/ui/browserFrame.tsx

网络路由与拦截

Playwright 支持对网络请求进行拦截和修改：

# 拦截特定 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 实现：

'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 支持多种元素定位方式：

# 使用快照引用
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# 为例：

// 检测是否为新页面操作
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 能够在不打开浏览器的情况下查看浏览器状态快照：

# 打开 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 组件展示浏览器元数据：

资料来源：packages/trace-viewer/src/ui/metadataView.tsx

浏览器环境变量

最佳实践

会话命名规范

# 推荐：清晰的命名
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

清理策略

无头模式与有头模式

# 无头模式（默认）
playwright-cli open https://example.com

# 有头模式（可见浏览器窗口）
playwright-cli open https://example.com --headed

架构总结

Playwright 的浏览器支持层采用适配器模式设计：

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 保持稳定
• 协议差异被隔离在各自的实现模块中

架构概述

Playwright 测试框架采用分层架构设计，核心组件包括配置管理、Fixtures 系统、测试运行器和 Worker 进程池。

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]

核心组件

配置系统

配置系统负责管理测试运行的全局参数，包括测试目录、测试超时、并发配置等。

配置通过 playwright.config.ts 文件定义，框架在启动时加载并验证配置的有效性。资料来源：packages/playwright/src/common/config.ts

Fixtures 系统

Fixtures 是 Playwright 测试框架的核心特性之一，用于在测试运行时提供上下文和资源管理。Fixtures 可以是浏览器上下文、页面对象、认证状态或任何测试所需的数据。

// 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 函数定义，支持分组、标注和元数据管理。

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）是框架的核心调度引擎，负责解析配置、加载测试文件并协调整个测试执行流程。

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 进程独立运行，可以并行执行多个测试。

资料来源：packages/playwright/src/runner/dispatcher.ts

Worker 进程

Worker 进程是测试代码的实际执行环境，每个 Worker 拥有独立的浏览器实例和上下文池。

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 进程池，优化资源利用率。

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]

进程池支持以下配置策略：

资料来源：packages/playwright/src/common/poolBuilder.ts

追踪与调试

追踪查看器

Playwright 提供追踪查看器（Trace Viewer）用于回放和调试测试执行过程。追踪文件是包含快照、网络请求、控制台日志的 ZIP 包。

# 打开追踪文件
npx playwright trace open <trace.zip>

# 查看特定 action 的详细信息
npx playwright trace action <action-id>

# 获取 DOM 快照
npx playwright trace snapshot <action-id>

追踪查看器支持以下功能：

• 时间线视图：可视化测试执行的时间轴
• 快照回放：查看每一步操作后的页面状态
• 网络监控：分析请求和响应详情
• 控制台日志：捕获 JavaScript 控制台输出
• 错误追踪：定位测试失败的具体原因

资料来源：packages/trace-viewer/src/ui/workbenchLoader.tsx

CLI 工具

playwright-cli 提供命令行界面用于调试和探索性测试。

# 启动调试会话
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 支持三大主流浏览器引擎：

每个浏览器通过独立的项目（Project）配置，支持不同的视口大小、用户代理、设备模拟等参数。

相关资源

• 官方文档：https://playwright.dev
• 追踪查看器：https://trace.playwright.dev
• 测试配置参考：Playwright 配置文件规范
• Fixtures API：自定义 Fixtures 开发指南

概述

Playwright 中的定位器（Locator）和选择器（Selector）是自动化浏览器交互的核心组件。定位器是 Playwright 推荐的元素定位方式，提供了比传统 Page.locator() API 更加健壮的元素查找机制。选择器则是用于匹配 DOM 元素的字符串表达式，支持多种定位策略。

定位器与选择器的关系可以通过以下架构图说明：

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 支持多种选择器类型：

源码架构

模块职责划分

graph LR
    A[packages/playwright-core<br/>客户端封装] --> B[packages/isomorphic<br/>跨平台工具]
    B --> C[packages/injected<br/>注入脚本]
    
    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

关键源文件

选择器引擎

选择器引擎架构

选择器引擎是 Playwright 解析和执行选择器的核心组件，采用插件化架构支持多种选择器类型。

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 规范实现。

graph LR
    A[getByRole<br/>'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

角色选择器支持的选项参数：

Locator API

创建定位器

定位器可以通过多种方式创建：

// 通过 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"]');

交互方法

过滤与断言

定位器支持通过 filter() 方法进一步过滤元素：

// 过滤条件示例
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 元素并生成可靠的选择器字符串。

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 对象生成选择器：

// 获取元素的选择器
playwright.selector(element);

// 生成特定语言的定位器
playwright.generateLocator(element, 'playwright');
playwright.generateLocator(element, 'cypress');
playwright.generateLocator(element, 'puppeteer');

选择器评估

评估器职责

selectorEvaluator.ts 负责评估选择器表达式与 DOM 元素的匹配关系：

评估流程

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. 避免脆弱选择器 - 不要依赖随机生成的类名
2. 使用语义角色 - 优先使用 getByRole() 而非 CSS 类
3. 添加 name 约束 - 角色选择器配合 accessible name 更可靠
4. 避免绝对路径 - XPath 不使用 html/body/div[1]/div[2]
5. 保持测试ID稳定 - 避免频繁更改 data-testid

性能优化

控制台 API

Playwright 注入脚本在浏览器控制台暴露了调试工具：

// 查找单个元素
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 规范，是推荐的定位方式
• 选择器生成器 自动创建健壮的选择器表达式
• 评估器 确保选择器正确匹配目标元素

合理使用这些组件可以编写出稳定、可维护的浏览器自动化测试脚本。

概述

Playwright 断言系统是端到端测试框架的核心组件，提供了一套完整的 Web 页面状态验证机制。该系统基于"Web-First 断言"理念设计，具有自动等待、可重试、软断言等关键特性，旨在消除人工设置超时和避免 flaky 测试。

断言系统的核心设计目标包括：

• 自动等待：在断言执行前自动等待目标元素达到预期状态
• 可重试机制：断言会自动重试直到条件满足或超时
• 软断言支持：允许收集多个失败而非立即中断测试
• 丰富的匹配器：覆盖 Web 交互中的各类验证场景

资料来源：README.md:1-100

核心架构

Playwright 断言系统采用分层架构设计，主要包含以下层次：

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

核心组件表

资料来源：packages/playwright/src/matchers/expect.ts:1-50

expect API

基本用法

expect 是 Playwright 断言系统的入口函数，支持多种使用方式：

import { test, expect } from '@playwright/test';

// 页面级断言
await expect(page).toHaveTitle('Playwright');

// 定位器断言
await expect(page.getByRole('button')).toBeVisible();

// 期望值断言
expect(value).toBe(42);

expect 函数实现

expect 函数接受一个实际值作为参数，返回一个包含所有断言方法的 Expect 对象：

// packages/playwright/src/matchers/expect.ts 核心签名
function expect(value: any): Expect

Expect 对象提供的方法分为两类：

1. 布尔匹配器：直接返回布尔结果的断言
2. 可等待匹配器：返回 Promise 并自动等待的断言

资料来源：packages/playwright/src/matchers/expect.ts:50-150

软断言

软断言允许在测试执行过程中收集多个失败断言，而不是在第一个失败时立即停止：

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 对象，验证页面整体状态：

资料来源：packages/playwright/src/matchers/matchers.ts:1-100

元素级匹配器

元素级匹配器通过 Locator 链式调用，用于验证单个或多个元素的状态：

// 可见性断言
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 角色相关的匹配器，用于验证元素的可访问性语义：

// 验证元素角色
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

计数与状态匹配器

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 对象直接集成了断言方法，允许链式调用：

// Locator 类中的断言方法
// packages/playwright-core/src/client/locator.ts

class Locator {
  // 可见性断言
  async toBeVisible(options?: VisibilityOption): Promise<void>
  
  // 内容断言  
  async toHaveText(expected: string | RegExp | (string | RegExp)[]): Promise<void>
  
  // 属性断言
  async toHaveAttribute(name: string, value?: string | RegExp): Promise<void>
  
  // 值断言
  async toHaveValue(value: string | RegExp): Promise<void>
}

Locator 断言的显著特点是自动等待：如果目标元素尚未满足条件，Playwright 会自动等待直到超时。

资料来源：packages/playwright-core/src/client/locator.ts:200-350

等待策略

Playwright 断言内置智能等待策略：

graph LR
    A[执行断言] --> B{元素存在?}
    B -->|否| C[等待 DOM 出现]
    C --> D{条件满足?}
    D -->|否| E[重试]
    E --> D
    D -->|是| F[断言通过]
    B -->|是| G{条件满足?}
    G -->|否| H[等待条件变化]
    H --> G
    G -->|是| F

默认超时时间为 30 秒，可通过配置或方法参数覆盖：

// 使用配置超时
await expect(page.locator('.loading')).toBeHidden({ timeout: 5000 });

// 使用全局配置
test.setTimeout(10000);

底层断言工具

断言辅助函数

packages/isomorphic/assert.ts 提供了底层断言实现：

// 核心断言函数签名
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

配置与选项

断言超时配置

expect 配置

// 自定义 expect 配置
test.use({
  expect: {
    timeout: 5000,
    soft: false
  }
});

最佳实践

1. 使用语义化定位器

// 推荐：使用角色定位器
await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();

// 避免：过度依赖 CSS 选择器
await expect(page.locator('.btn-primary')).toBeVisible();

2. 利用自动等待

// 正确：依赖自动等待
await expect(page.getByRole('status')).toHaveText('Saved');

// 错误：手动等待（容易导致 flaky）
await page.waitForTimeout(1000);
await expect(page.getByRole('status')).toHaveText('Saved');

3. 软断言收集错误

test('form validation', async ({ page }) => {
  await expect.soft(page.getByLabel('Email')).toHaveValue(/@/);
  await expect.soft(page.getByLabel('Phone')).toHaveValue(/^\d+$/);
  // 两个验证都会执行，错误会一起报告
});

4. 正则表达式匹配

// 动态内容匹配
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 进行断言调试：

# 运行测试并进入调试模式
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli

# 附加到测试会话
playwright-cli attach <session-id>

总结

Playwright 断言系统通过以下设计实现了可靠的 Web 测试：

该系统是 Playwright 测试框架的核心支柱，为开发者提供了简洁、可靠、语义化的断言 API。

1. 架构概述

Playwright 命令行工具由多个层次的组件构成，形成了一个分层式的命令行体系。最上层是用户直接调用的 playwright 主命令，中间层是针对不同功能域的子命令模块（如浏览器管理、测试运行、轨迹查看等），底层则是负责具体操作执行的工具后端。

graph TD
    A["用户终端"] --> B["playwright 主程序<br/>program.ts"]
    B --> C["browserActions<br/>浏览器管理"]
    B --> D["installActions<br/>安装管理"]
    B --> E["playwright-cli<br/>CLI客户端"]
    B --> F["playwright test<br/>测试运行"]
    B --> G["playwright trace<br/>轨迹分析"]
    E --> H["tools.ts<br/>工具后端"]
    H --> I["浏览器会话管理"]
    H --> J["快照与截图"]
    H --> K["网络拦截"]
    H --> L["存储管理"]

主程序入口位于 program.ts，负责解析命令行参数并将请求分发到对应的子模块。资料来源：packages/playwright-core/src/cli/program.ts

2. 主命令模块

2.1 浏览器动作命令

browserActions.ts 模块封装了所有与浏览器交互相关的底层操作，包括启动浏览器实例、创建页面、执行导航等核心功能。这些动作构成了所有高级自动化操作的基础。

资料来源：packages/playwright-core/src/cli/browserActions.ts

2.2 安装命令

installActions.ts 模块负责管理 Playwright 的运行时依赖。最重要的功能是下载和安装浏览器可执行文件。该模块确保所有支持的浏览器（Chromium、Firefox、WebKit）都被正确安装并可用。

# 安装所有浏览器
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 核心命令

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

#### 页面操作命令

#### 元素定位系统

playwright-cli 采用基于快照的引用系统来定位页面元素。每个可交互元素在快照中都有一个唯一的引用标识符（如 e15），用户可以通过这些引用来执行操作。

# 获取带引用的快照
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 测试非常有用。

# 创建命名会话
playwright-cli -s=mysession open https://example.com

# 列出所有会话
playwright-cli list

# 关闭指定会话
playwright-cli -s=mysession close

# 关闭所有会话
playwright-cli close-all

# 强制终止所有浏览器进程
playwright-cli kill-all

持久化配置文件支持自定义会话设置：

# 使用配置文件打开
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 的增删改查操作。

# 状态持久化
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 网络控制

# 拦截请求并返回自定义状态
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 标签页管理

# 标签页操作
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 轨迹工作流程

graph TD
    A["trace open"] --> B["trace actions"]
    B --> C{"发现问题?"}
    C -->|是| D["trace actions --errors-only"]
    C -->|否| E["继续分析"]
    D --> F["trace action <id>"]
    F --> G["trace snapshot"]
    G --> H["trace requests<br/>trace console"]

4.2 轨迹命令

资料来源：packages/playwright-core/src/tools/trace/SKILL.md

5. 调试工具

playwright-cli 集成了多种调试辅助工具，帮助开发者诊断问题。

5.1 控制台与网络监控

# 查看控制台输出
playwright-cli console
playwright-cli console warning

# 查看网络请求
playwright-cli requests

# 查看特定请求详情
playwright-cli request 5

5.2 追踪录制

# 开始录制追踪
playwright-cli tracing-start

# 停止录制并保存
playwright-cli tracing-stop

追踪文件包含以下内容：

5.3 可视化调试

# 启动带标注功能的截图工具
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 代码，这对于动态探测和调试非常有用。

# 获取页面信息
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 框架紧密集成，提供了便捷的测试调试能力。

# 运行所有测试
PLAYWRIGHT_HTML_OPEN=never npx playwright test

# 调试模式运行测试
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli

调试模式会暂停测试执行并提供会话名称，允许通过 playwright-cli 附加到测试会话进行实时调试：

# 等待调试指令输出 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 工具选择指南

9.2 最佳实践

1. 会话命名：使用有意义的会话名称，便于管理和清理
2. 资源清理：完成操作后及时关闭会话或使用 close-all
3. 持久化配置：复杂场景使用配置文件管理会话设置
4. 追踪录制：遇到问题时录制追踪便于事后分析
5. 快照优先：使用 snapshot 命令而非频繁截图，提高效率

9.3 安装与更新

# 检查版本
npx --no-install playwright-cli --version

# 或使用全局命令
playwright-cli --version

Pitfall Log / 踩坑日志

项目：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