\n\n# 列出所有操作\nnpx playwright trace actions\n\n# 查看特定操作详情\nnpx playwright trace action 12\n\n# 查看快照\nnpx playwright trace snapshot 12\n\n# 查看网络请求\nnpx playwright trace requests --failed\n\n# 查看控制台错误\nnpx playwright trace console --errors-only\n```\n\n### 典型调查流程\n\n```bash\n# 1. 打开追踪\nnpx playwright trace open test-results/my-test/trace.zip\n\n# 2. 查看操作列表\nnpx playwright trace actions\n\n# 3. 找出失败的操作\nnpx playwright trace actions --errors-only\n\n# 4. 分析失败详情\nnpx playwright trace action 12\n\n# 5. 查看页面快照\nnpx playwright trace snapshot 12\n\n# 6. 查询 DOM 获取更多信息\nnpx playwright trace snapshot 12 -- eval \"document.querySelector('.error-message').textContent\"\n\n# 7. 检查网络失败\nnpx playwright trace requests --failed\n\n# 8. 检查控制台错误\nnpx playwright trace console --errors-only\n```\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n### Trace Viewer Web 应用\n\nTrace Viewer 也是一个渐进式 Web 应用（PWA），可通过 `trace.playwright.dev` 在线访问：\n\n```tsx\n1. Download the trace from the download shelf
\n\n3. Drop the trace from the download shelf into the page
\n```\n\n资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx:1-20]()\n\n## 代码生成\n\nPlaywright 支持多种编程语言的测试代码生成，包括 JavaScript、TypeScript、C# 等。\n\n资料来源：[packages/playwright-core/src/server/codegen/csharp.ts]()\n\n### C# 代码生成\n\n```csharp\n// 创建新页面\nvar page = await context.NewPageAsync();\nawait page.GotoAsync(\"https://example.com\");\n\n// 对话框处理\nvoid Page_Dialog_EventHandler(object sender, IDialog dialog)\n{\n Console.WriteLine($\"Dialog message: {dialog.Message}\");\n dialog.DismissAsync();\n Page.Dialog -= Page_Dialog_EventHandler;\n}\nPage.Dialog += Page_Dialog_EventHandler;\n\n// 下载处理\nvar download = await Page.RunAndWaitForDownloadAsync(async () =>\n{\n // 执行下载操作\n});\n```\n\n资料来源：[packages/playwright-core/src/server/codegen/csharp.ts:1-30]()\n\n## HTML 报告器\n\nPlaywright HTML Reporter 用于生成可视化的测试报告，包含测试用例状态、持续时间、注释等信息。\n\n```tsx\n ({\n id: String(index),\n title: \n {statusIcon(result.status)} {retryLabel(index)}\n {(test.results.length > 1) && {msToString(result.duration)}}\n
,\n render: () => { /* 渲染测试结果 */ }\n }))\n} />\n```\n\n资料来源：[packages/html-reporter/src/testCaseView.tsx:1-30]()\n\n### 报告功能\n\n| 功能 | 说明 |\n|------|------|\n| 测试状态图标 | 显示通过/失败/跳过等状态 |\n| 重试标签 | 标记重试次数 |\n| 持续时间 | 显示每个测试的执行时长 |\n| 注释展示 | 显示测试注释和注解 |\n| 追踪链接 | 提供到追踪文件的链接 |\n\n资料来源：[packages/html-reporter/src/testCaseView.tsx:30-50]()\n\n## 页面注入 API\n\nPlaywright 在浏览器上下文中注入了 `window.playwright` 对象，提供调试和测试辅助功能：\n\n```typescript\ninstall() {\n this._injectedScript.window.playwright = {\n $: (selector: string, strict?: boolean) => this._querySelector(selector, !!strict),\n $$: (selector: string) => this._querySelectorAll(selector),\n inspect: (selector: string) => this._inspect(selector),\n selector: (element: Element) => this._selector(element),\n generateLocator: (element: Element, language?: Language) => this._generateLocator(element, language),\n ariaSnapshot: (element?: Element, options?: AriaTreeOptions) => {\n return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options || { mode: 'default' });\n },\n resume: () => this._resume(),\n ...new Locator(this._injectedScript, ''),\n };\n}\n```\n\n资料来源：[packages/injected/src/consoleApi.ts:18-35]()\n\n### 可用方法\n\n| 方法 | 功能描述 |\n|------|----------|\n| `$.query()` | 使用 Playwright 选择器语法查询单个元素 |\n| `$$.queryAll()` | 查询所有匹配的元素 |\n| `inspect()` | 检查元素的定位器信息 |\n| `selector()` | 生成元素的选择器 |\n| `generateLocator()` | 生成可用的定位器代码 |\n| `ariaSnapshot()` | 获取 ARIA 树快照 |\n| `resume()` | 恢复测试执行 |\n\n## 规范驱动测试\n\nPlaywright 支持基于规范的测试工作流，帮助团队从用户故事生成可执行的测试用例。\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()\n\n### 测试工作流\n\n```mermaid\ngraph LR\n A[编写规范] --> B[生成 Seed 测试]\n B --> C[探索应用]\n C --> D[完善规范]\n D --> E[生成测试代码]\n E --> F[运行测试]\n```\n\n### 规范文件结构\n\n```markdown\n# <功能> 测试计划\n\n## 应用概述\n<描述功能做什么以及为什么重要>\n\n## 测试场景\n\n### 1. <分组名称>\n**Seed:** `tests/seed.spec.ts`\n\n#### 1.1. <场景名称>\n**文件:** `tests//.spec.ts`\n\n**步骤:**\n 1. <具体用户操作>\n - expect: <可观察的结果>\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()\n\n### 探索应用\n\n```bash\n# 启动应用进行探索\nPLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli\n\n# 附加到调试会话\nplaywright-cli attach tw-XXXX\n\n# 探索命令\nplaywright-cli resume # 运行 seed 测试\nplaywright-cli snapshot # 元素清单\nplaywright-cli click e5 # 点击元素\nplaywright-cli eval \"location.href\" # 读取 URL/状态\nplaywright-cli show --annotate # 请求用户指向\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()\n\n## 总结\n\nPlaywright 是一个功能完整的跨浏览器测试框架，主要特点包括：\n\n- **多浏览器支持**：Chromium、Firefox、WebKit\n- **丰富的 CLI 工具**：playwright-cli 和 playwright-trace\n- **代码生成能力**：支持多种编程语言\n- **追踪可视化**：支持离线查看测试执行过程\n- **规范驱动测试**：支持从用户规范生成测试\n- **页面注入调试**：提供浏览器内调试 API\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目概述](#project-overview), [测试框架](#test-framework), [命令行工具](#cli-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/microsoft/playwright/blob/main/package.json)\n- [examples/svgomg/package.json](https://github.com/microsoft/playwright/blob/main/examples/svgomg/package.json)\n- [examples/todomvc/package.json](https://github.com/microsoft/playwright/blob/main/examples/todomvc/package.json)\n- [packages/playwright/package.json](https://github.com/microsoft/playwright/blob/main/packages/playwright/package.json)\n- [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)\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n \n\n# 快速入门\n\n## 概述\n\nPlaywright 是一个用于自动化 Web 浏览器的 Node.js 库，由 Microsoft 开发维护。它提供了高层次的 API，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎。Playwright 的主要特性包括：跨浏览器自动化、自动化等待机制、自动录制功能、以及强大的调试工具。\n\n当前版本为 **1.61.0-next**，最低要求 Node.js 18 及以上版本。\n\n## 安装 Playwright\n\n### 系统要求\n\n| 组件 | 要求 |\n|------|------|\n| Node.js | >= 18 |\n| 操作系统 | Windows、macOS、Linux |\n| 浏览器 | Chromium、Firefox、WebKit |\n\n### 安装命令\n\n```bash\n# 使用 npm 安装\nnpm install @playwright/test\n\n# 使用 yarn 安装\nyarn add @playwright/test\n\n# 使用 pnpm 安装\npnpm add @playwright/test\n```\n\n安装完成后，需要下载浏览器依赖：\n\n```bash\n# 下载所有浏览器\nnpx playwright install\n\n# 仅安装特定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n## 创建第一个测试\n\n### 项目结构\n\nPlaywright 测试项目通常包含以下文件：\n\n```\nmy-playwright-project/\n├── package.json\n├── playwright.config.ts\n├── tests/\n│ └── example.spec.ts\n└── playwright-report/\n```\n\n### 配置文件\n\n在项目根目录创建 `playwright.config.ts`：\n\n```typescript\nimport { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n testDir: './tests',\n fullyParallel: true,\n forbidOnly: !!process.env.CI,\n retries: process.env.CI ? 2 : 0,\n workers: process.env.CI ? 1 : undefined,\n reporter: 'html',\n use: {\n baseURL: 'http://localhost:3000',\n trace: 'on-first-retry',\n },\n projects: [\n {\n name: 'chromium',\n use: { ...devices['Desktop Chrome'] },\n },\n {\n name: 'firefox',\n use: { ...devices['Desktop Firefox'] },\n },\n {\n name: 'webkit',\n use: { ...devices['Desktop Safari'] },\n },\n ],\n});\n```\n\n资料来源：[examples/svgomg/package.json:1-13]()\n\n### 编写测试用例\n\n创建 `tests/example.spec.ts` 文件：\n\n```typescript\nimport { test, expect } from '@playwright/test';\n\ntest('has title', async ({ page }) => {\n await page.goto('https://example.com');\n await expect(page).toHaveTitle(/Example Domain/);\n});\n\ntest('get started link', async ({ page }) => {\n await page.goto('https://example.com');\n await page.getByRole('link', { name: 'More information' }).click();\n await expect(page).toHaveURL(/.*more/);\n});\n```\n\n## 运行测试\n\n### 基本命令\n\n| 命令 | 说明 |\n|------|------|\n| `npx playwright test` | 运行所有测试 |\n| `npx playwright test --project=chromium` | 仅运行 Chromium 测试 |\n| `npx playwright test tests/example.spec.ts` | 运行指定文件 |\n| `npx playwright test --grep \"login\"` | 运行匹配的测试 |\n\n### 调试模式\n\n使用 CLI 调试模式启动测试：\n\n```bash\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n```\n\n调试时会输出会话名称，格式为 `tw-XXXX`。使用 `playwright-cli` 附加到该会话进行调试：\n\n```bash\nplaywright-cli attach tw-XXXX\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md:1-21]()\n\n## Playwright CLI 工具\n\n`playwright-cli` 是 Playwright 提供的命令行交互工具，支持浏览器会话管理、元素交互、快照获取等功能。\n\n### 常用命令\n\n#### 浏览器会话管理\n\n```bash\n# 打开浏览器\nplaywright-cli open https://example.com\n\n# 使用指定浏览器\nplaywright-cli open https://example.com --browser=firefox\n\n# 有头模式\nplaywright-cli open https://example.com --headed\n\n# 关闭所有浏览器\nplaywright-cli close-all\n\n# 强制终止所有浏览器进程\nplaywright-cli kill-all\n```\n\n#### 页面交互\n\n```bash\n# 点击元素（使用快照中的 ref）\nplaywright-cli click e5\n\n# 使用 CSS 选择器\nplaywright-cli click \"#main > button.submit\"\n\n# 填写输入框\nplaywright-cli fill e2 \"test input\"\n\n# 获取快照\nplaywright-cli snapshot\n\n# 截图\nplaywright-cli screenshot --filename=page.png\n```\n\n#### 元素定位\n\nPlaywright 支持多种定位策略：\n\n| 定位方式 | 示例 |\n|----------|------|\n| CSS 选择器 | `\"#main > button.submit\"` |\n| Role 定位器 | `\"getByRole('button', { name: 'Submit' })\"` |\n| 测试 ID | `\"getByTestId('submit-button')\"` |\n| 快照引用 | `e5`, `e15` |\n\n#### 网络拦截\n\n```bash\n# 拦截请求返回 404\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 拦截并返回 mock 数据\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md:1-120]()\n\n### 持久化会话\n\n使用命名会话可以保持浏览器状态：\n\n```bash\n# 创建持久化会话\nplaywright-cli -s=mysession open https://example.com --persistent\n\n# 附加到会话\nplaywright-cli -s=mysession click e6\n\n# 关闭会话\nplaywright-cli -s=mysession close\n\n# 删除会话数据\nplaywright-cli -s=mysession delete-data\n```\n\n## 追踪与调试\n\n### 追踪功能\n\nPlaywright 可以录制完整的测试执行轨迹，包含 DOM 快照、截图、网络活动和控制台日志。\n\n#### 使用 CLI 录制追踪\n\n```bash\n# 开始录制\nplaywright-cli tracing-start\n\n# 执行操作\nplaywright-cli open https://example.com\nplaywright-cli click e1\nplaywright-cli fill e2 \"test\"\n\n# 停止录制\nplaywright-cli tracing-stop\n```\n\n录制完成后，会在 `traces/` 目录下生成以下文件：\n\n| 文件 | 说明 |\n|------|------|\n| `trace-{timestamp}.trace` | 动作日志，包含所有操作、DOM 快照、截图 |\n| `trace-{timestamp}.network` | 网络日志，包含所有请求和响应 |\n| `resources/` | 缓存的资源文件 |\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/tracing.md:1-45]()\n\n### Trace Viewer\n\n使用 Playwright Trace CLI 查看追踪文件：\n\n```bash\n# 打开追踪文件\nnpx playwright trace open \n\n# 查看所有动作\nnpx playwright trace actions\n\n# 查看失败的动作\nnpx playwright trace actions --errors-only\n\n# 查看动作详情\nnpx playwright trace action \n\n# 查看快照\nnpx playwright trace snapshot \n\n# 查看控制台错误\nnpx playwright trace console --errors-only\n\n# 查看失败的请求\nnpx playwright trace requests --failed\n\n# 关闭追踪\nnpx playwright trace close\n```\n\n典型调查流程：\n\n```bash\n# 1. 打开追踪文件\nnpx playwright trace open test-results/my-test/trace.zip\n\n# 2. 查看执行的动作\nnpx playwright trace actions\n\n# 3. 查看失败的动作\nnpx playwright trace actions --errors-only\n\n# 4. 查看详情\nnpx playwright trace action 12\n\n# 5. 查看页面快照\nnpx playwright trace snapshot 12\n\n# 6. 查询 DOM 获取更多细节\nnpx playwright trace snapshot 12 -- eval \"document.querySelector('.error-message').textContent\"\n\n# 7. 检查网络失败\nnpx playwright trace requests --failed\n\n# 8. 检查控制台错误\nnpx playwright trace console --errors-only\n```\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md:1-75]()\n\n## 浏览器会话与存储\n\n### 保存和加载状态\n\n```bash\n# 保存状态\nplaywright-cli state-save auth.json\n\n# 加载状态\nplaywright-cli state-load auth.json\n```\n\n### Cookie 管理\n\n```bash\n# 列出所有 Cookie\nplaywright-cli cookie-list\n\n# 按域名过滤\nplaywright-cli cookie-list --domain=example.com\n\n# 获取指定 Cookie\nplaywright-cli cookie-get session_id\n\n# 设置 Cookie\nplaywright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure\n\n# 删除 Cookie\nplaywright-cli cookie-delete session_id\n\n# 清除所有 Cookie\nplaywright-cli cookie-clear\n```\n\n### 本地存储\n\n```bash\n# LocalStorage\nplaywright-cli localstorage-list\nplaywright-cli localstorage-get theme\nplaywright-cli localstorage-set theme dark\nplaywright-cli localstorage-delete theme\nplaywright-cli localstorage-clear\n\n# SessionStorage\nplaywright-cli sessionstorage-list\nplaywright-cli sessionstorage-set step 3\nplaywright-cli sessionstorage-delete step\nplaywright-cli sessionstorage-clear\n```\n\n## 代码执行\n\n### 使用 run-code 执行自定义代码\n\n```bash\n# 获取页面标题\nplaywright-cli run-code \"async page => {\n return await page.title();\n}\"\n\n# 获取当前 URL\nplaywright-cli run-code \"async page => {\n return page.url();\n}\"\n\n# 读取剪贴板\nplaywright-cli run-code \"async page => {\n await page.context().grantPermissions(['clipboard-read']);\n return await page.evaluate(() => navigator.clipboard.readText());\n}\"\n\n# 从文件执行代码\nplaywright-cli run-code --filename=script.js\n```\n\n### 使用 eval 执行 JavaScript\n\n```bash\n# 获取页面标题\nplaywright-cli eval \"document.title\"\n\n# 获取元素内容\nplaywright-cli eval \"el => el.textContent\" e5\n\n# 获取元素属性\nplaywright-cli eval \"el => el.getAttribute('data-testid')\" e5\n\n# 保存结果到文件\nplaywright-cli eval \"document.body.outerHTML\" --filename=page.html\n```\n\n## 运行 npm 脚本示例\n\n项目中的 `package.json` 定义了常用的测试脚本：\n\n| 脚本 | 说明 |\n|------|------|\n| `npm run test` | 运行所有浏览器测试 |\n| `npm run ctest` | 仅运行 Chromium 测试 |\n| `npm run ftest` | 仅运行 Firefox 测试 |\n| `npm run wtest` | 仅运行 WebKit 测试 |\n\n资料来源：[package.json:19-35]()\n\n## 快速参考\n\n### 一分钟启动\n\n```bash\n# 1. 初始化项目\nnpm init -y\n\n# 2. 安装 Playwright\nnpm install @playwright/test\n\n# 3. 安装浏览器\nnpx playwright install\n\n# 4. 创建配置\ncat > playwright.config.ts << 'EOF'\nimport { defineConfig } from '@playwright/test';\nexport default defineConfig({\n testDir: './tests',\n use: { baseURL: 'http://localhost:3000' },\n});\nEOF\n\n# 5. 运行测试\nnpx playwright test\n```\n\n### 常用命令速查\n\n| 操作 | 命令 |\n|------|------|\n| 运行所有测试 | `npx playwright test` |\n| 运行指定浏览器 | `npx playwright test --project=chromium` |\n| 生成测试 | `npx playwright test --generate` |\n| 显示 HTML 报告 | `npx playwright show-report` |\n| 调试测试 | `npx playwright test --debug` |\n| 录制追踪 | `npx playwright show-trace trace.zip` |\n\n---\n\n\n\n## 架构概览\n\n### 相关页面\n\n相关主题：[客户端实现](#client-implementation), [服务器端实现](#server-implementation), [浏览器支持](#browser-support)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/client/connection.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/connection.ts)\n- [packages/playwright-core/src/remote/playwrightServer.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/remote/playwrightServer.ts)\n- [packages/playwright-core/src/inprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/inprocess.ts)\n- [packages/playwright-core/src/outofprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/outofprocess.ts)\n \n\n# 架构概览\n\nPlaywright 是一个用于自动化浏览器操作的高级 API 库。本页面详细介绍其核心架构设计，包括进程模型、客户端-服务器通信机制以及主要组件的职责划分。\n\n## 核心设计理念\n\nPlaywright 的架构围绕两个核心目标设计：\n\n| 目标 | 说明 |\n|------|------|\n| **跨浏览器一致性** | 提供统一的 API 接口，支持 Chromium、Firefox 和 WebKit 三种浏览器引擎 |\n| **灵活的进程模型** | 支持进程内（in-process）和进程外（out-of-process）两种执行模式 |\n\nPlaywright 的核心代码位于 `packages/playwright-core/` 包中，负责处理底层浏览器通信和 API 实现。\n\n## 进程模型\n\nPlaywright 支持两种进程模型，开发者可以根据场景选择适合的模式。\n\n### 进程外模式（Out-of-Process）\n\n进程外模式是 Playwright 的默认和推荐模式。在此模式下，Playwright 会在独立进程中启动浏览器，并通过 IPC（进程间通信）与浏览器进行交互。\n\n```mermaid\ngraph TD\n A[Playwright Client] -->|IPC| B[Playwright Server Process]\n B -->|CDP Protocol| C[Chromium]\n B -->|CDP Protocol| D[Firefox]\n B -->|CDP Protocol| E[WebKit]\n \n B --> F[Browser Processes]\n F --> G[Renderer Processes]\n F --> H[GPU Process]\n```\n\n**特点：**\n- 隔离性强，浏览器崩溃不会影响主进程\n- 支持远程连接（Remote Connection）\n- 便于调试和监控\n- 通过 `playwright-core/src/outofprocess.ts` 实现\n\n资料来源：[packages/playwright-core/src/outofprocess.ts:1-50]()\n\n### 进程内模式（In-Process）\n\n进程内模式将 Playwright 和浏览器运行在同一进程中，减少了进程间通信的开销。此模式主要用于：\n\n- 测试框架集成（如 `@playwright/test`）\n- 需要快速执行的场景\n- 与宿主应用紧密集成的用例\n\n```mermaid\ngraph LR\n A[Host Application] -->|Direct API| B[Playwright In-Process]\n B --> C[Browser Instance]\n```\n\n资料来源：[packages/playwright-core/src/inprocess.ts:1-30]()\n\n## 客户端连接架构\n\nPlaywright 的客户端通过 `Connection` 类建立与服务器端的通信通道。\n\n### 连接类型\n\n| 连接类型 | 适用场景 | 实现文件 |\n|----------|----------|----------|\n| **远程连接（Remote）** | 连接到独立的 Playwright 服务器进程 | `connection.ts` |\n| **本地连接（Local）** | 直接连接到同进程或子进程的服务器 | `connection.ts` |\n| **CDP 连接** | 直接使用 Chrome DevTools Protocol | `connection.ts` |\n\n### 连接生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as Playwright Client\n participant Conn as Connection\n participant Server as Playwright Server\n \n Client->>Conn: createConnection()\n Conn->>Server: establishTransport()\n Server-->>Conn: transportEstablished\n Conn-->>Client: connected\n \n Client->>Conn: sendMessage()\n Conn->>Server: dispatch()\n Server-->>Conn: response\n Conn-->>Client: callback\n \n Client->>Conn: close()\n Conn->>Server: disconnect()\n```\n\n资料来源：[packages/playwright-core/src/client/connection.ts:1-100]()\n\n## 服务器端架构\n\nPlaywright 服务器端负责管理浏览器实例和处理来自客户端的请求。\n\n### 服务器组件\n\n| 组件 | 职责 |\n|------|------|\n| **PlaywrightServer** | 主服务器类，管理所有浏览器会话 |\n| **BrowserSession** | 管理单个浏览器实例的生命周期 |\n| **ChromiumBrowser** | Chromium 特定实现 |\n| **FirefoxBrowser** | Firefox 特定实现 |\n| **WebKitBrowser** | WebKit 特定实现 |\n\n### 服务器传输层\n\n服务器支持多种传输协议：\n\n- **stdio 传输**：用于父子进程通信\n- **WebSocket 传输**：用于远程连接\n- **CDP 传输**：直接与浏览器 DevTools 端口通信\n\n资料来源：[packages/playwright-core/src/remote/playwrightServer.ts:1-80]()\n\n## 浏览器会话管理\n\nPlaywright 通过会话（Session）机制管理多个独立的浏览器上下文。\n\n### 会话类型\n\n```mermaid\ngraph TD\n A[PlaywrightServer] --> B[BrowserSession 1]\n A --> C[BrowserSession 2]\n A --> D[BrowserSession N]\n \n B --> E[BrowserContext 1]\n B --> F[BrowserContext 2]\n \n E --> G[Page 1]\n E --> H[Page 2]\n G --> I[Frame]\n```\n\n### 持久化会话\n\nPlaywright 支持持久化会话（Persistent Context），允许保存和恢复浏览器状态：\n\n```bash\n# 创建命名会话\nplaywright-cli -s=mysession open https://example.com --persistent\n\n# 指定配置文件目录\nplaywright-cli -s=mysession open https://example.com --profile=/path/to/profile\n```\n\n这对于需要保持登录状态的测试场景非常有用。\n\n## 命令执行流程\n\nPlaywright CLI 提供了丰富的命令行接口来与浏览器交互。\n\n### 核心命令处理\n\n```\nplaywright-cli open → Browser.open()\nplaywright-cli goto → Page.goto()\nplaywright-cli click → Page.click()\nplaywright-cli fill → Page.fill()\n```\n\n### 元素定位策略\n\nPlaywright 支持多种元素定位方式：\n\n| 定位方式 | 示例 | 优先级 |\n|----------|------|--------|\n| **Ref 引用** | `e15` | 最高（快照生成） |\n| **CSS 选择器** | `#main > button` | 高 |\n| **角色定位器** | `getByRole('button')` | 高 |\n| **测试 ID** | `getByTestId('submit')` | 中 |\n| **文本内容** | `getByText('Submit')` | 中 |\n\n## 网络拦截\n\nPlaywright 提供了强大的网络拦截功能，用于测试和调试。\n\n### 路由（Route）操作\n\n```bash\n# 拦截特定请求\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 修改响应内容\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\n```\n\n### 存储管理\n\n| 存储类型 | 列表 | 获取 | 设置 | 删除 |\n|----------|------|------|------|------|\n| **Cookies** | `cookie-list` | `cookie-get` | `cookie-set` | `cookie-delete` |\n| **LocalStorage** | `localstorage-list` | `localstorage-get` | `localstorage-set` | `localstorage-delete` |\n| **SessionStorage** | `sessionstorage-list` | `sessionstorage-get` | `sessionstorage-set` | `sessionstorage-delete` |\n\n## 跟踪与调试\n\nPlaywright 的跟踪功能可以捕获详细的执行信息，用于问题排查和性能分析。\n\n### 跟踪文件结构\n\n```\ntraces/\n├── trace-{timestamp}.trace # 操作日志\n├── trace-{timestamp}.network # 网络活动\n└── resources/ # 缓存资源\n```\n\n### CLI 跟踪命令\n\n```bash\n# 开始跟踪\nplaywright-cli tracing-start\n\n# 执行测试操作\nplaywright-cli click e1\nplaywright-cli fill e2 \"test\"\n\n# 停止跟踪\nplaywright-cli tracing-stop\n```\n\n## 扩展机制\n\nPlaywright 支持通过插件扩展功能。\n\n### MCP 集成\n\nPlaywright 提供了 MCP（Model Context Protocol）服务器集成，可以通过 AI 助手控制浏览器：\n\n```bash\n# 运行 MCP 测试\nnpm run test-mcp\n```\n\n### 扩展测试\n\n```bash\n# 测试扩展功能\nnpm run test-extension\n```\n\n## 包结构\n\n| 包名 | 说明 |\n|------|------|\n| `playwright-core` | 核心库，包含所有底层实现 |\n| `@playwright/test` | 测试框架，提供 `test()` 和 `expect()` |\n| `playwright` | 完整包，包含浏览器驱动 |\n| `@playwright/browser-chromium` | Chromium 浏览器驱动 |\n| `@playwright/browser-firefox` | Firefox 浏览器驱动 |\n| `@playwright/browser-webkit` | WebKit 浏览器驱动 |\n| `playwright-chromium` | Chromium 便捷包 |\n| `playwright-firefox` | Firefox 便捷包 |\n| `playwright-webkit` | WebKit 便捷包 |\n\n## 总结\n\nPlaywright 的架构设计体现了现代浏览器自动化的最佳实践：\n\n1. **双进程模型**：灵活支持进程内和进程外执行\n2. **统一 API**：跨浏览器提供一致的接口\n3. **可扩展设计**：支持插件和 MCP 集成\n4. **强大的调试能力**：内置跟踪、快照和 CLI 工具\n\n---\n\n\n\n## 客户端实现\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [服务器端实现](#server-implementation), [定位器和选择器](#locators-and-selectors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/client/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/page.ts)\n- [packages/playwright-core/src/client/frame.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/frame.ts)\n- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)\n- [packages/playwright-core/src/client/elementHandle.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/elementHandle.ts)\n- [packages/playwright-core/src/client/browserContext.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/browserContext.ts)\n- [packages/playwright-core/src/client/channelOwner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/channelOwner.ts)\n \n\n# 客户端实现\n\n## 概述\n\nPlaywright 的客户端实现是库的核心组成部分，它为开发者提供了操作浏览器的编程接口。客户端层封装了与浏览器驱动程序通信的底层细节，提供了高级 API 用于页面导航、元素交互、表单填写、截图等操作。\n\nPlaywright 采用 **Channel（通道）** 架构进行客户端与服务端通信。客户端实现位于 `packages/playwright-core/src/client/` 目录下，包含了所有与浏览器交互的 TypeScript 类和接口。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[开发者代码] --> B[Client API]\n B --> C[Locator API]\n B --> D[Page API]\n B --> E[BrowserContext API]\n C --> F[ChannelOwner]\n D --> F\n E --> F\n F --> G[Playwright Driver]\n G --> H[Browser Process]\n G --> I[CDP Connection]\n H --> J[Chromium/Firefox/WebKit]\n```\n\n客户端实现采用了分层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| API 层 | Page, Frame, Locator, ElementHandle | 提供高级用户接口 |\n| 通道层 | ChannelOwner | 管理与驱动程序的通信通道 |\n| 传输层 | Playwright Driver | 处理协议编解码和消息传递 |\n\n## 核心组件\n\n### ChannelOwner 基类\n\n`ChannelOwner` 是所有客户端对象的基类，负责：\n\n- 管理与 Playwright Driver 的底层通信通道\n- 处理远程过程调用（RPC）\n- 管理对象的生命周期\n- 处理事件订阅和分发\n\n所有客户端对象（Page、Frame、BrowserContext、Locator 等）都继承自 `ChannelOwner`，共享相同的通信机制和生命周期管理模式。\n\n### Page 类\n\n`Page` 代表浏览器中的一个页面，是最常用的交互入口。主要功能包括：\n\n| 功能类别 | 方法示例 | 说明 |\n|----------|----------|------|\n| 导航 | goto, goBack, goForward, reload | 页面导航控制 |\n| 交互 | click, fill, hover, type | 用户操作模拟 |\n| 状态 | title, url, content | 获取页面信息 |\n| 截图 | screenshot, pdf | 页面内容导出 |\n| 等待 | waitForSelector, waitForLoadState | 条件等待机制 |\n\n### Frame 类\n\n`Frame` 表示页面中的一个 iframe 或主框架。Playwright 中的 Frame 实现支持：\n\n- 嵌套框架的遍历和定位\n- 框架级别的操作隔离\n- 跨框架元素交互\n\n### Locator API\n\nLocator 是 Playwright 现代化的元素定位和交互方式，相比传统的 `ElementHandle`，Locator 具有以下优势：\n\n| 特性 | ElementHandle | Locator |\n|------|---------------|---------|\n| 定位时机 | 创建时立即定位 | 操作时延迟定位 |\n| 重试机制 | 无自动重试 | 自动重试直到元素可操作 |\n| 稳定性 | 可能因 DOM 变化失效 | 每次操作重新定位 |\n| 链式调用 | 不支持 | 支持链式定位 |\n\nLocator 提供了丰富的方法链：\n\n```typescript\n// 链式定位示例\nlocator\n .frameLocator('#iframe')\n .locator('button.submit')\n .click();\n```\n\n### ElementHandle 类\n\n`ElementHandle` 代表 DOM 中的一个元素，提供直接的元素级操作：\n\n- `click()` - 点击元素\n- `fill()` - 填写表单\n- `hover()` - 鼠标悬停\n- `evaluate()` - 在元素上下文中执行 JavaScript\n\n### BrowserContext 类\n\n`BrowserContext` 表示一个独立的浏览器会话，具有以下特性：\n\n| 特性 | 说明 |\n|------|------|\n| 隔离存储 | 独立的 Cookie、LocalStorage、SessionStorage |\n| 并行执行 | 可创建多个 Context 同时运行 |\n| 权限控制 | 可精细控制地理位置、摄像头等权限 |\n| 隐私模式 | 每个 Context 相互隔离 |\n\n## 对象关系图\n\n```mermaid\ngraph LR\n A[Browser] --> B[BrowserContext]\n B --> C[Page]\n C --> D[Frame]\n D --> E[ElementHandle]\n C --> F[Locator]\n F -.-> E\n B --> G[BrowserServer]\n B --> H[Tracing]\n```\n\n核心对象关系：\n\n- **Browser** 可以包含多个独立的 **BrowserContext**\n- 每个 **BrowserContext** 可以包含多个 **Page**\n- **Page** 包含一个主 **Frame** 和可能的嵌套 **Frame**\n- **ElementHandle** 和 **Locator** 都用于定位和操作 **Frame** 中的 DOM 元素\n\n## 生命周期管理\n\n### 对象创建\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant API as Client API\n participant Channel as ChannelOwner\n participant Driver as Playwright Driver\n \n User->>API: new Page(channel)\n API->>Channel: 初始化通道\n Channel->>Driver: 创建远程对象\n Driver-->>Channel: 返回对象引用\n Channel-->>API: 返回实例\n API-->>User: Page 实例\n```\n\n### 资源释放\n\n客户端对象在以下情况下会被自动或手动释放：\n\n1. **显式关闭**：调用 `page.close()`, `context.close()`\n2. **作用域结束**：在测试框架中，测试完成后自动清理\n3. **强制关闭**：调用 `browser.close()` 关闭整个浏览器\n\n## 事件系统\n\n客户端实现了基于订阅的事件系统：\n\n| 事件类型 | 触发时机 | 使用场景 |\n|----------|----------|----------|\n| `load` | 页面加载完成 | 等待页面就绪 |\n| `domcontentloaded` | DOM 解析完成 | 快速验证 |\n| `console` | 控制台消息 | 调试和日志 |\n| `request` | 网络请求发起 | 流量监控 |\n| `response` | 网络响应接收 | 断言验证 |\n| `crash` | 页面崩溃 | 错误处理 |\n\n## 等待机制\n\nPlaywright 客户端提供了智能的等待机制来处理异步操作：\n\n### 内置等待\n\n| 等待类型 | 说明 |\n|----------|------|\n| 导航等待 | 自动等待页面加载完成 |\n| 元素等待 | 等待元素出现、可见、可点击 |\n| 函数等待 | 等待条件满足 |\n| 超时控制 | 可配置全局或单次超时 |\n\n### 自定义等待\n\n```typescript\n// 等待元素包含特定文本\nawait page.locator('div.status').waitFor({ \n hasText: 'Success' \n});\n\n// 等待函数返回 true\nawait page.waitForFunction(() => {\n return document.querySelectorAll('li').length > 10;\n});\n```\n\n## 错误处理\n\n客户端实现了完善的错误处理机制：\n\n| 错误类型 | 触发条件 | 处理建议 |\n|----------|----------|----------|\n| TimeoutError | 操作超时 | 增加超时时间或检查页面状态 |\n| TargetClosedError | 目标已关闭 | 检查对象生命周期 |\n| NotFoundError | 元素未找到 | 验证选择器或等待条件 |\n| NavigationError | 导航失败 | 检查网络或 URL |\n\n## 与 CLI 的集成\n\nPlaywright CLI (`playwright-cli`) 提供了命令行界面的浏览器自动化能力，与客户端 API 共享相同的底层实现：\n\n```bash\n# CLI 命令对应客户端 API\nplaywright-cli click e15 # => page.locator('#selector').click()\nplaywright-cli screenshot # => page.screenshot()\nplaywright-cli goto url # => page.goto(url)\n```\n\nCLI 和客户端共享相同的 Page、Frame、Locator 实现，保证了行为一致性。\n\n## 源码结构\n\n```\npackages/playwright-core/src/client/\n├── channelOwner.ts # 基础通道所有者类\n├── page.ts # 页面实现\n├── frame.ts # 框架实现\n├── locator.ts # 定位器实现\n├── elementHandle.ts # 元素句柄实现\n├── browserContext.ts # 浏览器上下文\n├── browser.ts # 浏览器实例\n└── ...\n```\n\n## 总结\n\nPlaywright 的客户端实现提供了一套完整、高层次的浏览器自动化 API。其核心设计理念包括：\n\n1. **统一通道架构**：所有客户端对象通过 ChannelOwner 与驱动程序通信\n2. **延迟定位**：Locator 机制确保元素操作的稳定性\n3. **智能等待**：内置自动等待，减少 flaky tests\n4. **丰富的事件系统**：支持各种页面状态和行为的监控\n5. **完善的错误处理**：清晰的错误类型和合理的默认行为\n\n这套客户端架构使得开发者能够以声明式的方式编写浏览器自动化测试和脚本，同时保证了跨浏览器的一致性。\n\n---\n\n\n\n## 服务器端实现\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [客户端实现](#client-implementation), [浏览器支持](#browser-support)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/server/browser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browser.ts)\n- [packages/playwright-core/src/server/browserContext.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browserContext.ts)\n- [packages/playwright-core/src/server/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/page.ts)\n- [packages/playwright-core/src/server/dispatchers/dispatcher.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/dispatchers/dispatcher.ts)\n- [packages/playwright-core/src/server/network.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/network.ts)\n- [packages/playwright-core/src/server/index.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/index.ts)\n \n\n# 服务器端实现\n\n## 概述\n\nPlaywright 的服务器端实现是框架的核心架构层，负责在 Node.js 环境中管理与浏览器实例的通信。该层封装了浏览器启动、页面操作、网络拦截、上下文隔离等底层功能，为上层 API 提供统一的接口抽象。\n\n服务器端实现的主要职责包括：\n\n- 管理浏览器进程的生命周期\n- 处理跨进程通信协议\n- 协调浏览器上下文和页面状态\n- 处理网络请求和响应\n- 分发器（Dispatcher）模式的消息路由\n\n资料来源：[packages/playwright-core/src/server/index.ts:1-20]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[playwright-core] --> B[Server Index]\n B --> C[Browser]\n B --> D[BrowserContext]\n B --> E[Page]\n B --> F[Network]\n C --> D\n D --> E\n E --> F\n B --> G[Dispatcher]\n G --> C\n G --> D\n G --> E\n G --> F\n```\n\n### 层次结构\n\nPlaywright 服务器端采用分层架构设计，从底层到高层依次为：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 传输层 | Protocol 协议 | 定义客户端与服务端的消息格式 |\n| 路由层 | Dispatcher | 消息分发与路由 |\n| 业务层 | Browser/Context/Page | 核心业务逻辑 |\n| 实现层 | Browser API | 与底层浏览器通信 |\n\n资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts:1-30]()\n\n## Browser 服务器实现\n\n### Browser 类职责\n\nBrowser 类是服务器端的核心入口，负责以下功能：\n\n- 浏览器进程启动与关闭\n- 浏览器类型检测（Chromium/Firefox/WebKit）\n- 版本信息管理\n- 发射器（Launch Server）管理\n\n### 主要方法\n\n```typescript\nclass Browser {\n // 启动浏览器\n async launch(options: LaunchOptions): Promise\n \n // 连接已存在的浏览器\n async connect(wsEndpoint: string): Promise\n \n // 创建新上下文\n async newContext(options?: ContextOptions): Promise\n \n // 关闭浏览器\n async close(): Promise\n \n // 获取所有上下文\n contexts(): BrowserContext[]\n}\n```\n\n资料来源：[packages/playwright-core/src/server/browser.ts:30-100]()\n\n### 浏览器上下文管理\n\n```mermaid\ngraph LR\n A[Browser] -->|创建| B[BrowserContext 1]\n A -->|创建| C[BrowserContext 2]\n A -->|创建| D[BrowserContext N]\n B --> E[Page 1]\n B --> F[Page 2]\n C --> G[Page 3]\n D --> H[Page 4]\n```\n\n## BrowserContext 服务器实现\n\nBrowserContext 代表一个独立的浏览器会话，每个上下文拥有独立的存储空间、Cookie、缓存等。\n\n### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 隔离存储 | 独立的 localStorage、sessionStorage |\n| Cookie 隔离 | 每个上下文维护独立的 Cookie 存储 |\n| 权限管理 | 可独立控制地理位置、摄像头等权限 |\n| 代理配置 | 支持为单个上下文配置代理服务器 |\n\n### 主要方法\n\n```typescript\nclass BrowserContext {\n // 创建新页面\n async newPage(): Promise\n \n // 添加 cookies\n async addCookies(cookies: Cookie[]): Promise\n \n // 获取 cookies\n async cookies(urls?: string[]): Promise\n \n // 清除所有 cookies\n async clearCookies(): Promise\n \n // 授权权限\n async grantPermissions(permissions: string[]): Promise\n \n // 截图\n async screenshot(options?: ScreenshotOptions): Promise\n \n // 关闭上下文\n async close(): Promise\n}\n```\n\n资料来源：[packages/playwright-core/src/server/browserContext.ts:50-150]()\n\n## Page 服务器实现\n\nPage 类代表浏览器中的一个标签页或框架，是与网页内容交互的主要接口。\n\n### 元素定位与交互\n\n```typescript\nclass Page {\n // 元素定位\n locator(selector: string): Locator\n getByRole(role: AriaRole, options?: GetByRoleOptions): Locator\n getByText(text: string, options?: GetByTextOptions): Locator\n getByTestId(testId: string): Locator\n \n // 交互操作\n async click(selector: string, options?: ClickOptions): Promise\n async fill(selector: string, value: string): Promise\n async type(selector: string, text: string, options?: TypeOptions): Promise\n async hover(selector: string): Promise\n async dragAndDrop(source: string, target: string): Promise\n}\n```\n\n### 导航操作\n\n```typescript\nclass Page {\n // 页面导航\n async goto(url: string, options?: GotoOptions): Promise\n async goBack(options?: NavigationOptions): Promise\n async goForward(options?: NavigationOptions): Promise\n async reload(options?: NavigationOptions): Promise\n \n // 等待导航完成\n async waitForNavigation(options?: WaitForNavigationOptions): Promise\n \n // 事件监听\n async waitForLoadState(state: LoadState): Promise\n waitForURL(url: string | RegExp): Promise\n}\n```\n\n资料来源：[packages/playwright-core/src/server/page.ts:100-250]()\n\n## Dispatcher 分发器\n\nDispatcher 是 Playwright 服务器端的消息路由核心，采用发布-订阅模式处理客户端请求。\n\n### 工作原理\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[Protocol Handler]\n B --> C[Dispatcher]\n C --> D{路由判断}\n D -->|Browser| E[BrowserDispatcher]\n D -->|Context| F[BrowserContextDispatcher]\n D -->|Page| G[PageDispatcher]\n D -->|Network| H[NetworkDispatcher]\n E --> I[执行结果]\n F --> I\n G --> I\n H --> I\n```\n\n### 消息流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Protocol as Protocol Handler\n participant Dispatcher as Dispatcher\n participant Handler as 业务处理器\n \n Client->>Protocol: 发送命令\n Protocol->>Dispatcher: 路由消息\n Dispatcher->>Handler: 分发请求\n Handler->>Handler: 处理业务逻辑\n Handler-->>Dispatcher: 返回结果\n Dispatcher-->>Protocol: 格式化响应\n Protocol-->>Client: 返回执行结果\n```\n\n### Dispatcher 基类\n\n```typescript\nclass Dispatcher {\n // 构造函数接收根对象和唯一标识\n constructor(scope: object, uid: number)\n \n // 内部对象引用\n protected _scope: object\n protected _uid: number\n \n // 回调方法\n protected _dispatchEvent(method: string, params: any): void\n protected _writeObjectToLog(logName: string, obj: any): void\n}\n```\n\n资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts:30-80]()\n\n## Network 网络管理\n\nNetwork 模块负责处理页面的网络请求和响应，支持请求拦截、修改、模拟等功能。\n\n### 网络拦截\n\n```typescript\nclass Route {\n // 继续请求（可选修改）\n async continue(options?: ContinueRequestOptions): Promise\n \n // 完成响应\n async fulfill(response: Partial): Promise\n \n // 中止请求\n async abort(errorCode?: string): Promise\n}\n\nclass Request {\n // 获取请求信息\n url(): string\n method(): string\n headers(): Record\n postData(): string | null\n \n // 响应对象\n response(): Response | null\n}\n```\n\n### 路由规则配置\n\n| 方法 | 说明 |\n|------|------|\n| `route(url, handler)` | 为匹配 URL 的请求设置处理函数 |\n| `unroute(url, handler?)` | 移除路由规则 |\n| `routeList()` | 列出所有活动路由 |\n\n资料来源：[packages/playwright-core/src/server/network.ts:50-120]()\n\n## 服务器启动流程\n\n```mermaid\ngraph TD\n A[导入 Server Index] --> B[初始化传输层]\n B --> C[加载浏览器驱动]\n C --> D{检查浏览器安装}\n D -->|未安装| E[触发自动安装]\n D -->|已安装| F[启动浏览器进程]\n F --> G[建立 WebSocket 连接]\n G --> H[初始化 Dispatcher]\n H --> I[导出公共 API]\n I --> J[服务器就绪]\n```\n\n## 关键配置选项\n\n### 浏览器启动配置\n\n| 选项 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `headless` | boolean | 是否无头模式运行 | true |\n| `args` | string[] | 浏览器启动参数 | [] |\n| `proxy` | ProxyOptions | 代理服务器配置 | undefined |\n| `viewport` | Viewport | 视口大小 | 800x600 |\n| `userAgent` | string | 用户代理字符串 | 浏览器默认 |\n| `timeout` | number | 操作超时时间(毫秒) | 30000 |\n\n### 上下文配置\n\n| 选项 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `storageState` | string/StorageState | 预加载存储状态 | undefined |\n| `permissions` | string[] | 默认授权的权限 | [] |\n| `geolocation` | Geolocation | 地理位置模拟 | undefined |\n| `ignoreHTTPSErrors` | boolean | 忽略 HTTPS 错误 | false |\n| `baseURL` | string | 相对 URL 的基础地址 | undefined |\n\n资料来源：[packages/playwright-core/src/server/browserContext.ts:200-280]()\n\n## 与客户端的通信\n\nPlaywright 服务器端通过 CDP（Chrome DevTools Protocol）协议与浏览器通信，同时通过自定义协议与 Node.js 客户端交互。\n\n```mermaid\ngraph LR\n A[Node.js 客户端] <-->|Playwright Protocol| B[Server]\n B <-->|CDP Protocol| C[Chromium]\n B <-->|CDP Protocol| D[Firefox]\n B <-->|WebKit Protocol| E[WebKit]\n```\n\n## 扩展与定制\n\n### 自定义浏览器驱动\n\n开发者可以通过继承 Browser 类来支持自定义浏览器：\n\n```typescript\nclass CustomBrowser extends Browser {\n protected async _launchServer(): Promise {\n // 自定义启动逻辑\n }\n}\n```\n\n### 添加新的协议处理器\n\n通过扩展 Dispatcher 基类，可以添加新的协议处理能力：\n\n```typescript\nclass CustomDispatcher extends Dispatcher {\n constructor(scope: object, uid: number) {\n super(scope, uid);\n }\n \n // 实现自定义方法\n async customMethod(params: any): Promise {\n // 处理逻辑\n }\n}\n```\n\n## 最佳实践\n\n### 资源管理\n\n- 及时关闭不再使用的 Page、BrowserContext\n- 使用 `async/await` 确保资源释放\n- 设置合理的超时时间避免资源泄漏\n\n### 错误处理\n\n```typescript\ntry {\n await page.goto('https://example.com', { timeout: 10000 });\n} catch (error) {\n if (error instanceof TimeoutError) {\n // 处理超时\n } else if (error instanceof net.Error) {\n // 处理网络错误\n }\n}\n```\n\n### 并发控制\n\n| 场景 | 推荐做法 |\n|------|----------|\n| 多页面并发 | 使用多个 BrowserContext |\n| 批量操作 | 控制并发数量避免资源耗尽 |\n| 资源密集型 | 考虑使用 `browser.close()` 释放资源 |\n\n## 相关模块索引\n\n| 模块路径 | 职责 |\n|----------|------|\n| `src/server/browser.ts` | 浏览器进程管理 |\n| `src/server/browserContext.ts` | 会话上下文管理 |\n| `src/server/page.ts` | 页面操作与交互 |\n| `src/server/dispatchers/dispatcher.ts` | 消息路由分发 |\n| `src/server/network.ts` | 网络请求拦截 |\n| `src/server/index.ts` | 服务端导出入口 |\n\n---\n\n本页面持续更新中，如有问题请提交 Issue 或 Pull Request。\n\n---\n\n\n\n## 浏览器支持\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [服务器端实现](#server-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/server/chromium/crBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/crBrowser.ts)\n- [packages/playwright-core/src/server/firefox/ffBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/firefox/ffBrowser.ts)\n- [packages/playwright-core/src/server/webkit/wkBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/webkit/wkBrowser.ts)\n- [packages/playwright-core/src/server/browserType.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browserType.ts)\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n- [packages/trace-viewer/src/ui/browserFrame.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/browserFrame.tsx)\n- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)\n- [packages/playwright-core/src/server/codegen/csharp.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/codegen/csharp.ts)\n \n\n# 浏览器支持\n\nPlaywright 是一个跨浏览器自动化测试框架，支持三大主流浏览器引擎：Chromium、Firefox 和 WebKit。每个浏览器都通过独立的实现模块进行抽象和管理，使得上层 API 能够以统一的方式与不同浏览器进行交互。\n\n## 支持的浏览器类型\n\nPlaywright 原生支持以下三种浏览器：\n\n| 浏览器 | 渲染引擎 | 协议实现 | 源码目录 |\n|--------|----------|----------|----------|\n| Chromium | Blink/V8 | Chrome DevTools Protocol (CDP) | `packages/playwright-core/src/server/chromium/` |\n| Firefox | Gecko/SpiderMonkey | Firefox DevTools Protocol (FDP) | `packages/playwright-core/src/server/firefox/` |\n| WebKit | WebKit/JavaScriptCore | Apple WebKit Protocol (WKP) | `packages/playwright-core/src/server/webkit/` |\n\n资料来源：[packages/playwright-core/src/server/browserType.ts]()\n\n## 浏览器启动流程\n\nPlaywright 的浏览器启动遵循统一的工厂模式，通过 `browserType.ts` 中的 `launch()` 方法创建浏览器实例。\n\n```mermaid\ngraph TD\n A[launchBrowser] --> B{浏览器类型}\n B -->|Chromium| C[createChromiumBrowser]\n B -->|Firefox| D[createFirefoxBrowser]\n B -->|WebKit| E[createWebKitBrowser]\n C --> F[连接 CDP 端口]\n D --> G[启动 Juggler 进程]\n E --> H[连接 WebKit 调试器]\n F --> I[返回 Browser 实例]\n G --> I\n H --> I\n```\n\n### 启动参数配置\n\n`launch()` 方法支持丰富的配置选项：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `headless` | boolean | 是否以无头模式运行，默认 `true` |\n| `channel` | string | 浏览器渠道，如 `chrome`, `chrome-beta`, `msedge` |\n| `args` | string[] | 传递给浏览器的额外命令行参数 |\n| `proxy` | object | 代理服务器配置 |\n| `downloadPath` | string | 下载文件保存路径 |\n| `viewport` | object | 视口尺寸配置 |\n| `userAgent` | string | 自定义 User-Agent |\n| `slowMo` | number | 操作延迟（毫秒），用于调试 |\n\n资料来源：[packages/playwright-core/src/server/browserType.ts]()\n\n## 浏览器会话管理\n\n### CLI 会话管理\n\nPlaywright CLI (`playwright-cli`) 提供了完整的浏览器会话管理能力：\n\n```bash\n# 创建新的命名会话\nplaywright-cli -s=mysession open https://example.com\n\n# 使用持久化配置文件\nplaywright-cli -s=mysession open https://example.com --persistent\n\n# 删除会话数据\nplaywright-cli -s=mysession delete-data\n\n# 关闭所有浏览器\nplaywright-cli close-all\n\n# 强制终止所有浏览器进程\nplaywright-cli kill-all\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md]()\n\n### 会话状态持久化\n\n浏览器状态可以通过以下方式保存和恢复：\n\n| 存储类型 | 命令 | 说明 |\n|----------|------|------|\n| 完整状态 | `state-save`, `state-load` | 保存/恢复 cookies、localStorage、sessionStorage |\n| Cookies | `cookie-list`, `cookie-set`, `cookie-delete` | 独立管理 cookies |\n| LocalStorage | `localstorage-list`, `localstorage-set` | 键值对存储 |\n| SessionStorage | `sessionstorage-list`, `sessionstorage-set` | 会话级存储 |\n\n```bash\n# 保存当前状态\nplaywright-cli state-save auth.json\n\n# 恢复状态\nplaywright-cli state-load auth.json\n```\n\n## 浏览器帧组件\n\nTrace Viewer 使用 `browserFrame.tsx` 组件渲染浏览器外观模拟，该组件展示地址栏、菜单栏等 UI 元素：\n\n```tsx\n\n {url || 'about:blank'}\n {url && }\n
\n```\n\n资料来源：[packages/trace-viewer/src/ui/browserFrame.tsx]()\n\n## 网络路由与拦截\n\nPlaywright 支持对网络请求进行拦截和修改：\n\n```bash\n# 拦截特定 URL 并返回自定义状态\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 使用自定义响应体\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\n```\n\n## 元素定位与交互\n\n### 角色定位器\n\nPlaywright 内置了基于 ARIA 角色的定位器支持，通过 `roleUtils.ts` 实现：\n\n| HTML 元素 | 默认 ARIA 角色 |\n|-----------|---------------|\n| `BUTTON` | button |\n| `A` | link |\n| `INPUT[type=\"search\"]` | searchbox |\n| `INPUT[type=\"email\"]` | textbox |\n| `SELECT` | listbox |\n| `DIALOG` | dialog |\n| `FORM` | form (仅当有显式可访问名称时) |\n| `IMG[alt=\"\"]` | presentation |\n| `IMG[alt!=\"\"]` | img |\n| `H1-H6` | heading |\n| `HEADER` | banner |\n| `FOOTER` | contentinfo |\n\n```typescript\n'INPUT': (e: Element) => {\n const type = (e as HTMLInputElement).type.toLowerCase();\n if (type === 'search')\n return e.hasAttribute('list') ? 'combobox' : 'searchbox';\n if (['email', 'tel', 'url'].includes(type))\n return 'textbox';\n}\n```\n\n资料来源：[packages/injected/src/roleUtils.ts]()\n\n### 元素交互命令\n\nPlaywright CLI 支持多种元素定位方式：\n\n```bash\n# 使用快照引用\nplaywright-cli click e15\n\n# CSS 选择器\nplaywright-cli click \"#main > button.submit\"\n\n# 角色定位器\nplaywright-cli click \"getByRole('button', { name: 'Submit' })\"\n\n# 测试 ID\nplaywright-cli click \"getByTestId('submit-button')\"\n```\n\n## 代码生成中的浏览器支持\n\n代码生成模块针对不同浏览器生成优化代码。以 C# 为例：\n\n```csharp\n// 检测是否为新页面操作\nif (action.name === 'openPage' || action.name === 'closePage')\n return '';\n\n// 生成页面变量\nvar page = await context.NewPageAsync();\n\n// 根据 URL 导航\nif (action.url)\n await page.GotoAsync(action.url);\n\n// 处理对话框事件\nvoid page_Dialog_EventHandler(object sender, IDialog dialog)\n{\n dialog.DismissAsync();\n}\n```\n\n资料来源：[packages/playwright-core/src/server/codegen/csharp.ts]()\n\n## Trace 与浏览器状态\n\nTrace Viewer 能够在不打开浏览器的情况下查看浏览器状态快照：\n\n```bash\n# 打开 trace 文件\nnpx playwright trace open test-results/my-test/trace.zip\n\n# 查看特定操作后的快照\nnpx playwright trace snapshot 12\n\n# 获取 DOM 内容\nnpx playwright trace snapshot 12 -- eval \"document.body.outerHTML\"\n```\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n### Trace 元数据展示\n\nTrace Viewer 通过 `MetadataView` 组件展示浏览器元数据：\n\n| 元数据字段 | 说明 |\n|-----------|------|\n| playwrightVersion | Playwright 版本 |\n| userAgent | 用户代理字符串 |\n| baseURL | 基础 URL 配置 |\n| viewport | 视口尺寸 (width × height) |\n| isMobile | 是否移动设备模拟 |\n| deviceScaleFactor | 设备像素比 |\n\n资料来源：[packages/trace-viewer/src/ui/metadataView.tsx]()\n\n## 浏览器环境变量\n\n| 环境变量 | 作用 |\n|----------|------|\n| `PLAYWRIGHT_CLI_SESSION` | 设置默认浏览器会话名称 |\n| `PLAYWRIGHT_HTML_OPEN` | 控制 HTML 报告打开行为 |\n| `PLAYWRIGHT_BROWSERS_PATH` | 浏览器可执行文件存储路径 |\n\n## 最佳实践\n\n### 会话命名规范\n\n```bash\n# 推荐：清晰的命名\nplaywright-cli -s=github-auth open https://github.com\nplaywright-cli -s=docs-scrape open https://docs.example.com\n\n# 避免：通用命名\nplaywright-cli -s=s1 open https://github.com\n```\n\n### 清理策略\n\n| 场景 | 建议操作 |\n|------|----------|\n| 正常完成 | 使用 `close` 优雅关闭 |\n| 异常退出 | 使用 `kill-all` 强制终止 |\n| 磁盘空间不足 | 使用 `delete-data` 清理旧会话 |\n\n### 无头模式与有头模式\n\n```bash\n# 无头模式（默认）\nplaywright-cli open https://example.com\n\n# 有头模式（可见浏览器窗口）\nplaywright-cli open https://example.com --headed\n```\n\n## 架构总结\n\nPlaywright 的浏览器支持层采用适配器模式设计：\n\n```mermaid\ngraph LR\n A[用户代码] --> B[Playwright API]\n B --> C[BrowserType 工厂]\n C --> D[ChromiumBrowser]\n C --> E[FirefoxBrowser]\n C --> E --> F[Juggler 桥接]\n C --> G[WebKitBrowser]\n D --> H[CDP 连接]\n G --> I[WKP 连接]\n```\n\n这种设计使得：\n- 新增浏览器支持只需实现新的适配器\n- 上层 API 保持稳定\n- 协议差异被隔离在各自的实现模块中\n\n---\n\n\n\n## 测试框架\n\n### 相关页面\n\n相关主题：[断言系统](#assertions), [定位器和选择器](#locators-and-selectors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright/src/common/config.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/config.ts)\n- [packages/playwright/src/common/fixtures.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/fixtures.ts)\n- [packages/playwright/src/common/test.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/test.ts)\n- [packages/playwright/src/runner/testRunner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/testRunner.ts)\n- [packages/playwright/src/runner/dispatcher.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/dispatcher.ts)\n- [packages/playwright/src/worker/workerMain.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/worker/workerMain.ts)\n- [packages/playwright/src/common/poolBuilder.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/poolBuilder.ts)\n \n\n# 测试框架\n\nPlaywright 测试框架是微软开发的一个端到端测试框架，提供了用于编写、管理和执行浏览器自动化测试的完整工具链。该框架支持多浏览器（Chromium、Firefox、WebKit）、多语言（JavaScript/TypeScript、Python、Java、.NET）以及丰富的断言和定位器 API。\n\n## 架构概述\n\nPlaywright 测试框架采用分层架构设计，核心组件包括配置管理、Fixtures 系统、测试运行器和 Worker 进程池。\n\n```mermaid\ngraph TD\n A[Playwright Test CLI] --> B[Test Runner]\n B --> C[Configuration]\n B --> D[Dispatcher]\n D --> E[Worker Pool]\n E --> F[Worker Process 1]\n E --> G[Worker Process 2]\n E --> H[Worker Process N]\n F --> I[Browser Context]\n G --> J[Browser Context]\n I --> K[Test Fixture]\n J --> L[Test Fixture]\n```\n\n## 核心组件\n\n### 配置系统\n\n配置系统负责管理测试运行的全局参数，包括测试目录、测试超时、并发配置等。\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| testDir | 测试文件目录 | 当前工作目录 |\n| timeout | 单个测试超时时间 | 30000ms |\n| retries | 失败测试重试次数 | 0 |\n| workers | 并发 Worker 数量 | CPU 核心数 |\n| reporter | 测试报告格式 | list |\n\n配置通过 `playwright.config.ts` 文件定义，框架在启动时加载并验证配置的有效性。资料来源：[packages/playwright/src/common/config.ts]()\n\n### Fixtures 系统\n\nFixtures 是 Playwright 测试框架的核心特性之一，用于在测试运行时提供上下文和资源管理。Fixtures 可以是浏览器上下文、页面对象、认证状态或任何测试所需的数据。\n\n```typescript\n// Fixtures 定义示例结构\nexport interface TestFixtures {\n page: Page;\n context: BrowserContext;\n request: APIRequestContext;\n}\n```\n\nFixtures 支持以下特性：\n\n- **自动生命周期管理**：自动处理资源的创建和销毁\n- **依赖注入**：Fixtures 可以依赖其他 Fixtures\n- **参数化支持**：支持动态参数化配置\n- **作用域控制**：可设置 Function Scope（Function、Test、Worker、Project）\n\n资料来源：[packages/playwright/src/common/fixtures.ts]()\n\n### 测试定义\n\n测试通过 `test` 函数定义，支持分组、标注和元数据管理。\n\n```typescript\ntest.describe('测试分组', () => {\n test.beforeEach(async ({ page }) => {\n // 前置条件\n });\n \n test('示例测试', async ({ page }) => {\n await page.goto('https://example.com');\n // 测试步骤\n });\n \n test.afterEach(async ({ page }) => {\n // 清理工作\n });\n});\n```\n\n资料来源：[packages/playwright/src/common/test.ts]()\n\n## 运行机制\n\n### 测试运行器\n\n测试运行器（Test Runner）是框架的核心调度引擎，负责解析配置、加载测试文件并协调整个测试执行流程。\n\n```mermaid\ngraph LR\n A[Load Config] --> B[Discover Tests]\n B --> C[Build Worker Pool]\n C --> D[Dispatch Tests]\n D --> E[Execute in Worker]\n E --> F[Report Results]\n F --> G[Cleanup]\n```\n\n运行器的主要职责包括：\n\n1. 解析命令行参数和配置文件\n2. 发现并加载测试文件\n3. 构建 Worker 进程池\n4. 分发测试任务到 Worker\n5. 收集并汇总测试结果\n\n资料来源：[packages/playwright/src/runner/testRunner.ts]()\n\n### 分发器\n\n分发器（Dispatcher）负责将测试任务分配给可用的 Worker 进程，支持智能负载均衡和失败重试机制。\n\n| 特性 | 说明 |\n|------|------|\n| 动态分配 | 根据 Worker 负载动态分配测试 |\n| 失败重试 | 支持按测试或全局配置重试 |\n| 超时控制 | 监控测试执行时间 |\n| 进度追踪 | 实时汇报测试执行进度 |\n\n分发器采用基于队列的模型，新测试被发现后立即加入执行队列。每个 Worker 进程独立运行，可以并行执行多个测试。\n\n资料来源：[packages/playwright/src/runner/dispatcher.ts]()\n\n### Worker 进程\n\nWorker 进程是测试代码的实际执行环境，每个 Worker 拥有独立的浏览器实例和上下文池。\n\n```mermaid\ngraph TD\n A[Worker Main] --> B[Load Fixtures]\n B --> C[Create Browser Context]\n C --> D[Run Test]\n D --> E[Assert Results]\n E --> F{Cleanup}\n F --> G[Destroy Context]\n G --> H[Ready for Next Test]\n```\n\nWorker 的生命周期管理包括：\n\n- 初始化阶段：加载必要的 Fixtures 和依赖\n- 执行阶段：运行单个测试用例\n- 清理阶段：销毁浏览器上下文，释放资源\n\n资料来源：[packages/playwright/src/worker/workerMain.ts]()\n\n### 进程池构建器\n\n进程池构建器（Pool Builder）负责创建和管理 Worker 进程池，优化资源利用率。\n\n```mermaid\ngraph TD\n A[Pool Request] --> B{Check Pool}\n B -->|有可用 Worker| C[Reuse Worker]\n B -->|无可用 Worker| D[Create Worker]\n D --> E[Initialize]\n C --> F[Execute Test]\n E --> F\n F --> G[Return to Pool]\n```\n\n进程池支持以下配置策略：\n\n| 策略 | 说明 |\n|------|------|\n| 并发数量 | 最大同时运行的 Worker 数 |\n| 空闲超时 | 空闲 Worker 的存活时间 |\n| 启动延迟 | 预热 Worker 的延迟配置 |\n\n资料来源：[packages/playwright/src/common/poolBuilder.ts]()\n\n## 追踪与调试\n\n### 追踪查看器\n\nPlaywright 提供追踪查看器（Trace Viewer）用于回放和调试测试执行过程。追踪文件是包含快照、网络请求、控制台日志的 ZIP 包。\n\n```bash\n# 打开追踪文件\nnpx playwright trace open \n\n# 查看特定 action 的详细信息\nnpx playwright trace action \n\n# 获取 DOM 快照\nnpx playwright trace snapshot \n```\n\n追踪查看器支持以下功能：\n\n- 时间线视图：可视化测试执行的时间轴\n- 快照回放：查看每一步操作后的页面状态\n- 网络监控：分析请求和响应详情\n- 控制台日志：捕获 JavaScript 控制台输出\n- 错误追踪：定位测试失败的具体原因\n\n资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx]()\n\n### CLI 工具\n\nplaywright-cli 提供命令行界面用于调试和探索性测试。\n\n| 命令 | 功能 |\n|------|------|\n| `goto` | 导航到指定 URL |\n| `click` | 点击页面元素 |\n| `snapshot` | 获取页面快照 |\n| `screenshot` | 截取页面截图 |\n| `pdf` | 生成 PDF 文档 |\n| `console` | 查看控制台输出 |\n| `requests` | 查看网络请求 |\n| `eval` | 执行 JavaScript 代码 |\n\n```bash\n# 启动调试会话\nplaywright-cli open https://example.com\n\n# 获取带引用标记的快照\nplaywright-cli snapshot\n\n# 使用引用标记交互\nplaywright-cli click e15\n```\n\n## 报告生成\n\n### HTML 报告器\n\nPlaywright 生成详细的 HTML 测试报告，包含测试结果统计、失败原因分析、截图对比等信息。\n\n报告界面主要组件：\n\n| 组件 | 说明 |\n|------|------|\n| 测试摘要 | 通过/失败/跳过统计 |\n| 测试列表 | 按项目分组的测试项 |\n| 测试详情 | 单个测试的执行信息 |\n| 元数据视图 | 测试环境配置信息 |\n\n资料来源：[packages/html-reporter/src/testCaseView.tsx]()\n\n报告支持以下数据展示：\n\n- 测试执行时长（毫秒转换显示）\n- 测试标签和项目分组\n- 重试次数和历史记录\n- 注释和标注信息\n- 追踪链接（跳转到 Trace Viewer）\n\n## 浏览器支持\n\nPlaywright 支持三大主流浏览器引擎：\n\n| 浏览器 | 引擎 | 平台支持 |\n|--------|------|----------|\n| Chromium | Blink | Windows、macOS、Linux |\n| Firefox | Gecko | Windows、macOS、Linux |\n| WebKit | WebKit | Windows、macOS、Linux |\n\n每个浏览器通过独立的项目（Project）配置，支持不同的视口大小、用户代理、设备模拟等参数。\n\n## 相关资源\n\n- 官方文档：https://playwright.dev\n- 追踪查看器：https://trace.playwright.dev\n- 测试配置参考：Playwright 配置文件规范\n- Fixtures API：自定义 Fixtures 开发指南\n\n---\n\n\n\n## 定位器和选择器\n\n### 相关页面\n\n相关主题：[客户端实现](#client-implementation), [测试框架](#test-framework)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)\n- [packages/injected/src/selectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEngine.ts)\n- [packages/injected/src/roleSelectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleSelectorEngine.ts)\n- [packages/injected/src/selectorGenerator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorGenerator.ts)\n- [packages/injected/src/selectorEvaluator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEvaluator.ts)\n- [packages/isomorphic/locatorUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/locatorUtils.ts)\n \n\n# 定位器和选择器\n\n## 概述\n\nPlaywright 中的**定位器（Locator）**和**选择器（Selector）**是自动化浏览器交互的核心组件。定位器是 Playwright 推荐的元素定位方式，提供了比传统 `Page.locator()` API 更加健壮的元素查找机制。选择器则是用于匹配 DOM 元素的字符串表达式，支持多种定位策略。\n\n定位器与选择器的关系可以通过以下架构图说明：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Locator API]\n B --> C{查找策略}\n C --> D[CSS 选择器]\n C --> E[Role 选择器]\n C --> F[文本选择器]\n C --> G[测试ID选择器]\n C --> H[XPath 选择器]\n D --> I[selectorEngine.ts]\n E --> J[roleSelectorEngine.ts]\n F --> I\n G --> I\n H --> I\n I --> K[selectorEvaluator.ts]\n K --> L[DOM 元素]\n \n style A fill:#e1f5ff\n style L fill:#c8e6c9\n```\n\n## 核心概念\n\n### 定位器（Locator）\n\n定位器是 Playwright 用来定位页面元素的异步可重用对象。与传统的 `querySelector` 不同，定位器具有以下特点：\n\n| 特性 | 说明 |\n|------|------|\n| **自动重试** | 元素未找到时自动等待并重试 |\n| **可复用** | 定位器对象可以多次使用 |\n| **惰性执行** | 定位器在交互时才执行查询 |\n| **可组合** | 支持链式调用构建复杂定位器 |\n\n定位器 API 提供了丰富的交互方法，包括 `click()`、`fill()`、`hover()`、`getByRole()` 等。\n\n### 选择器（Selector）\n\n选择器是用于匹配 DOM 元素的字符串表达式。Playwright 支持多种选择器类型：\n\n| 类型 | 语法示例 | 说明 |\n|------|----------|------|\n| CSS | `#id`, `.class`, `div > span` | 标准 CSS 选择器 |\n| Role | `getByRole('button')` | ARIA 角色选择器 |\n| 文本 | `getByText('Submit')` | 按文本内容定位 |\n| 测试ID | `getByTestId('submit')` | data-testid 属性 |\n| XPath | `xpath=//button` | XPath 表达式 |\n| 混合 | `role=button[name='Login']` | 属性组合 |\n\n## 源码架构\n\n### 模块职责划分\n\n```mermaid\ngraph LR\n A[packages/playwright-core
客户端封装] --> B[packages/isomorphic
跨平台工具]\n B --> C[packages/injected
注入脚本]\n \n A1[locator.ts] --> B1[locatorUtils.ts]\n C1[selectorEngine.ts] --> C4[selectorEvaluator.ts]\n C2[roleSelectorEngine.ts] --> C4\n C3[selectorGenerator.ts] --> C4\n \n style A fill:#fff3e0\n style B fill:#e3f2fd\n style C fill:#f3e5f5\n```\n\n### 关键源文件\n\n| 文件路径 | 职责 |\n|----------|------|\n| `client/locator.ts` | 定义Locator类，提供元素交互API |\n| `injected/selectorEngine.ts` | 实现基础选择器引擎 |\n| `injected/roleSelectorEngine.ts` | 实现ARIA角色选择器引擎 |\n| `injected/selectorGenerator.ts` | 自动生成健壮的选择器 |\n| `injected/selectorEvaluator.ts` | 评估和验证选择器匹配 |\n| `isomorphic/locatorUtils.ts` | 提供跨平台的定位器工具函数 |\n\n## 选择器引擎\n\n### 选择器引擎架构\n\n选择器引擎是 Playwright 解析和执行选择器的核心组件，采用插件化架构支持多种选择器类型。\n\n```mermaid\ngraph TD\n A[选择器字符串] --> B[解析器]\n B --> C{选择器类型}\n C -->|CSS| D[CSS Engine]\n C -->|role| E[Role Engine]\n C -->|text| F[Text Engine]\n C -->|test-id| G[TestId Engine]\n C -->|xpath| H[XPath Engine]\n \n D --> I[querySelector]\n E --> J[roleSelectorEngine.ts]\n F --> K[文本匹配]\n G --> L[data-testid]\n H --> M[XPath 评估]\n \n I --> N[selectorEvaluator.ts]\n J --> N\n K --> N\n L --> N\n M --> N\n \n N --> O[匹配结果]\n```\n\n### 角色选择器引擎\n\n角色选择器（Role Selector）是 Playwright 推荐的元素定位方式，基于 ARIA 规范实现。\n\n```mermaid\ngraph LR\n A[getByRole
'button'] --> B[roleSelectorEngine.ts]\n B --> C[ARIA 属性检查]\n C --> D{匹配类型}\n D -->|implicit| E[通过角色推断]\n D -->|explicit| F[通过 aria-* 属性]\n E --> G[返回元素]\n F --> G\n \n style A fill:#e1f5ff\n style G fill:#c8e6c9\n```\n\n角色选择器支持的选项参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string \\| RegExp | 角色关联的 accessible name |\n| `level` | number | ARIA level（如 heading 角色） |\n| `checked` | boolean | checkbox/radio 的选中状态 |\n| `pressed` | boolean | button 的按下状态 |\n| `expanded` | boolean | 展开/折叠状态 |\n| `selected` | boolean | option 的选中状态 |\n\n## Locator API\n\n### 创建定位器\n\n定位器可以通过多种方式创建：\n\n```typescript\n// 通过 CSS 选择器\npage.locator('css=.submit-button');\n\n// 通过角色\npage.locator('role=button[name=\"Submit\"]');\n\n// 通过文本内容\npage.locator('text=Click here');\n\n// 通过测试ID\npage.locator('test-id=submit-btn');\n\n// 链式定位器\npage.locator('form').locator('button[type=\"submit\"]');\n```\n\n### 交互方法\n\n| 方法 | 说明 | 示例 |\n|------|------|------|\n| `click()` | 点击元素 | `locator.click()` |\n| `dblclick()` | 双击元素 | `locator.dblclick()` |\n| `fill()` | 填充输入框 | `locator.fill('text')` |\n| `hover()` | 鼠标悬停 | `locator.hover()` |\n| `type()` | 逐字符输入 | `locator.type('hello')` |\n| `press()` | 按下按键 | `locator.press('Enter')` |\n| `check()` | 勾选复选框 | `locator.check()` |\n| `selectOption()` | 选择下拉选项 | `locator.selectOption('value')` |\n| `waitFor()` | 等待元素可见 | `locator.waitFor()` |\n| `getAttribute()` | 获取属性值 | `locator.getAttribute('href')` |\n\n### 过滤与断言\n\n定位器支持通过 `filter()` 方法进一步过滤元素：\n\n```typescript\n// 过滤条件示例\npage.locator('li').filter({ hasText: 'Item 1' });\npage.locator('button').filter({ hasNotText: 'Disabled' });\npage.locator('tr').filter({ has: page.locator('td.name') });\n```\n\n## 选择器生成\n\n### 自动生成选择器\n\nPlaywright 提供自动生成健壮选择器的功能。`selectorGenerator.ts` 分析 DOM 元素并生成可靠的选择器字符串。\n\n```mermaid\ngraph TD\n A[DOM 元素] --> B[selectorGenerator.ts]\n B --> C[收集元素信息]\n C --> D{检查优先级}\n D -->|测试ID| E[优先使用 test-id]\n D -->|角色+名称| F[回退到 role+name]\n D -->|CSS| G[最后使用 CSS 路径]\n E --> H[返回选择器字符串]\n F --> H\n G --> H\n \n style A fill:#e1f5ff\n style H fill:#c8e6c9\n```\n\n选择器生成优先级：\n\n1. `data-testid` 属性\n2. ARIA role + accessible name 组合\n3. 其他 ARIA 属性组合\n4. 文本内容\n5. CSS 路径\n\n### 生成 API\n\n在浏览器控制台中可以使用 `playwright` 对象生成选择器：\n\n```javascript\n// 获取元素的选择器\nplaywright.selector(element);\n\n// 生成特定语言的定位器\nplaywright.generateLocator(element, 'playwright');\nplaywright.generateLocator(element, 'cypress');\nplaywright.generateLocator(element, 'puppeteer');\n```\n\n## 选择器评估\n\n### 评估器职责\n\n`selectorEvaluator.ts` 负责评估选择器表达式与 DOM 元素的匹配关系：\n\n| 功能 | 说明 |\n|------|------|\n| **匹配验证** | 验证元素是否匹配选择器 |\n| **唯一性检查** | 确保选择器匹配唯一元素 |\n| **可见性检查** | 考虑元素可见性状态 |\n| **优先级排序** | 对多个匹配结果排序 |\n\n### 评估流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant L as Locator\n participant E as selectorEvaluator\n participant D as DOM\n \n U->>L: locator.click()\n L->>E: evaluate(selector)\n E->>D: querySelectorAll()\n D-->>E: [elements]\n E->>E: filterByVisibility()\n E->>E: sortByPriority()\n E-->>L: [matchedElements]\n L->>L: waitForMatch()\n L->>D: performAction()\n```\n\n## 最佳实践\n\n### 选择器选择优先级\n\n| 优先级 | 方法 | 示例 | 适用场景 |\n|--------|------|------|----------|\n| 1 | `getByRole()` | `getByRole('button', {name:'Submit'})` | 推荐首选 |\n| 2 | `getByLabel()` | `getByLabel('Username')` | 表单输入 |\n| 3 | `getByText()` | `getByText('Submit')` | 可见文本 |\n| 4 | `getByTestId()` | `getByTestId('submit-btn')` | 测试专用 |\n| 5 | CSS/XPath | `locator('.class')` | 复杂定位 |\n\n### 健壮性原则\n\n1. **避免脆弱选择器** - 不要依赖随机生成的类名\n2. **使用语义角色** - 优先使用 `getByRole()` 而非 CSS 类\n3. **添加 name 约束** - 角色选择器配合 accessible name 更可靠\n4. **避免绝对路径** - XPath 不使用 `html/body/div[1]/div[2]`\n5. **保持测试ID稳定** - 避免频繁更改 `data-testid`\n\n### 性能优化\n\n| 问题 | 解决方案 |\n|------|----------|\n| 元素查找慢 | 使用更具体的选择器 |\n| 频繁重试 | 减少选择器复杂度 |\n| 跨框架定位 | 使用 `frameLocator()` |\n\n## 控制台 API\n\nPlaywright 注入脚本在浏览器控制台暴露了调试工具：\n\n```javascript\n// 查找单个元素\nplaywright.$('button.submit');\n\n// 查找所有匹配元素\nplaywright.$$('li.item');\n\n// 检查元素信息\nplaywright.inspect('button');\n\n// 获取元素选择器\nplaywright.selector(element);\n\n// 生成定位器代码\nplaywright.generateLocator(element, 'playwright');\n\n// 获取 ARIA 快照\nplaywright.ariaSnapshot();\n```\n\n这些 API 用于 `playwright-cli` 工具的调试和诊断功能。\n\n## 总结\n\nPlaywright 的定位器和选择器系统提供了强大而灵活的页面元素定位能力：\n\n- **Locator API** 是高级封装，提供自动重试和惰性执行\n- **选择器引擎** 支持多种定位策略，采用插件化架构\n- **角色选择器** 基于 ARIA 规范，是推荐的定位方式\n- **选择器生成器** 自动创建健壮的选择器表达式\n- **评估器** 确保选择器正确匹配目标元素\n\n合理使用这些组件可以编写出稳定、可维护的浏览器自动化测试脚本。\n\n---\n\n**相关资料：**\n\n- Locator 客户端实现：`packages/playwright-core/src/client/locator.ts`\n- 选择器引擎核心：`packages/injected/src/selectorEngine.ts`\n- 角色选择器：`packages/injected/src/roleSelectorEngine.ts`\n- 选择器生成器：`packages/injected/src/selectorGenerator.ts`\n- 选择器评估器：`packages/injected/src/selectorEvaluator.ts`\n- 跨平台工具：`packages/isomorphic/locatorUtils.ts`\n\n---\n\n\n\n## 断言系统\n\n### 相关页面\n\n相关主题：[测试框架](#test-framework), [定位器和选择器](#locators-and-selectors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright/src/matchers/expect.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/expect.ts)\n- [packages/playwright/src/matchers/matchers.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/matchers.ts)\n- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)\n- [packages/isomorphic/assert.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/assert.ts)\n- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)\n- [README.md](https://github.com/microsoft/playwright/blob/main/README.md)\n \n\n# 断言系统\n\n## 概述\n\nPlaywright 断言系统是端到端测试框架的核心组件，提供了一套完整的 Web 页面状态验证机制。该系统基于\"Web-First 断言\"理念设计，具有自动等待、可重试、软断言等关键特性，旨在消除人工设置超时和避免 flaky 测试。\n\n断言系统的核心设计目标包括：\n\n- **自动等待**：在断言执行前自动等待目标元素达到预期状态\n- **可重试机制**：断言会自动重试直到条件满足或超时\n- **软断言支持**：允许收集多个失败而非立即中断测试\n- **丰富的匹配器**：覆盖 Web 交互中的各类验证场景\n\n资料来源：[README.md:1-100]()\n\n## 核心架构\n\nPlaywright 断言系统采用分层架构设计，主要包含以下层次：\n\n```mermaid\ngraph TD\n A[用户测试代码] --> B[expect API]\n B --> C[软断言控制器]\n C --> D[匹配器集合]\n D --> E[等待策略]\n E --> F[Locator/Page 对象]\n F --> G[底层 CDP 通信]\n \n H[自定义匹配器] --> D\n I[toBe/toHave/toContain...] --> D\n```\n\n### 核心组件表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| expect | `packages/playwright/src/matchers/expect.ts` | 入口函数，创建断言上下文 |\n| 匹配器 | `packages/playwright/src/matchers/matchers.ts` | 实现具体断言逻辑 |\n| Locator | `packages/playwright-core/src/client/locator.ts` | 元素定位与断言绑定 |\n| 断言工具 | `packages/isomorphic/assert.ts` | 底层断言辅助函数 |\n\n资料来源：[packages/playwright/src/matchers/expect.ts:1-50]()\n\n## expect API\n\n### 基本用法\n\n`expect` 是 Playwright 断言系统的入口函数，支持多种使用方式：\n\n```typescript\nimport { test, expect } from '@playwright/test';\n\n// 页面级断言\nawait expect(page).toHaveTitle('Playwright');\n\n// 定位器断言\nawait expect(page.getByRole('button')).toBeVisible();\n\n// 期望值断言\nexpect(value).toBe(42);\n```\n\n### expect 函数实现\n\n`expect` 函数接受一个实际值作为参数，返回一个包含所有断言方法的 Expect 对象：\n\n```typescript\n// packages/playwright/src/matchers/expect.ts 核心签名\nfunction expect(value: any): Expect\n```\n\n Expect 对象提供的方法分为两类：\n1. **布尔匹配器**：直接返回布尔结果的断言\n2. **可等待匹配器**：返回 Promise 并自动等待的断言\n\n资料来源：[packages/playwright/src/matchers/expect.ts:50-150]()\n\n### 软断言\n\n软断言允许在测试执行过程中收集多个失败断言，而不是在第一个失败时立即停止：\n\n```typescript\ntest('soft assertions example', async ({ page }) => {\n await expect.soft(page).toHaveTitle('Expected Title');\n await expect.soft(page.getByRole('button')).toBeVisible();\n // 即使前一个失败，后续断言仍会执行\n});\n```\n\n软断言的失败会在测试结束时统一报告，测试状态标记为失败。\n\n资料来源：[packages/playwright/src/matchers/expect.ts:150-200]()\n\n## 内置匹配器\n\n### 页面级匹配器\n\n页面级匹配器直接作用于 `Page` 对象，验证页面整体状态：\n\n| 匹配器 | 描述 | 示例 |\n|--------|------|------|\n| `toHaveTitle(title)` | 验证页面标题 | `await expect(page).toHaveTitle(/Playwright/)` |\n| `toHaveURL(url)` | 验证当前 URL | `await expect(page).toHaveURL('**/docs**')` |\n| `toHaveScreenshot(name)` | 验证页面截图 | `await expect(page).toHaveScreenshot('home.png')` |\n\n资料来源：[packages/playwright/src/matchers/matchers.ts:1-100]()\n\n### 元素级匹配器\n\n元素级匹配器通过 Locator 链式调用，用于验证单个或多个元素的状态：\n\n```typescript\n// 可见性断言\nawait expect(page.locator('#submit')).toBeVisible();\nawait expect(page.locator('.loading')).toBeHidden();\n\n// 内容断言\nawait expect(page.getByRole('button')).toHaveText('Submit');\nawait expect(page.locator('.error')).toContainText('Invalid');\n\n// 属性断言\nawait expect(page.getByRole('input')).toHaveAttribute('required');\nawait expect(page.locator('img')).toHaveAttribute('src', /logo/);\n\n// 表单值断言\nawait expect(page.getByRole('textbox')).toHaveValue('default text');\n```\n\n资料来源：[packages/playwright/src/matchers/matchers.ts:100-300]()\n\n### 可访问性匹配器\n\nPlaywright 提供 ARIA 角色相关的匹配器，用于验证元素的可访问性语义：\n\n```typescript\n// 验证元素角色\nawait expect(page.locator('dialog')).toHaveRole('dialog');\nawait expect(page.locator('nav')).toHaveRole('navigation');\n```\n\n角色映射定义在 `roleUtils.ts` 中，涵盖了 HTML 语义化元素到 ARIA 角色的转换规则。\n\n资料来源：[packages/injected/src/roleUtils.ts:1-50]()\n\n### 计数与状态匹配器\n\n| 匹配器 | 描述 |\n|--------|------|\n| `toHaveCount(count)` | 验证元素数量 |\n| `toBeChecked()` | 验证复选框/单选框状态 |\n| `toBeEnabled()` | 验证元素可用状态 |\n| `toBeDisabled()` | 验证元素禁用状态 |\n| `toBeFocused()` | 验证焦点状态 |\n\n```typescript\nawait expect(page.getByRole('checkbox', { name: 'Remember me' })).toBeChecked();\nawait expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();\n```\n\n资料来源：[packages/playwright/src/matchers/matchers.ts:300-400]()\n\n## Locator 集成\n\n### Locator 断言方法\n\nLocator 对象直接集成了断言方法，允许链式调用：\n\n```typescript\n// Locator 类中的断言方法\n// packages/playwright-core/src/client/locator.ts\n\nclass Locator {\n // 可见性断言\n async toBeVisible(options?: VisibilityOption): Promise\n \n // 内容断言 \n async toHaveText(expected: string | RegExp | (string | RegExp)[]): Promise\n \n // 属性断言\n async toHaveAttribute(name: string, value?: string | RegExp): Promise\n \n // 值断言\n async toHaveValue(value: string | RegExp): Promise\n}\n```\n\nLocator 断言的显著特点是**自动等待**：如果目标元素尚未满足条件，Playwright 会自动等待直到超时。\n\n资料来源：[packages/playwright-core/src/client/locator.ts:200-350]()\n\n### 等待策略\n\nPlaywright 断言内置智能等待策略：\n\n```mermaid\ngraph LR\n A[执行断言] --> B{元素存在?}\n B -->|否| C[等待 DOM 出现]\n C --> D{条件满足?}\n D -->|否| E[重试]\n E --> D\n D -->|是| F[断言通过]\n B -->|是| G{条件满足?}\n G -->|否| H[等待条件变化]\n H --> G\n G -->|是| F\n```\n\n默认超时时间为 30 秒，可通过配置或方法参数覆盖：\n\n```typescript\n// 使用配置超时\nawait expect(page.locator('.loading')).toBeHidden({ timeout: 5000 });\n\n// 使用全局配置\ntest.setTimeout(10000);\n```\n\n## 底层断言工具\n\n### 断言辅助函数\n\n`packages/isomorphic/assert.ts` 提供了底层断言实现：\n\n```typescript\n// 核心断言函数签名\nexport function expect(value: any, options?: ExpectOptions): ExpectResult\n\n// 软断言标记\nexport type ExpectOptions = {\n isSoft?: boolean\n}\n\n// 断言结果\nexport type ExpectResult = {\n pass: boolean\n message?: string\n}\n```\n\n这些底层函数处理：\n- 布尔值比较\n- 正则表达式匹配\n- 对象深度比较\n- 数组包含检查\n\n资料来源：[packages/isomorphic/assert.ts:1-100]()\n\n## 配置与选项\n\n### 断言超时配置\n\n| 配置方式 | 优先级 | 示例 |\n|----------|--------|------|\n| 方法参数 | 最高 | `toBeVisible({ timeout: 1000 })` |\n| 测试超时 | 中 | `test.setTimeout(10000)` |\n| 全局配置 | 最低 | `playwright.config.ts` 中设置 |\n\n### expect 配置\n\n```typescript\n// 自定义 expect 配置\ntest.use({\n expect: {\n timeout: 5000,\n soft: false\n }\n});\n```\n\n## 最佳实践\n\n### 1. 使用语义化定位器\n\n```typescript\n// 推荐：使用角色定位器\nawait expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();\n\n// 避免：过度依赖 CSS 选择器\nawait expect(page.locator('.btn-primary')).toBeVisible();\n```\n\n### 2. 利用自动等待\n\n```typescript\n// 正确：依赖自动等待\nawait expect(page.getByRole('status')).toHaveText('Saved');\n\n// 错误：手动等待（容易导致 flaky）\nawait page.waitForTimeout(1000);\nawait expect(page.getByRole('status')).toHaveText('Saved');\n```\n\n### 3. 软断言收集错误\n\n```typescript\ntest('form validation', async ({ page }) => {\n await expect.soft(page.getByLabel('Email')).toHaveValue(/@/);\n await expect.soft(page.getByLabel('Phone')).toHaveValue(/^\\d+$/);\n // 两个验证都会执行，错误会一起报告\n});\n```\n\n### 4. 正则表达式匹配\n\n```typescript\n// 动态内容匹配\nawait expect(page.locator('.status')).toContainText(/saved|updated/i);\n\n// URL 模式匹配\nawait expect(page).toHaveURL(/\\?page=\\d+/);\n```\n\n## 错误处理与调试\n\n### 断言错误信息\n\nPlaywright 断言失败时会提供详细的诊断信息：\n\n```\nexpect(received).toHaveText(expected)\n\nExpected string: \"Submit\"\nReceived string: \"Cancel\"\n```\n\n### 调试模式\n\n使用 Playwright CLI 进行断言调试：\n\n```bash\n# 运行测试并进入调试模式\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n\n# 附加到测试会话\nplaywright-cli attach \n```\n\n## 总结\n\nPlaywright 断言系统通过以下设计实现了可靠的 Web 测试：\n\n| 特性 | 优势 |\n|------|------|\n| Web-First 断言 | 自动等待元素就绪，消除人工超时 |\n| 语义化匹配器 | 符合 ARIA 规范，支持可访问性测试 |\n| 软断言支持 | 收集多个失败，提供完整错误报告 |\n| Locator 集成 | 链式调用，代码可读性高 |\n| 可配置超时 | 灵活适应不同测试场景 |\n\n该系统是 Playwright 测试框架的核心支柱，为开发者提供了简洁、可靠、语义化的断言 API。\n\n---\n\n\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[快速入门](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/cli/program.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/program.ts)\n- [packages/playwright-core/src/cli/browserActions.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/browserActions.ts)\n- [packages/playwright-core/src/cli/installActions.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/installActions.ts)\n- [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)\n- [packages/playwright-core/src/tools/backend/tools.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/backend/tools.ts)\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n- [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)\n \n\n# 命令行工具\n\nPlaywright 提供了一套完整的命令行工具体系，用于浏览器自动化、测试执行、轨迹分析和 CLI 客户端交互。本页详细介绍 Playwright 命令行工具的整体架构、各子命令的功能以及典型使用场景。\n\n## 1. 架构概述\n\nPlaywright 命令行工具由多个层次的组件构成，形成了一个分层式的命令行体系。最上层是用户直接调用的 `playwright` 主命令，中间层是针对不同功能域的子命令模块（如浏览器管理、测试运行、轨迹查看等），底层则是负责具体操作执行的工具后端。\n\n```mermaid\ngraph TD\n A[\"用户终端\"] --> B[\"playwright 主程序
program.ts\"]\n B --> C[\"browserActions
浏览器管理\"]\n B --> D[\"installActions
安装管理\"]\n B --> E[\"playwright-cli
CLI客户端\"]\n B --> F[\"playwright test
测试运行\"]\n B --> G[\"playwright trace
轨迹分析\"]\n E --> H[\"tools.ts
工具后端\"]\n H --> I[\"浏览器会话管理\"]\n H --> J[\"快照与截图\"]\n H --> K[\"网络拦截\"]\n H --> L[\"存储管理\"]\n```\n\n主程序入口位于 `program.ts`，负责解析命令行参数并将请求分发到对应的子模块。资料来源：[packages/playwright-core/src/cli/program.ts]()\n\n## 2. 主命令模块\n\n### 2.1 浏览器动作命令\n\n`browserActions.ts` 模块封装了所有与浏览器交互相关的底层操作，包括启动浏览器实例、创建页面、执行导航等核心功能。这些动作构成了所有高级自动化操作的基础。\n\n| 命令类别 | 功能描述 |\n|---------|---------|\n| `open` | 启动新的浏览器会话并导航到指定 URL |\n| `goto` | 在当前会话中导航到目标页面 |\n| `close` | 关闭当前浏览器会话 |\n| `kill-all` | 强制终止所有浏览器进程 |\n\n资料来源：[packages/playwright-core/src/cli/browserActions.ts]()\n\n### 2.2 安装命令\n\n`installActions.ts` 模块负责管理 Playwright 的运行时依赖。最重要的功能是下载和安装浏览器可执行文件。该模块确保所有支持的浏览器（Chromium、Firefox、WebKit）都被正确安装并可用。\n\n```bash\n# 安装所有浏览器\nnpx playwright install\n\n# 安装指定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n\n# 安装带驱动依赖\nnpx playwright install --with-deps\n```\n\n资料来源：[packages/playwright-core/src/cli/installActions.ts]()\n\n## 3. playwright-cli 客户端\n\n`playwright-cli` 是 Playwright 提供的交互式命令行客户端，提供了比主命令更丰富的浏览器自动化能力。它支持实时快照查看、元素交互、网络拦截、存储管理等高级功能。\n\n### 3.1 核心命令\n\n```mermaid\ngraph LR\n A[\"playwright-cli\"] --> B[\"页面操作\"]\n A --> C[\"元素定位\"]\n A --> D[\"网络控制\"]\n A --> E[\"状态管理\"]\n A --> F[\"调试工具\"]\n \n B --> B1[\"goto / click / fill / type\"]\n C --> C1[\"snapshot / click ref\"]\n D --> D1[\"route / unroute\"]\n E --> E1[\"cookie / localstorage\"]\n F --> F1[\"console / tracing\"]\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()\n\n#### 页面操作命令\n\n| 命令 | 功能 | 示例 |\n|-----|------|------|\n| `open` | 打开浏览器并访问 URL | `playwright-cli open https://example.com` |\n| `goto` | 导航到指定页面 | `playwright-cli goto https://example.com` |\n| `click` | 点击元素 | `playwright-cli click e15` |\n| `fill` | 填充输入框 | `playwright-cli fill e5 \"text\"` |\n| `type` | 模拟键盘输入 | `playwright-cli type \"search query\"` |\n| `press` | 按下按键 | `playwright-cli press Enter` |\n| `snapshot` | 获取页面快照 | `playwright-cli snapshot` |\n| `screenshot` | 截图保存 | `playwright-cli screenshot --filename=page.png` |\n| `pdf` | 生成 PDF | `playwright-cli pdf --filename=page.pdf` |\n\n#### 元素定位系统\n\nplaywright-cli 采用基于快照的引用系统来定位页面元素。每个可交互元素在快照中都有一个唯一的引用标识符（如 `e15`），用户可以通过这些引用来执行操作。\n\n```bash\n# 获取带引用的快照\nplaywright-cli snapshot\n\n# 使用引用点击元素\nplaywright-cli click e15\n\n# 也支持 CSS 选择器和 Playwright 定位器\nplaywright-cli click \"#main > button.submit\"\nplaywright-cli click \"getByRole('button', { name: 'Submit' })\"\n```\n\n### 3.2 浏览器会话管理\n\nplaywright-cli 支持多个并发浏览器会话，每个会话可以通过名称标识。这对于同时测试多个场景或进行 A/B 测试非常有用。\n\n```bash\n# 创建命名会话\nplaywright-cli -s=mysession open https://example.com\n\n# 列出所有会话\nplaywright-cli list\n\n# 关闭指定会话\nplaywright-cli -s=mysession close\n\n# 关闭所有会话\nplaywright-cli close-all\n\n# 强制终止所有浏览器进程\nplaywright-cli kill-all\n```\n\n持久化配置文件支持自定义会话设置：\n\n```bash\n# 使用配置文件打开\nplaywright-cli open https://example.com --config=.playwright/my-cli.json\n\n# 指定浏览器类型\nplaywright-cli open https://example.com --browser=firefox\n\n# 以有头模式打开\nplaywright-cli open https://example.com --headed\n\n# 使用持久化配置文件\nplaywright-cli open https://example.com --persistent\nplaywright-cli open https://example.com --profile=/path/to/profile\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md]()\n\n### 3.3 存储管理\n\nplaywright-cli 提供了完整的客户端存储管理能力，支持 Cookie、LocalStorage、SessionStorage 的增删改查操作。\n\n```bash\n# 状态持久化\nplaywright-cli state-save auth.json\nplaywright-cli state-load auth.json\n\n# Cookie 管理\nplaywright-cli cookie-list\nplaywright-cli cookie-list --domain=example.com\nplaywright-cli cookie-get session_id\nplaywright-cli cookie-set session_id abc123\nplaywright-cli cookie-delete session_id\nplaywright-cli cookie-clear\n\n# LocalStorage 管理\nplaywright-cli localstorage-list\nplaywright-cli localstorage-get theme\nplaywright-cli localstorage-set theme dark\nplaywright-cli localstorage-delete theme\nplaywright-cli localstorage-clear\n```\n\n### 3.4 网络控制\n\n```bash\n# 拦截请求并返回自定义状态\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 修改响应体\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\nplaywright-cli unroute\n```\n\n### 3.5 标签页管理\n\n```bash\n# 标签页操作\nplaywright-cli tab-list\nplaywright-cli tab-new\nplaywright-cli tab-new https://example.com/page\nplaywright-cli tab-close\nplaywright-cli tab-close 2\nplaywright-cli tab-select 0\n```\n\n## 4. 轨迹工具\n\n`playwright trace` 命令用于分析和调试 `.zip` 格式的轨迹文件，这些文件由 Playwright 测试运行时生成，包含完整的执行过程记录。\n\n### 4.1 轨迹工作流程\n\n```mermaid\ngraph TD\n A[\"trace open\"] --> B[\"trace actions\"]\n B --> C{\"发现问题?\"}\n C -->|是| D[\"trace actions --errors-only\"]\n C -->|否| E[\"继续分析\"]\n D --> F[\"trace action \"]\n F --> G[\"trace snapshot\"]\n G --> H[\"trace requests
trace console\"]\n```\n\n### 4.2 轨迹命令\n\n| 命令 | 功能 |\n|-----|------|\n| `trace open ` | 打开并提取轨迹文件，显示元数据 |\n| `trace close` | 关闭当前轨迹，清理临时文件 |\n| `trace actions` | 列出所有动作，支持 `--grep` 过滤 |\n| `trace actions --errors-only` | 仅显示失败的动作 |\n| `trace action ` | 查看特定动作的详细信息 |\n| `trace snapshot ` | 获取动作执行时的 DOM 快照 |\n| `trace requests` | 查看网络请求列表 |\n| `trace requests --failed` | 仅显示失败的请求 |\n| `trace console` | 查看控制台日志 |\n| `trace console --errors-only` | 仅显示错误日志 |\n| `trace attachments` | 列出所有附件 |\n| `trace attachment ` | 提取指定附件 |\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n## 5. 调试工具\n\nplaywright-cli 集成了多种调试辅助工具，帮助开发者诊断问题。\n\n### 5.1 控制台与网络监控\n\n```bash\n# 查看控制台输出\nplaywright-cli console\nplaywright-cli console warning\n\n# 查看网络请求\nplaywright-cli requests\n\n# 查看特定请求详情\nplaywright-cli request 5\n```\n\n### 5.2 追踪录制\n\n```bash\n# 开始录制追踪\nplaywright-cli tracing-start\n\n# 停止录制并保存\nplaywright-cli tracing-stop\n```\n\n追踪文件包含以下内容：\n\n| 文件/目录 | 内容描述 |\n|----------|---------|\n| `trace-{timestamp}.trace` | 动作日志，包含每个操作的快照和截图 |\n| `trace-{timestamp}.network` | 完整的网络活动记录 |\n| `resources/` | 缓存的资源文件 |\n\n### 5.3 可视化调试\n\n```bash\n# 启动带标注功能的截图工具\nplaywright-cli show --annotate\n\n# 高亮显示元素\nplaywright-cli highlight e5\nplaywright-cli highlight e5 --style=\"outline: 3px dashed red\"\nplaywright-cli highlight --hide\n```\n\n## 6. 代码执行\n\n`run-code` 命令允许在页面上下文中直接执行 JavaScript 代码，这对于动态探测和调试非常有用。\n\n```bash\n# 获取页面信息\nplaywright-cli run-code \"async page => {\n return await page.title();\n}\"\n\n# 读写剪贴板\nplaywright-cli run-code \"async page => {\n await page.context().grantPermissions(['clipboard-read']);\n return await page.evaluate(() => navigator.clipboard.readText());\n}\"\n\n# 执行复杂逻辑\nplaywright-cli run-code \"async page => {\n const multiplier = 5;\n return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);\n}\"\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/running-code.md]()\n\n## 7. 测试集成\n\nPlaywright CLI 与 Playwright Test 框架紧密集成，提供了便捷的测试调试能力。\n\n```bash\n# 运行所有测试\nPLAYWRIGHT_HTML_OPEN=never npx playwright test\n\n# 调试模式运行测试\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n```\n\n调试模式会暂停测试执行并提供会话名称，允许通过 playwright-cli 附加到测试会话进行实时调试：\n\n```bash\n# 等待调试指令输出 tw-XXXX 会话名\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n\n# 附加到测试会话\nplaywright-cli attach tw-XXXX\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md]()\n\n## 8. 工具后端架构\n\n`tools.ts` 模块定义了 CLI 工具的后端实现，封装了所有底层浏览器操作能力。这些工具通过 MCP（Model Context Protocol）协议对外提供服务，使得 AI 代理能够通过标准化接口调用 Playwright 功能。\n\n核心工具类别包括：\n\n- **页面操作工具**：导航、点击、输入、提交等\n- **元素查询工具**：快照生成、引用解析、选择器生成\n- **状态管理工具**：Cookie、存储、网络路由\n- **调试工具**：控制台捕获、追踪录制、截图\n\n资料来源：[packages/playwright-core/src/tools/backend/tools.ts]()\n\n## 9. 使用建议\n\n### 9.1 工具选择指南\n\n| 场景 | 推荐工具 |\n|------|---------|\n| 快速浏览网页 | `playwright-cli open` |\n| 调试测试失败 | `playwright test --debug=cli` + `playwright-cli attach` |\n| 分析测试轨迹 | `playwright trace` |\n| 复杂自动化脚本 | `playwright-cli run-code` |\n| 并发多浏览器测试 | `playwright-cli -s=` |\n\n### 9.2 最佳实践\n\n1. **会话命名**：使用有意义的会话名称，便于管理和清理\n2. **资源清理**：完成操作后及时关闭会话或使用 `close-all`\n3. **持久化配置**：复杂场景使用配置文件管理会话设置\n4. **追踪录制**：遇到问题时录制追踪便于事后分析\n5. **快照优先**：使用 `snapshot` 命令而非频繁截图，提高效率\n\n### 9.3 安装与更新\n\n```bash\n# 检查版本\nnpx --no-install playwright-cli --version\n\n# 或使用全局命令\nplaywright-cli --version\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：microsoft/playwright\n\n摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized。\n\n## 1. 安装坑 · 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f8ee5532aee4b6cbf512f4227b0bac6 | https://github.com/microsoft/playwright/issues/40856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ae154da8c374e95842c5b9fed587329 | https://github.com/microsoft/playwright/issues/40857 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d99eb725d0044cc8a856ff77a5034353 | https://github.com/microsoft/playwright/issues/40868 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[Bug]: test body doesn't accept function with a return type other than void\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: test body doesn't accept function with a return type other than void\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_068a984a4ea348dd8b8de11244fbddd2 | https://github.com/microsoft/playwright/issues/40851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[Feature] Allow custom command-line arguments in @playwright/test\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Allow custom command-line arguments in @playwright/test\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_27f460cbef7e4489b323fb9fb7cfc515 | https://github.com/microsoft/playwright/issues/10337 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.56.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.56.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cc7813a33a854a3c8465dd3548ef7684 | https://github.com/microsoft/playwright/releases/tag/v1.56.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.57.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.57.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d76f3b46992422c8b4a18583cabd192 | https://github.com/microsoft/playwright/releases/tag/v1.57.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v1.59.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.59.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4296f1e3e0d4e37bbecccf2fe087c00 | https://github.com/microsoft/playwright/releases/tag/v1.59.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 能力坑 · 来源证据：v1.60.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v1.60.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2bf82c9b52a6418986114131cd1bd2d3 | https://github.com/microsoft/playwright/releases/tag/v1.60.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:221981891 | https://github.com/microsoft/playwright | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：v1.59.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.59.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fa3aef4aac6e4812b8d1e973fb2e88c5 | https://github.com/microsoft/playwright/releases/tag/v1.59.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · 来源证据：v1.55.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.55.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66dddad3517842b38fff2a76a1c00ce0 | https://github.com/microsoft/playwright/releases/tag/v1.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 来源证据：v1.58.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.58.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53b55fd4a28c4da791a8160ca677d10d | https://github.com/microsoft/playwright/releases/tag/v1.58.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：v1.56.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.56.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e050e46d53424e568cf3a0286a0f2739 | https://github.com/microsoft/playwright/releases/tag/v1.56.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v1.58.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91fccb17c1534cbfbc86fc6d7d0f7e30 | https://github.com/microsoft/playwright/releases/tag/v1.58.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.58.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b5831f013464a809b33b71e270d6a82 | https://github.com/microsoft/playwright/releases/tag/v1.58.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | release_recency=unknown\n\n\n",
"markdown_key": "playwright",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:221981891",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/microsoft/playwright"
},
{
"evidence_id": "art_b2213d06a04743089bd0d2db345084dd",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/microsoft/playwright#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "playwright 说明书",
"toc": [
"https://github.com/microsoft/playwright 项目说明书",
"目录",
"项目概述",
"什么是 Playwright",
"核心架构",
"CLI 工具集",
"导航和页面控制",
"读取剪贴板",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "bb7af07608e50f6b1e3cd534af30294a94ba8336",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/src/emulation.md",
"docs/src/other-locators.md",
"docs/src/codegen.md",
"docs/src/library-csharp.md",
"docs/src/test-retries-js.md",
"docs/src/test-runners-python.md",
"docs/src/test-cli-js.md",
"docs/src/test-webserver-js.md",
"docs/src/intro-python.md",
"docs/src/test-reporters-js.md",
"docs/src/api-testing-js.md",
"docs/src/writing-tests-js.md",
"docs/src/locators.md",
"docs/src/running-tests-java.md",
"docs/src/protractor-js.md",
"docs/src/dialogs.md",
"docs/src/running-tests-csharp.md",
"docs/src/frames.md",
"docs/src/junit-java.md",
"docs/src/api-testing-python.md",
"docs/src/getting-started-mcp.md",
"docs/src/accessibility-testing-java.md",
"docs/src/events.md",
"docs/src/trace-viewer.md",
"docs/src/screenshots.md",
"docs/src/test-parameterize-js.md",
"docs/src/service-workers-js-python.md",
"docs/src/threading-java.md",
"docs/src/api-testing-java.md",
"docs/src/test-projects-js.md",
"docs/src/test-timeouts-js.md",
"docs/src/running-tests-js.md",
"docs/src/trace-viewer-intro-csharp.md",
"docs/src/release-notes-js.md",
"docs/src/browser-contexts.md",
"docs/src/intro-js.md",
"docs/src/mock.md",
"docs/src/library-js.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# playwright-internal - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 playwright-internal 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md`, `packages/playwright-core/src/tools/trace/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md`, `packages/playwright-core/src/tools/trace/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm i -D @playwright/test` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx playwright install` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx playwright test` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx playwright show-trace trace.zip` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npm install -g @playwright/cli@latest` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `claude mcp add playwright npx @playwright/mcp@latest` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npm i playwright` 证据：`README.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md`, `packages/playwright-core/src/tools/trace/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md`, `packages/playwright-core/src/tools/trace/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `CLAUDE.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `CLAUDE.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0013` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/skills/playwright-dev/SKILL.md`, `.claude/skills/playwright-devops/SKILL.md`, `packages/playwright-core/src/tools/cli-client/skill/SKILL.md`, `packages/playwright-core/src/tools/trace/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2742\n- 重要文件覆盖：40/2742\n- 证据索引条目：80\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 playwright-internal 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 playwright-internal 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 playwright-internal 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **playwright-dev**（skill）：Explains how to develop Playwright - add APIs, MCP tools, CLI commands, and vendor dependencies. 激活提示：当用户任务与“playwright-dev”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/playwright-dev/SKILL.md`\n- **playwright-devops**（skill）：DevOps workflows for Playwright - CI failure analysis, workflow debugging, and release operations. 激活提示：当用户任务与“playwright-devops”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/playwright-devops/SKILL.md`\n- **playwright-cli**（skill）：Automate browser interactions, test web pages and work with Playwright tests. 激活提示：当用户任务与“playwright-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/playwright-core/src/tools/cli-client/skill/SKILL.md`\n- **playwright-trace**（skill）：Inspect Playwright trace files from the command line — list actions, view requests, console, errors, snapshots and screenshots. 激活提示：当用户任务与“playwright-trace”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/playwright-core/src/tools/trace/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Monorepo Packages**（documentation）：Package npm name Purpose --------- ---------- --------- playwright-core playwright-core Browser automation engine: client, server, dispatchers, protocol playwright playwright Test runner + browser automation public package playwright-test @playwright/test Test runner entry point playwright-client @playwright/client Standalone client package protocol internal RPC protocol definitions protocol.yml → generated channels.d.ts 证据：`CLAUDE.md`\n- **🎭 Playwright**（documentation）：! npm version https://img.shields.io/npm/v/playwright.svg https://www.npmjs.com/package/playwright ! Chromium version https://img.shields.io/badge/chromium-149.0.7827.3-blue.svg?logo=google-chrome https://www.chromium.org/Home ! Firefox version https://img.shields.io/badge/firefox-150.0.2-blue.svg?logo=firefoxbrowser https://www.mozilla.org/en-US/firefox/new/ ! WebKit version https://img.shields.io/badge/webkit-26.4-blue.svg?logo=safari https://webkit.org/ ! Join Discord https://img.shields.io/badge/join-discord-informational https://aka.ms/playwright/discord 证据：`README.md`\n- **Tool for printing .exe and .dll dependencies on Windows**（documentation）：Tool for printing .exe and .dll dependencies on Windows 证据：`browser_patches/winldd/README.md`\n- **Battery Status API**（documentation）：Demo http://pazguille.github.io/demo-battery-api/ 证据：`examples/mock-battery/demo-battery-api/README.md`\n- **Playwright Chrome Extension**（documentation）：The Playwright Chrome Extension allows you to connect to pages in your existing browser and leverage the state of your default user profile. This means the AI assistant can interact with websites where you're already logged in, using your existing cookies, sessions, and browser state, providing a seamless experience without requiring separate authentication or setup. 证据：`packages/extension/README.md`\n- **Injected**（documentation）：This directory contains helper sources which are injected into the page. 证据：`packages/injected/src/README.md`\n- **@playwright/browser-chromium**（documentation）：This package automatically installs Chromium https://www.chromium.org/ browser for Playwright http://github.com/microsoft/playwright library. If you want to write end-to-end tests, we recommend @playwright/test https://playwright.dev/docs/intro . 证据：`packages/playwright-browser-chromium/README.md`\n- **@playwright/browser-firefox**（documentation）：This package automatically installs Firefox https://www.mozilla.org/firefox/ browser for Playwright http://github.com/microsoft/playwright library. If you want to write end-to-end tests, we recommend @playwright/test https://playwright.dev/docs/intro . 证据：`packages/playwright-browser-firefox/README.md`\n- **@playwright/browser-webkit**（documentation）：This package automatically installs WebKit https://www.webkit.org/ browser for Playwright http://github.com/microsoft/playwright library. If you want to write end-to-end tests, we recommend @playwright/test https://playwright.dev/docs/intro . 证据：`packages/playwright-browser-webkit/README.md`\n- **playwright-chromium**（documentation）：This package contains the Chromium https://www.chromium.org/ flavor of the Playwright http://github.com/microsoft/playwright library. If you want to write end-to-end tests, we recommend @playwright/test https://playwright.dev/docs/intro . 证据：`packages/playwright-chromium/README.md`\n- **playwright-core**（documentation）：This package contains the no-browser flavor of Playwright http://github.com/microsoft/playwright . 证据：`packages/playwright-core/README.md`\n- **Readme**（documentation）：BEWARE This package is EXPERIMENTAL and does not respect semver. 证据：`packages/playwright-ct-core/README.md`\n- **Readme**（documentation）：BEWARE This package is EXPERIMENTAL and does not respect semver. 证据：`packages/playwright-ct-react/README.md`\n- **Readme**（documentation）：BEWARE This package is EXPERIMENTAL and does not respect semver. 证据：`packages/playwright-ct-react17/README.md`\n- **Readme**（documentation）：BEWARE This package is EXPERIMENTAL and does not respect semver. 证据：`packages/playwright-ct-vue/README.md`\n- **playwright-firefox**（documentation）：This package contains the Firefox https://www.mozilla.org/firefox/ flavor of the Playwright http://github.com/microsoft/playwright library. If you want to write end-to-end tests, we recommend @playwright/test https://playwright.dev/docs/intro . 证据：`packages/playwright-firefox/README.md`\n- **playwright-webkit**（documentation）：This package contains the WebKit https://www.webkit.org/ flavor of the Playwright http://github.com/microsoft/playwright library. If you want to write end-to-end tests, we recommend @playwright/test https://playwright.dev/docs/intro . 证据：`packages/playwright-webkit/README.md`\n- **Readme**（documentation）：Tests derived from axe-core test suite: https://github.com/dequelabs/axe-core/tree/develop/test. 证据：`tests/assets/axe-core/README.md`\n- **Client Certificate test-certificates**（documentation）：Client Certificate test-certificates 证据：`tests/assets/client-certificates/README.md`\n- **Playwright Modernizr tests**（documentation）：- modernizr.com modernizr.com isn't getting updated anymore, see here https://github.com/Modernizr/Modernizr/issues/2490 and here https://github.com/Modernizr/Modernizr/commit/db96bdaff995a1d4abccb0dc69c77db7b47ad614 . It only contains version 3.6. - This is why we build it from source ourselves, using roll.sh they recommend it . 证据：`tests/assets/modernizr/README.md`\n- **Readme**（documentation）：Source: https://github.com/mdn/dom-examples/tree/main/to-do-notifications 证据：`tests/assets/to-do-notifications/README.md`\n- **Regenerating**（documentation）：This font contains two glyphs — + U+2B and - U+2D — each rendered as a simple filled black rectangle. The simplicity makes screenshot tests insensitive to font-rendering/antialiasing differences across platforms. 证据：`tests/assets/webfont/README.md`\n- **Readme**（documentation）：Web platform tests are copied from https://github.com/web-platform-tests/wpt at revision 5adfe4e8cd223729aa2942915e8a515c079ed0ef . 证据：`tests/assets/wpt/README.md`\n- **Running Bidi tests**（documentation）：To install beta channel of Firefox, run the following command in the project root: After that you need to pass custom firefox binary path to the test runner via BIDI FFPATH : 证据：`tests/bidi/README.md`\n- **Getting Started with Create React App**（documentation）：Getting Started with Create React App 证据：`tests/components/ct-react17/README.md`\n- **ct-vue-cli**（documentation）：Compiles and hot-reloads for development 证据：`tests/components/ct-vue-cli/README.md`\n- **ct1**（documentation）：This template should help get you started developing with Vue 3 in Vite. 证据：`tests/components/ct-vue-vite/README.md`\n- **Julia SSIM trap**（documentation）：SSIM https://en.wikipedia.org/wiki/Structural similarity is a metric used to compare image similarity. 证据：`tests/image_tools/fixtures/should-fail/julia-ssim-trap/README.md`\n- **Readme**（documentation）：These tests are coming from the looks-same library: - https://github.com/gemini-testing/looks-same/blob/b9399bce8fd980e6e59cf740bee3cd3fe66c3eae/test/test.js 证据：`tests/image_tools/fixtures/should-fail/looks-same-tests/README.md`\n- **Original SSIM trap**（documentation）：SSIM https://en.wikipedia.org/wiki/Structural similarity is a metric used to compare image similarity. 证据：`tests/image_tools/fixtures/should-fail/original-ssim-trap/README.md`\n- **Trivial failing examples**（documentation）：Trivial failing examples Some trivial failing examples 证据：`tests/image_tools/fixtures/should-fail/trivial/README.md`\n- **Chrome non-deterministic rendering**（documentation）：Reported by: https://bugs.chromium.org/p/chromium/issues/detail?id=919955 证据：`tests/image_tools/fixtures/should-match/crbug-919955/README.md`\n- **Readme**（documentation）：These tests are coming from the looks-same library: - https://github.com/gemini-testing/looks-same/blob/b9399bce8fd980e6e59cf740bee3cd3fe66c3eae/test/test.js 证据：`tests/image_tools/fixtures/should-match/looks-same-tests/README.md`\n- **Tiny anti-aliasing sample**（documentation）：This is a 10x10 image sample with a 3 anti-aliased pixels in-between. This is actually a cropped down snapshot of one of the ubuntu-x86-vs-ubuntu-arm samples ../ubuntu-x86-vs-ubuntu-arm/samples/stylings stories-Stylings-stories-Texture-bar-should-use-custom-path-chrome/stylings-stories/texture/bar/should-use-custom-path-actual.png handy for debugging purposes. 证据：`tests/image_tools/fixtures/should-match/tiny-antialiasing-sample/README.md`\n- **Equal small images**（documentation）：Equal small images Simple equal images. 证据：`tests/image_tools/fixtures/should-match/trivial/README.md`\n- **Readme**（documentation）：A set of examples with rendering artifacts that happen when running Playwright screenshot tests on WebKit linux. 证据：`tests/image_tools/fixtures/should-match/webkit-rendering-artifacts/README.md`\n- **Readme**（documentation）：This directory holds a stable test runner: - It is possible to test broken test runner with a stable working one. - Dependencies between ToT and stable test runner do not clash. 证据：`tests/playwright-test/stable-test-runner/README.md`\n- **Readme**（documentation）：This folder contains the proxy https://github.com/TooTallNate/proxy-agents library vendored at commit c881a1804197b89580320b87082971c3c6a61746 with the following modifications: 证据：`tests/third_party/proxy/README.md`\n- **Flakiness Dashboard Backend**（documentation）：This directory contains source code for the Azure function that we use to aggregate test reports. The data is consumed by https://devops.playwright.dev/flakiness.html 证据：`utils/flakiness-dashboard/README.md`\n- **Mapping distribution libraries to package names**（documentation）：Mapping distribution libraries to package names 证据：`utils/linux-browser-dependencies/README.md`\n- **Package**（package_manifest）：{ \"name\": \"playwright-internal\", \"private\": true, \"version\": \"1.61.0-next\", \"description\": \"A high-level API to automate web browsers\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"scripts\": { \"ctest\": \"playwright test --config=tests/library/playwright.config.ts --project=chromium- \", \"ftest\": \"playwright test --config=tests/library/playwright.config.ts --project=firefox- \", \"wtest\": \"playwright test --config=tests/library/playwright.config.ts --project=webkit- \", \"atest\": \"playwright test --config=tests/a… 证据：`package.json`\n- **Contributing**（documentation）：To maintain project quality and focus, Playwright requires a corresponding issue for every contribution, with the exception of minor documentation fixes. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"github-api\", \"version\": \"0.0.1\", \"scripts\": { \"test\": \"playwright test\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"devDependencies\": { \"@playwright/test\": \"^1.17.1\" } } 证据：`examples/github-api/package.json`\n- **Package**（package_manifest）：{ \"name\": \"mock-battery\", \"version\": \"1.0.0\", \"description\": \"\", \"main\": \"index.js\", \"scripts\": { \"test\": \"playwright test\", \"start\": \"http-server -c-1 -p 9900 demo-battery-api\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"devDependencies\": { \"@playwright/test\": \"^1.19.1\", \"http-server\": \"^14.1.0\" } } 证据：`examples/mock-battery/package.json`\n- **Package**（package_manifest）：{ \"name\": \"mock-filesystem\", \"version\": \"1.0.0\", \"description\": \"\", \"main\": \"index.js\", \"scripts\": { \"test\": \"playwright test\", \"start\": \"http-server -c-1 -p 9900 src/\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"devDependencies\": { \"@playwright/test\": \"^1.19.1\", \"http-server\": \"^14.1.0\" } } 证据：`examples/mock-filesystem/package.json`\n- **Package**（package_manifest）：{ \"name\": \"svgomg-tests\", \"version\": \"0.0.1\", \"scripts\": { \"test\": \"playwright test\", \"ctest\": \"playwright test --project=chromium\", \"ftest\": \"playwright test --project=firefox\", \"wtest\": \"playwright test --project=webkit\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"devDependencies\": { \"@playwright/test\": \"^1.17.1\" } } 证据：`examples/svgomg/package.json`\n- **Package**（package_manifest）：{ \"name\": \"todomvc-test\", \"version\": \"0.0.1\", \"scripts\": { \"test\": \"playwright test\", \"ctest\": \"playwright test --project=chromium\", \"ftest\": \"playwright test --project=firefox\", \"wtest\": \"playwright test --project=webkit\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"devDependencies\": { \"@playwright/test\": \"^1.38.0\", \"dotenv\": \"^17.2.3\" } } 证据：`examples/todomvc/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/dashboard\", \"private\": true, \"version\": \"0.0.0\", \"type\": \"module\", \"dependencies\": { \"@browser-logos/chrome\": \"2.0.0\", \"@browser-logos/chrome-beta\": \"3.0.0\", \"@browser-logos/chrome-canary\": \"2.0.0\", \"@browser-logos/chrome-dev\": \"3.0.0\", \"@browser-logos/chromium\": \"2.0.1\", \"@browser-logos/edge\": \"2.0.7\", \"@browser-logos/firefox\": \"3.0.10\", \"@browser-logos/firefox-beta\": \"4.1.4\", \"@browser-logos/firefox-nightly\": \"3.0.6\", \"@browser-logos/safari\": \"2.1.0\" } } 证据：`packages/dashboard/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/extension\", \"version\": \"0.2.1\", \"description\": \"Playwright Browser Extension\", \"private\": true, \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\" } 证据：`packages/extension/package.json`\n- **Package**（package_manifest）：{ \"name\": \"html-reporter\", \"private\": true, \"version\": \"0.0.0\", \"type\": \"module\" } 证据：`packages/html-reporter/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/browser-chromium\", \"version\": \"1.61.0-next\", \"description\": \"Playwright package that automatically installs Chromium\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"import\": \"./index.mjs\", \"require\": \"./index.js\", \"default\": \"./index.js\" }, \"./package.json\": \"./package.json\" }, \"scripts\": { \"install\": \"node install.js\" }, \"dependencies\": { \"playwright-core\": \"1.61.0-next\" } } 证据：`packages/playwright-browser-chromium/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/browser-firefox\", \"version\": \"1.61.0-next\", \"description\": \"Playwright package that automatically installs Firefox\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"import\": \"./index.mjs\", \"require\": \"./index.js\", \"default\": \"./index.js\" }, \"./package.json\": \"./package.json\" }, \"scripts\": { \"install\": \"node install.js\" }, \"dependencies\": { \"playwright-core\": \"1.61.0-next\" } } 证据：`packages/playwright-browser-firefox/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/browser-webkit\", \"version\": \"1.61.0-next\", \"description\": \"Playwright package that automatically installs WebKit\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"import\": \"./index.mjs\", \"require\": \"./index.js\", \"default\": \"./index.js\" }, \"./package.json\": \"./package.json\" }, \"scripts\": { \"install\": \"node install.js\" }, \"dependencies\": { \"playwright-core\": \"1.61.0-next\" } } 证据：`packages/playwright-browser-webkit/package.json`\n- **Package**（package_manifest）：{ \"name\": \"playwright-chromium\", \"version\": \"1.61.0-next\", \"description\": \"A high-level API to automate Chromium\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"import\": \"./index.mjs\", \"require\": \"./index.js\", \"default\": \"./index.js\" }, \"./package.json\": \"./package.json\" }, \"bin\": { \"playwright\": \"cli.js\" }, \"scripts\": { \"install\": \"node install.js\" }, \"dependencies\": { \"playwright-core\": \"1.61.0-next\" } } 证据：`packages/playwright-chromium/package.json`\n- **Package**（package_manifest）：{ \"name\": \"playwright-cli-stub\", \"version\": \"0.0.0\", \"private\": true, \"bin\": { \"playwright-cli\": \"playwright-cli-stub.js\" } } 证据：`packages/playwright-cli-stub/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/client\", \"private\": true, \"version\": \"0.0.0\", \"description\": \"A thin client for Playwright\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"import\": \"./index.mjs\", \"require\": \"./index.js\", \"default\": \"./index.js\" }, \"./package.json\": \"./package.json\" }, \"scripts\": { \"esbuild\": \"node build.js\", \"build\": \"npm run esbuild\", \"watch\": \"npm run esbuild -- --watch\" }, \"dependencies\": { \"playwright-core\": \"1.61.0-next\" } } 证据：`packages/playwright-client/package.json`\n- **Package**（package_manifest）：{ \"name\": \"playwright-core\", \"version\": \"1.61.0-next\", \"description\": \"A high-level API to automate web browsers\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"import\": \"./index.mjs\", \"require\": \"./index.js\", \"default\": \"./index.js\" }, \"./package.json\": \"./package.json\", \"./lib/bootstrap\": \"./lib/bootstrap.js\", \"./lib/coreBundle\": \"./lib/coreBundle.js\", \"./lib/utilsBundle\": \"./lib/utilsBundle.js\", \"./lib/tools/cli-client/program\": \"./lib/tools/cli-client/program… 证据：`packages/playwright-core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/experimental-ct-core\", \"version\": \"1.61.0-next\", \"description\": \"Playwright Component Testing Helpers\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"default\": \"./index.js\" }, \"./lib/mount\": \"./lib/mount.js\", \"./lib/program\": \"./lib/program.js\", \"./types/component\": { \"types\": \"./types/component.d.ts\" } }, \"dependencies\": { \"playwright-core\": \"1.61.0-next\", \"vite\": \"^6.4.1\", \"playwright\": \"1.61.0-next\" } } 证据：`packages/playwright-ct-core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/experimental-ct-react\", \"version\": \"1.61.0-next\", \"description\": \"Playwright Component Testing for React\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"default\": \"./index.js\" }, \"./register\": { \"types\": \"./register.d.ts\", \"default\": \"./register.mjs\" }, \"./hooks\": { \"types\": \"./hooks.d.ts\", \"default\": \"./hooks.mjs\" }, \"./package.json\": \"./package.json\" }, \"dependencies\": { \"@playwright/experimental-ct-core\": \"1.61.0-next\", \"@vitejs/plugin-r… 证据：`packages/playwright-ct-react/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@playwright/experimental-ct-react17\", \"version\": \"1.61.0-next\", \"description\": \"Playwright Component Testing for React\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/microsoft/playwright.git\" }, \"homepage\": \"https://playwright.dev\", \"engines\": { \"node\": \" =18\" }, \"author\": { \"name\": \"Microsoft Corporation\" }, \"license\": \"Apache-2.0\", \"exports\": { \".\": { \"types\": \"./index.d.ts\", \"default\": \"./index.js\" }, \"./register\": { \"types\": \"./register.d.ts\", \"default\": \"./register.mjs\" }, \"./hooks\": { \"types\": \"./hooks.d.ts\", \"default\": \"./hooks.mjs\" }, \"./package.json\": \"./package.json\" }, \"dependencies\": { \"@playwright/experimental-ct-core\": \"1.61.0-next\", \"@vitejs/plugin… 证据：`packages/playwright-ct-react17/package.json`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `browser_patches/winldd/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `browser_patches/winldd/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json, CLAUDE.md\n- **快速入门**：importance `high`\n - source_paths: packages/playwright/package.json, packages/playwright-core/package.json, packages/playwright-test/package.json\n- **架构概览**：importance `high`\n - source_paths: packages/playwright-core/src/client/connection.ts, packages/playwright-core/src/remote/playwrightServer.ts, packages/playwright-core/src/inprocess.ts, packages/playwright-core/src/outofprocess.ts\n- **客户端实现**：importance `high`\n - source_paths: packages/playwright-core/src/client/page.ts, packages/playwright-core/src/client/frame.ts, packages/playwright-core/src/client/locator.ts, packages/playwright-core/src/client/elementHandle.ts, packages/playwright-core/src/client/browserContext.ts\n- **服务器端实现**：importance `high`\n - source_paths: packages/playwright-core/src/server/browser.ts, packages/playwright-core/src/server/browserContext.ts, packages/playwright-core/src/server/page.ts, packages/playwright-core/src/server/dispatchers/dispatcher.ts, packages/playwright-core/src/server/network.ts\n- **浏览器支持**：importance `high`\n - source_paths: packages/playwright-core/src/server/chromium/crBrowser.ts, packages/playwright-core/src/server/firefox/ffBrowser.ts, packages/playwright-core/src/server/webkit/wkBrowser.ts, packages/playwright-core/src/server/browserType.ts, browser_patches/firefox/juggler\n- **测试框架**：importance `high`\n - source_paths: packages/playwright/src/common/config.ts, packages/playwright/src/common/fixtures.ts, packages/playwright/src/common/test.ts, packages/playwright/src/runner/testRunner.ts, packages/playwright/src/runner/dispatcher.ts\n- **定位器和选择器**：importance `high`\n - source_paths: 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\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `bb7af07608e50f6b1e3cd534af30294a94ba8336`\n- inspected_files: `package.json`, `README.md`, `docs/src/emulation.md`, `docs/src/other-locators.md`, `docs/src/codegen.md`, `docs/src/library-csharp.md`, `docs/src/test-retries-js.md`, `docs/src/test-runners-python.md`, `docs/src/test-cli-js.md`, `docs/src/test-webserver-js.md`, `docs/src/intro-python.md`, `docs/src/test-reporters-js.md`, `docs/src/api-testing-js.md`, `docs/src/writing-tests-js.md`, `docs/src/locators.md`, `docs/src/running-tests-java.md`, `docs/src/protractor-js.md`, `docs/src/dialogs.md`, `docs/src/running-tests-csharp.md`, `docs/src/frames.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9f8ee5532aee4b6cbf512f4227b0bac6 | https://github.com/microsoft/playwright/issues/40856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9ae154da8c374e95842c5b9fed587329 | https://github.com/microsoft/playwright/issues/40857 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_d99eb725d0044cc8a856ff77a5034353 | https://github.com/microsoft/playwright/issues/40868 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Bug]: test body doesn't accept function with a return type other than void\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: test body doesn't accept function with a return type other than void\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_068a984a4ea348dd8b8de11244fbddd2 | https://github.com/microsoft/playwright/issues/40851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[Feature] Allow custom command-line arguments in @playwright/test\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Allow custom command-line arguments in @playwright/test\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_27f460cbef7e4489b323fb9fb7cfc515 | https://github.com/microsoft/playwright/issues/10337 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.56.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.56.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_cc7813a33a854a3c8465dd3548ef7684 | https://github.com/microsoft/playwright/releases/tag/v1.56.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.57.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.57.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_5d76f3b46992422c8b4a18583cabd192 | https://github.com/microsoft/playwright/releases/tag/v1.57.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v1.59.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.59.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c4296f1e3e0d4e37bbecccf2fe087c00 | https://github.com/microsoft/playwright/releases/tag/v1.59.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v1.60.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v1.60.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2bf82c9b52a6418986114131cd1bd2d3 | https://github.com/microsoft/playwright/releases/tag/v1.60.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:221981891 | https://github.com/microsoft/playwright | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：microsoft/playwright\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Bug]: module.register() deprecation warning (DEP0205) on Node 26（medium）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]: test body doesn't accept function with a return type other than void（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Feature] Allow custom command-line arguments in @playwright/test（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/microsoft/playwright 项目说明书\n\n生成时间：2026-05-16 05:45:44 UTC\n\n## 目录\n\n- [项目概述](#project-overview)\n- [快速入门](#getting-started)\n- [架构概览](#architecture-overview)\n- [客户端实现](#client-implementation)\n- [服务器端实现](#server-implementation)\n- [浏览器支持](#browser-support)\n- [测试框架](#test-framework)\n- [定位器和选择器](#locators-and-selectors)\n- [断言系统](#assertions)\n- [命令行工具](#cli-tools)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [快速入门](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n- [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)\n- [packages/playwright-core/src/tools/cli-client/skill/references/running-code.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/running-code.md)\n- [packages/trace-viewer/src/ui/workbenchLoader.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/workbenchLoader.tsx)\n- [packages/playwright-core/src/server/codegen/csharp.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/codegen/csharp.ts)\n- [packages/injected/src/consoleApi.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/consoleApi.ts)\n- [packages/html-reporter/src/testCaseView.tsx](https://github.com/microsoft/playwright/blob/main/packages/html-reporter/src/testCaseView.tsx)\n- [packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md)\n \n\n# 项目概述\n\n## 什么是 Playwright\n\nPlaywright 是由 Microsoft 开发的一个跨浏览器自动化测试框架，支持 Chromium、Firefox 和 WebKit 浏览器。它提供了可靠的方式来测试现代 Web 应用程序，支持自动化点击、输入、表单提交、截图、PDF 生成等操作。\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()\n\n## 核心架构\n\nPlaywright 项目采用多包架构，包含以下主要组件：\n\n```mermaid\ngraph TD\n A[Playwright] --> B[playwright-core]\n A --> C[trace-viewer]\n A --> D[html-reporter]\n A --> E[playwright]\n B --> F[CLI 工具]\n B --> G[浏览器驱动]\n F --> H[playwright-cli]\n F --> I[playwright-trace]\n```\n\n### 核心包说明\n\n| 包名 | 功能描述 |\n|------|----------|\n| `playwright` | 主包，提供完整的测试 API |\n| `playwright-core` | 核心引擎，不包含浏览器二进制文件 |\n| `trace-viewer` | 追踪文件可视化查看器 |\n| `html-reporter` | HTML 测试报告生成器 |\n| `injected` | 页面内注入脚本，提供调试能力 |\n\n资料来源：[packages/injected/src/consoleApi.ts:18-26]()\n\n## CLI 工具集\n\nPlaywright CLI 提供了丰富的命令行工具，用于浏览器自动化操作和测试调试。\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()\n\n### 页面操作命令\n\n```bash\n# 导航和页面控制\nplaywright-cli goto \nplaywright-cli back\nplaywright-cli forward\nplaywright-cli reload\nplaywright-cli close\n```\n\n### 元素交互命令\n\n| 命令 | 功能 |\n|------|------|\n| `click` | 点击元素 |\n| `dblclick` | 双击元素 |\n| `hover` | 悬停元素 |\n| `fill` | 填写输入框 |\n| `select` | 选择下拉选项 |\n| `check/uncheck` | 勾选/取消复选框 |\n\n```bash\nplaywright-cli click e15\nplaywright-cli fill \"#search-input\" \"搜索内容\"\nplaywright-cli screenshot --filename=page.png\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()\n\n### 代码执行\n\n使用 `run-code` 命令在浏览器上下文中执行 JavaScript 代码：\n\n```bash\n# 读取剪贴板\nplaywright-cli run-code \"async page => {\n await page.context().grantPermissions(['clipboard-read']);\n return await page.evaluate(() => navigator.clipboard.readText());\n}\"\n\n# 执行 JavaScript 并获取结果\nplaywright-cli run-code \"async page => {\n return await page.evaluate(() => {\n return {\n userAgent: navigator.userAgent,\n language: navigator.language,\n cookiesEnabled: navigator.cookieEnabled\n };\n });\n}\"\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/running-code.md]()\n\n### 存储管理\n\n```bash\n# 状态持久化\nplaywright-cli state-save auth.json\nplaywright-cli state-load auth.json\n\n# Cookie 操作\nplaywright-cli cookie-list\nplaywright-cli cookie-get session_id\nplaywright-cli cookie-set session_id abc123 --httpOnly --secure\n\n# LocalStorage\nplaywright-cli localstorage-list\nplaywright-cli localstorage-get theme\nplaywright-cli localstorage-set theme dark\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()\n\n### 标签页管理\n\n```bash\nplaywright-cli tab-list\nplaywright-cli tab-new https://example.com\nplaywright-cli tab-close\nplaywright-cli tab-select 0\n```\n\n## Trace 查看器\n\nPlaywright Trace CLI 是一个命令行工具，用于检查测试生成的 `.zip` 追踪文件，无需打开浏览器。\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n### 追踪命令\n\n```bash\n# 打开追踪文件\nnpx playwright trace open \n\n# 列出所有操作\nnpx playwright trace actions\n\n# 查看特定操作详情\nnpx playwright trace action 12\n\n# 查看快照\nnpx playwright trace snapshot 12\n\n# 查看网络请求\nnpx playwright trace requests --failed\n\n# 查看控制台错误\nnpx playwright trace console --errors-only\n```\n\n### 典型调查流程\n\n```bash\n# 1. 打开追踪\nnpx playwright trace open test-results/my-test/trace.zip\n\n# 2. 查看操作列表\nnpx playwright trace actions\n\n# 3. 找出失败的操作\nnpx playwright trace actions --errors-only\n\n# 4. 分析失败详情\nnpx playwright trace action 12\n\n# 5. 查看页面快照\nnpx playwright trace snapshot 12\n\n# 6. 查询 DOM 获取更多信息\nnpx playwright trace snapshot 12 -- eval \"document.querySelector('.error-message').textContent\"\n\n# 7. 检查网络失败\nnpx playwright trace requests --failed\n\n# 8. 检查控制台错误\nnpx playwright trace console --errors-only\n```\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n### Trace Viewer Web 应用\n\nTrace Viewer 也是一个渐进式 Web 应用（PWA），可通过 `trace.playwright.dev` 在线访问：\n\n```tsx\n1. Download the trace from the download shelf
\n\n3. Drop the trace from the download shelf into the page
\n```\n\n资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx:1-20]()\n\n## 代码生成\n\nPlaywright 支持多种编程语言的测试代码生成，包括 JavaScript、TypeScript、C# 等。\n\n资料来源：[packages/playwright-core/src/server/codegen/csharp.ts]()\n\n### C# 代码生成\n\n```csharp\n// 创建新页面\nvar page = await context.NewPageAsync();\nawait page.GotoAsync(\"https://example.com\");\n\n// 对话框处理\nvoid Page_Dialog_EventHandler(object sender, IDialog dialog)\n{\n Console.WriteLine($\"Dialog message: {dialog.Message}\");\n dialog.DismissAsync();\n Page.Dialog -= Page_Dialog_EventHandler;\n}\nPage.Dialog += Page_Dialog_EventHandler;\n\n// 下载处理\nvar download = await Page.RunAndWaitForDownloadAsync(async () =>\n{\n // 执行下载操作\n});\n```\n\n资料来源：[packages/playwright-core/src/server/codegen/csharp.ts:1-30]()\n\n## HTML 报告器\n\nPlaywright HTML Reporter 用于生成可视化的测试报告，包含测试用例状态、持续时间、注释等信息。\n\n```tsx\n ({\n id: String(index),\n title: \n {statusIcon(result.status)} {retryLabel(index)}\n {(test.results.length > 1) && {msToString(result.duration)}}\n
,\n render: () => { /* 渲染测试结果 */ }\n }))\n} />\n```\n\n资料来源：[packages/html-reporter/src/testCaseView.tsx:1-30]()\n\n### 报告功能\n\n| 功能 | 说明 |\n|------|------|\n| 测试状态图标 | 显示通过/失败/跳过等状态 |\n| 重试标签 | 标记重试次数 |\n| 持续时间 | 显示每个测试的执行时长 |\n| 注释展示 | 显示测试注释和注解 |\n| 追踪链接 | 提供到追踪文件的链接 |\n\n资料来源：[packages/html-reporter/src/testCaseView.tsx:30-50]()\n\n## 页面注入 API\n\nPlaywright 在浏览器上下文中注入了 `window.playwright` 对象，提供调试和测试辅助功能：\n\n```typescript\ninstall() {\n this._injectedScript.window.playwright = {\n $: (selector: string, strict?: boolean) => this._querySelector(selector, !!strict),\n $$: (selector: string) => this._querySelectorAll(selector),\n inspect: (selector: string) => this._inspect(selector),\n selector: (element: Element) => this._selector(element),\n generateLocator: (element: Element, language?: Language) => this._generateLocator(element, language),\n ariaSnapshot: (element?: Element, options?: AriaTreeOptions) => {\n return this._injectedScript.ariaSnapshot(element || this._injectedScript.document.body, options || { mode: 'default' });\n },\n resume: () => this._resume(),\n ...new Locator(this._injectedScript, ''),\n };\n}\n```\n\n资料来源：[packages/injected/src/consoleApi.ts:18-35]()\n\n### 可用方法\n\n| 方法 | 功能描述 |\n|------|----------|\n| `$.query()` | 使用 Playwright 选择器语法查询单个元素 |\n| `$$.queryAll()` | 查询所有匹配的元素 |\n| `inspect()` | 检查元素的定位器信息 |\n| `selector()` | 生成元素的选择器 |\n| `generateLocator()` | 生成可用的定位器代码 |\n| `ariaSnapshot()` | 获取 ARIA 树快照 |\n| `resume()` | 恢复测试执行 |\n\n## 规范驱动测试\n\nPlaywright 支持基于规范的测试工作流，帮助团队从用户故事生成可执行的测试用例。\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()\n\n### 测试工作流\n\n```mermaid\ngraph LR\n A[编写规范] --> B[生成 Seed 测试]\n B --> C[探索应用]\n C --> D[完善规范]\n D --> E[生成测试代码]\n E --> F[运行测试]\n```\n\n### 规范文件结构\n\n```markdown\n# <功能> 测试计划\n\n## 应用概述\n<描述功能做什么以及为什么重要>\n\n## 测试场景\n\n### 1. <分组名称>\n**Seed:** `tests/seed.spec.ts`\n\n#### 1.1. <场景名称>\n**文件:** `tests//.spec.ts`\n\n**步骤:**\n 1. <具体用户操作>\n - expect: <可观察的结果>\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()\n\n### 探索应用\n\n```bash\n# 启动应用进行探索\nPLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli\n\n# 附加到调试会话\nplaywright-cli attach tw-XXXX\n\n# 探索命令\nplaywright-cli resume # 运行 seed 测试\nplaywright-cli snapshot # 元素清单\nplaywright-cli click e5 # 点击元素\nplaywright-cli eval \"location.href\" # 读取 URL/状态\nplaywright-cli show --annotate # 请求用户指向\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/spec-driven-testing.md]()\n\n## 总结\n\nPlaywright 是一个功能完整的跨浏览器测试框架，主要特点包括：\n\n- **多浏览器支持**：Chromium、Firefox、WebKit\n- **丰富的 CLI 工具**：playwright-cli 和 playwright-trace\n- **代码生成能力**：支持多种编程语言\n- **追踪可视化**：支持离线查看测试执行过程\n- **规范驱动测试**：支持从用户规范生成测试\n- **页面注入调试**：提供浏览器内调试 API\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目概述](#project-overview), [测试框架](#test-framework), [命令行工具](#cli-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/microsoft/playwright/blob/main/package.json)\n- [examples/svgomg/package.json](https://github.com/microsoft/playwright/blob/main/examples/svgomg/package.json)\n- [examples/todomvc/package.json](https://github.com/microsoft/playwright/blob/main/examples/todomvc/package.json)\n- [packages/playwright/package.json](https://github.com/microsoft/playwright/blob/main/packages/playwright/package.json)\n- [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)\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n \n\n# 快速入门\n\n## 概述\n\nPlaywright 是一个用于自动化 Web 浏览器的 Node.js 库，由 Microsoft 开发维护。它提供了高层次的 API，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎。Playwright 的主要特性包括：跨浏览器自动化、自动化等待机制、自动录制功能、以及强大的调试工具。\n\n当前版本为 **1.61.0-next**，最低要求 Node.js 18 及以上版本。\n\n## 安装 Playwright\n\n### 系统要求\n\n| 组件 | 要求 |\n|------|------|\n| Node.js | >= 18 |\n| 操作系统 | Windows、macOS、Linux |\n| 浏览器 | Chromium、Firefox、WebKit |\n\n### 安装命令\n\n```bash\n# 使用 npm 安装\nnpm install @playwright/test\n\n# 使用 yarn 安装\nyarn add @playwright/test\n\n# 使用 pnpm 安装\npnpm add @playwright/test\n```\n\n安装完成后，需要下载浏览器依赖：\n\n```bash\n# 下载所有浏览器\nnpx playwright install\n\n# 仅安装特定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n## 创建第一个测试\n\n### 项目结构\n\nPlaywright 测试项目通常包含以下文件：\n\n```\nmy-playwright-project/\n├── package.json\n├── playwright.config.ts\n├── tests/\n│ └── example.spec.ts\n└── playwright-report/\n```\n\n### 配置文件\n\n在项目根目录创建 `playwright.config.ts`：\n\n```typescript\nimport { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n testDir: './tests',\n fullyParallel: true,\n forbidOnly: !!process.env.CI,\n retries: process.env.CI ? 2 : 0,\n workers: process.env.CI ? 1 : undefined,\n reporter: 'html',\n use: {\n baseURL: 'http://localhost:3000',\n trace: 'on-first-retry',\n },\n projects: [\n {\n name: 'chromium',\n use: { ...devices['Desktop Chrome'] },\n },\n {\n name: 'firefox',\n use: { ...devices['Desktop Firefox'] },\n },\n {\n name: 'webkit',\n use: { ...devices['Desktop Safari'] },\n },\n ],\n});\n```\n\n资料来源：[examples/svgomg/package.json:1-13]()\n\n### 编写测试用例\n\n创建 `tests/example.spec.ts` 文件：\n\n```typescript\nimport { test, expect } from '@playwright/test';\n\ntest('has title', async ({ page }) => {\n await page.goto('https://example.com');\n await expect(page).toHaveTitle(/Example Domain/);\n});\n\ntest('get started link', async ({ page }) => {\n await page.goto('https://example.com');\n await page.getByRole('link', { name: 'More information' }).click();\n await expect(page).toHaveURL(/.*more/);\n});\n```\n\n## 运行测试\n\n### 基本命令\n\n| 命令 | 说明 |\n|------|------|\n| `npx playwright test` | 运行所有测试 |\n| `npx playwright test --project=chromium` | 仅运行 Chromium 测试 |\n| `npx playwright test tests/example.spec.ts` | 运行指定文件 |\n| `npx playwright test --grep \"login\"` | 运行匹配的测试 |\n\n### 调试模式\n\n使用 CLI 调试模式启动测试：\n\n```bash\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n```\n\n调试时会输出会话名称，格式为 `tw-XXXX`。使用 `playwright-cli` 附加到该会话进行调试：\n\n```bash\nplaywright-cli attach tw-XXXX\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md:1-21]()\n\n## Playwright CLI 工具\n\n`playwright-cli` 是 Playwright 提供的命令行交互工具，支持浏览器会话管理、元素交互、快照获取等功能。\n\n### 常用命令\n\n#### 浏览器会话管理\n\n```bash\n# 打开浏览器\nplaywright-cli open https://example.com\n\n# 使用指定浏览器\nplaywright-cli open https://example.com --browser=firefox\n\n# 有头模式\nplaywright-cli open https://example.com --headed\n\n# 关闭所有浏览器\nplaywright-cli close-all\n\n# 强制终止所有浏览器进程\nplaywright-cli kill-all\n```\n\n#### 页面交互\n\n```bash\n# 点击元素（使用快照中的 ref）\nplaywright-cli click e5\n\n# 使用 CSS 选择器\nplaywright-cli click \"#main > button.submit\"\n\n# 填写输入框\nplaywright-cli fill e2 \"test input\"\n\n# 获取快照\nplaywright-cli snapshot\n\n# 截图\nplaywright-cli screenshot --filename=page.png\n```\n\n#### 元素定位\n\nPlaywright 支持多种定位策略：\n\n| 定位方式 | 示例 |\n|----------|------|\n| CSS 选择器 | `\"#main > button.submit\"` |\n| Role 定位器 | `\"getByRole('button', { name: 'Submit' })\"` |\n| 测试 ID | `\"getByTestId('submit-button')\"` |\n| 快照引用 | `e5`, `e15` |\n\n#### 网络拦截\n\n```bash\n# 拦截请求返回 404\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 拦截并返回 mock 数据\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md:1-120]()\n\n### 持久化会话\n\n使用命名会话可以保持浏览器状态：\n\n```bash\n# 创建持久化会话\nplaywright-cli -s=mysession open https://example.com --persistent\n\n# 附加到会话\nplaywright-cli -s=mysession click e6\n\n# 关闭会话\nplaywright-cli -s=mysession close\n\n# 删除会话数据\nplaywright-cli -s=mysession delete-data\n```\n\n## 追踪与调试\n\n### 追踪功能\n\nPlaywright 可以录制完整的测试执行轨迹，包含 DOM 快照、截图、网络活动和控制台日志。\n\n#### 使用 CLI 录制追踪\n\n```bash\n# 开始录制\nplaywright-cli tracing-start\n\n# 执行操作\nplaywright-cli open https://example.com\nplaywright-cli click e1\nplaywright-cli fill e2 \"test\"\n\n# 停止录制\nplaywright-cli tracing-stop\n```\n\n录制完成后，会在 `traces/` 目录下生成以下文件：\n\n| 文件 | 说明 |\n|------|------|\n| `trace-{timestamp}.trace` | 动作日志，包含所有操作、DOM 快照、截图 |\n| `trace-{timestamp}.network` | 网络日志，包含所有请求和响应 |\n| `resources/` | 缓存的资源文件 |\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/tracing.md:1-45]()\n\n### Trace Viewer\n\n使用 Playwright Trace CLI 查看追踪文件：\n\n```bash\n# 打开追踪文件\nnpx playwright trace open \n\n# 查看所有动作\nnpx playwright trace actions\n\n# 查看失败的动作\nnpx playwright trace actions --errors-only\n\n# 查看动作详情\nnpx playwright trace action \n\n# 查看快照\nnpx playwright trace snapshot \n\n# 查看控制台错误\nnpx playwright trace console --errors-only\n\n# 查看失败的请求\nnpx playwright trace requests --failed\n\n# 关闭追踪\nnpx playwright trace close\n```\n\n典型调查流程：\n\n```bash\n# 1. 打开追踪文件\nnpx playwright trace open test-results/my-test/trace.zip\n\n# 2. 查看执行的动作\nnpx playwright trace actions\n\n# 3. 查看失败的动作\nnpx playwright trace actions --errors-only\n\n# 4. 查看详情\nnpx playwright trace action 12\n\n# 5. 查看页面快照\nnpx playwright trace snapshot 12\n\n# 6. 查询 DOM 获取更多细节\nnpx playwright trace snapshot 12 -- eval \"document.querySelector('.error-message').textContent\"\n\n# 7. 检查网络失败\nnpx playwright trace requests --failed\n\n# 8. 检查控制台错误\nnpx playwright trace console --errors-only\n```\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md:1-75]()\n\n## 浏览器会话与存储\n\n### 保存和加载状态\n\n```bash\n# 保存状态\nplaywright-cli state-save auth.json\n\n# 加载状态\nplaywright-cli state-load auth.json\n```\n\n### Cookie 管理\n\n```bash\n# 列出所有 Cookie\nplaywright-cli cookie-list\n\n# 按域名过滤\nplaywright-cli cookie-list --domain=example.com\n\n# 获取指定 Cookie\nplaywright-cli cookie-get session_id\n\n# 设置 Cookie\nplaywright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure\n\n# 删除 Cookie\nplaywright-cli cookie-delete session_id\n\n# 清除所有 Cookie\nplaywright-cli cookie-clear\n```\n\n### 本地存储\n\n```bash\n# LocalStorage\nplaywright-cli localstorage-list\nplaywright-cli localstorage-get theme\nplaywright-cli localstorage-set theme dark\nplaywright-cli localstorage-delete theme\nplaywright-cli localstorage-clear\n\n# SessionStorage\nplaywright-cli sessionstorage-list\nplaywright-cli sessionstorage-set step 3\nplaywright-cli sessionstorage-delete step\nplaywright-cli sessionstorage-clear\n```\n\n## 代码执行\n\n### 使用 run-code 执行自定义代码\n\n```bash\n# 获取页面标题\nplaywright-cli run-code \"async page => {\n return await page.title();\n}\"\n\n# 获取当前 URL\nplaywright-cli run-code \"async page => {\n return page.url();\n}\"\n\n# 读取剪贴板\nplaywright-cli run-code \"async page => {\n await page.context().grantPermissions(['clipboard-read']);\n return await page.evaluate(() => navigator.clipboard.readText());\n}\"\n\n# 从文件执行代码\nplaywright-cli run-code --filename=script.js\n```\n\n### 使用 eval 执行 JavaScript\n\n```bash\n# 获取页面标题\nplaywright-cli eval \"document.title\"\n\n# 获取元素内容\nplaywright-cli eval \"el => el.textContent\" e5\n\n# 获取元素属性\nplaywright-cli eval \"el => el.getAttribute('data-testid')\" e5\n\n# 保存结果到文件\nplaywright-cli eval \"document.body.outerHTML\" --filename=page.html\n```\n\n## 运行 npm 脚本示例\n\n项目中的 `package.json` 定义了常用的测试脚本：\n\n| 脚本 | 说明 |\n|------|------|\n| `npm run test` | 运行所有浏览器测试 |\n| `npm run ctest` | 仅运行 Chromium 测试 |\n| `npm run ftest` | 仅运行 Firefox 测试 |\n| `npm run wtest` | 仅运行 WebKit 测试 |\n\n资料来源：[package.json:19-35]()\n\n## 快速参考\n\n### 一分钟启动\n\n```bash\n# 1. 初始化项目\nnpm init -y\n\n# 2. 安装 Playwright\nnpm install @playwright/test\n\n# 3. 安装浏览器\nnpx playwright install\n\n# 4. 创建配置\ncat > playwright.config.ts << 'EOF'\nimport { defineConfig } from '@playwright/test';\nexport default defineConfig({\n testDir: './tests',\n use: { baseURL: 'http://localhost:3000' },\n});\nEOF\n\n# 5. 运行测试\nnpx playwright test\n```\n\n### 常用命令速查\n\n| 操作 | 命令 |\n|------|------|\n| 运行所有测试 | `npx playwright test` |\n| 运行指定浏览器 | `npx playwright test --project=chromium` |\n| 生成测试 | `npx playwright test --generate` |\n| 显示 HTML 报告 | `npx playwright show-report` |\n| 调试测试 | `npx playwright test --debug` |\n| 录制追踪 | `npx playwright show-trace trace.zip` |\n\n---\n\n\n\n## 架构概览\n\n### 相关页面\n\n相关主题：[客户端实现](#client-implementation), [服务器端实现](#server-implementation), [浏览器支持](#browser-support)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/client/connection.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/connection.ts)\n- [packages/playwright-core/src/remote/playwrightServer.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/remote/playwrightServer.ts)\n- [packages/playwright-core/src/inprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/inprocess.ts)\n- [packages/playwright-core/src/outofprocess.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/outofprocess.ts)\n \n\n# 架构概览\n\nPlaywright 是一个用于自动化浏览器操作的高级 API 库。本页面详细介绍其核心架构设计，包括进程模型、客户端-服务器通信机制以及主要组件的职责划分。\n\n## 核心设计理念\n\nPlaywright 的架构围绕两个核心目标设计：\n\n| 目标 | 说明 |\n|------|------|\n| **跨浏览器一致性** | 提供统一的 API 接口，支持 Chromium、Firefox 和 WebKit 三种浏览器引擎 |\n| **灵活的进程模型** | 支持进程内（in-process）和进程外（out-of-process）两种执行模式 |\n\nPlaywright 的核心代码位于 `packages/playwright-core/` 包中，负责处理底层浏览器通信和 API 实现。\n\n## 进程模型\n\nPlaywright 支持两种进程模型，开发者可以根据场景选择适合的模式。\n\n### 进程外模式（Out-of-Process）\n\n进程外模式是 Playwright 的默认和推荐模式。在此模式下，Playwright 会在独立进程中启动浏览器，并通过 IPC（进程间通信）与浏览器进行交互。\n\n```mermaid\ngraph TD\n A[Playwright Client] -->|IPC| B[Playwright Server Process]\n B -->|CDP Protocol| C[Chromium]\n B -->|CDP Protocol| D[Firefox]\n B -->|CDP Protocol| E[WebKit]\n \n B --> F[Browser Processes]\n F --> G[Renderer Processes]\n F --> H[GPU Process]\n```\n\n**特点：**\n- 隔离性强，浏览器崩溃不会影响主进程\n- 支持远程连接（Remote Connection）\n- 便于调试和监控\n- 通过 `playwright-core/src/outofprocess.ts` 实现\n\n资料来源：[packages/playwright-core/src/outofprocess.ts:1-50]()\n\n### 进程内模式（In-Process）\n\n进程内模式将 Playwright 和浏览器运行在同一进程中，减少了进程间通信的开销。此模式主要用于：\n\n- 测试框架集成（如 `@playwright/test`）\n- 需要快速执行的场景\n- 与宿主应用紧密集成的用例\n\n```mermaid\ngraph LR\n A[Host Application] -->|Direct API| B[Playwright In-Process]\n B --> C[Browser Instance]\n```\n\n资料来源：[packages/playwright-core/src/inprocess.ts:1-30]()\n\n## 客户端连接架构\n\nPlaywright 的客户端通过 `Connection` 类建立与服务器端的通信通道。\n\n### 连接类型\n\n| 连接类型 | 适用场景 | 实现文件 |\n|----------|----------|----------|\n| **远程连接（Remote）** | 连接到独立的 Playwright 服务器进程 | `connection.ts` |\n| **本地连接（Local）** | 直接连接到同进程或子进程的服务器 | `connection.ts` |\n| **CDP 连接** | 直接使用 Chrome DevTools Protocol | `connection.ts` |\n\n### 连接生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as Playwright Client\n participant Conn as Connection\n participant Server as Playwright Server\n \n Client->>Conn: createConnection()\n Conn->>Server: establishTransport()\n Server-->>Conn: transportEstablished\n Conn-->>Client: connected\n \n Client->>Conn: sendMessage()\n Conn->>Server: dispatch()\n Server-->>Conn: response\n Conn-->>Client: callback\n \n Client->>Conn: close()\n Conn->>Server: disconnect()\n```\n\n资料来源：[packages/playwright-core/src/client/connection.ts:1-100]()\n\n## 服务器端架构\n\nPlaywright 服务器端负责管理浏览器实例和处理来自客户端的请求。\n\n### 服务器组件\n\n| 组件 | 职责 |\n|------|------|\n| **PlaywrightServer** | 主服务器类，管理所有浏览器会话 |\n| **BrowserSession** | 管理单个浏览器实例的生命周期 |\n| **ChromiumBrowser** | Chromium 特定实现 |\n| **FirefoxBrowser** | Firefox 特定实现 |\n| **WebKitBrowser** | WebKit 特定实现 |\n\n### 服务器传输层\n\n服务器支持多种传输协议：\n\n- **stdio 传输**：用于父子进程通信\n- **WebSocket 传输**：用于远程连接\n- **CDP 传输**：直接与浏览器 DevTools 端口通信\n\n资料来源：[packages/playwright-core/src/remote/playwrightServer.ts:1-80]()\n\n## 浏览器会话管理\n\nPlaywright 通过会话（Session）机制管理多个独立的浏览器上下文。\n\n### 会话类型\n\n```mermaid\ngraph TD\n A[PlaywrightServer] --> B[BrowserSession 1]\n A --> C[BrowserSession 2]\n A --> D[BrowserSession N]\n \n B --> E[BrowserContext 1]\n B --> F[BrowserContext 2]\n \n E --> G[Page 1]\n E --> H[Page 2]\n G --> I[Frame]\n```\n\n### 持久化会话\n\nPlaywright 支持持久化会话（Persistent Context），允许保存和恢复浏览器状态：\n\n```bash\n# 创建命名会话\nplaywright-cli -s=mysession open https://example.com --persistent\n\n# 指定配置文件目录\nplaywright-cli -s=mysession open https://example.com --profile=/path/to/profile\n```\n\n这对于需要保持登录状态的测试场景非常有用。\n\n## 命令执行流程\n\nPlaywright CLI 提供了丰富的命令行接口来与浏览器交互。\n\n### 核心命令处理\n\n```\nplaywright-cli open → Browser.open()\nplaywright-cli goto → Page.goto()\nplaywright-cli click → Page.click()\nplaywright-cli fill → Page.fill()\n```\n\n### 元素定位策略\n\nPlaywright 支持多种元素定位方式：\n\n| 定位方式 | 示例 | 优先级 |\n|----------|------|--------|\n| **Ref 引用** | `e15` | 最高（快照生成） |\n| **CSS 选择器** | `#main > button` | 高 |\n| **角色定位器** | `getByRole('button')` | 高 |\n| **测试 ID** | `getByTestId('submit')` | 中 |\n| **文本内容** | `getByText('Submit')` | 中 |\n\n## 网络拦截\n\nPlaywright 提供了强大的网络拦截功能，用于测试和调试。\n\n### 路由（Route）操作\n\n```bash\n# 拦截特定请求\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 修改响应内容\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\n```\n\n### 存储管理\n\n| 存储类型 | 列表 | 获取 | 设置 | 删除 |\n|----------|------|------|------|------|\n| **Cookies** | `cookie-list` | `cookie-get` | `cookie-set` | `cookie-delete` |\n| **LocalStorage** | `localstorage-list` | `localstorage-get` | `localstorage-set` | `localstorage-delete` |\n| **SessionStorage** | `sessionstorage-list` | `sessionstorage-get` | `sessionstorage-set` | `sessionstorage-delete` |\n\n## 跟踪与调试\n\nPlaywright 的跟踪功能可以捕获详细的执行信息，用于问题排查和性能分析。\n\n### 跟踪文件结构\n\n```\ntraces/\n├── trace-{timestamp}.trace # 操作日志\n├── trace-{timestamp}.network # 网络活动\n└── resources/ # 缓存资源\n```\n\n### CLI 跟踪命令\n\n```bash\n# 开始跟踪\nplaywright-cli tracing-start\n\n# 执行测试操作\nplaywright-cli click e1\nplaywright-cli fill e2 \"test\"\n\n# 停止跟踪\nplaywright-cli tracing-stop\n```\n\n## 扩展机制\n\nPlaywright 支持通过插件扩展功能。\n\n### MCP 集成\n\nPlaywright 提供了 MCP（Model Context Protocol）服务器集成，可以通过 AI 助手控制浏览器：\n\n```bash\n# 运行 MCP 测试\nnpm run test-mcp\n```\n\n### 扩展测试\n\n```bash\n# 测试扩展功能\nnpm run test-extension\n```\n\n## 包结构\n\n| 包名 | 说明 |\n|------|------|\n| `playwright-core` | 核心库，包含所有底层实现 |\n| `@playwright/test` | 测试框架，提供 `test()` 和 `expect()` |\n| `playwright` | 完整包，包含浏览器驱动 |\n| `@playwright/browser-chromium` | Chromium 浏览器驱动 |\n| `@playwright/browser-firefox` | Firefox 浏览器驱动 |\n| `@playwright/browser-webkit` | WebKit 浏览器驱动 |\n| `playwright-chromium` | Chromium 便捷包 |\n| `playwright-firefox` | Firefox 便捷包 |\n| `playwright-webkit` | WebKit 便捷包 |\n\n## 总结\n\nPlaywright 的架构设计体现了现代浏览器自动化的最佳实践：\n\n1. **双进程模型**：灵活支持进程内和进程外执行\n2. **统一 API**：跨浏览器提供一致的接口\n3. **可扩展设计**：支持插件和 MCP 集成\n4. **强大的调试能力**：内置跟踪、快照和 CLI 工具\n\n---\n\n\n\n## 客户端实现\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [服务器端实现](#server-implementation), [定位器和选择器](#locators-and-selectors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/client/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/page.ts)\n- [packages/playwright-core/src/client/frame.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/frame.ts)\n- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)\n- [packages/playwright-core/src/client/elementHandle.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/elementHandle.ts)\n- [packages/playwright-core/src/client/browserContext.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/browserContext.ts)\n- [packages/playwright-core/src/client/channelOwner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/channelOwner.ts)\n \n\n# 客户端实现\n\n## 概述\n\nPlaywright 的客户端实现是库的核心组成部分，它为开发者提供了操作浏览器的编程接口。客户端层封装了与浏览器驱动程序通信的底层细节，提供了高级 API 用于页面导航、元素交互、表单填写、截图等操作。\n\nPlaywright 采用 **Channel（通道）** 架构进行客户端与服务端通信。客户端实现位于 `packages/playwright-core/src/client/` 目录下，包含了所有与浏览器交互的 TypeScript 类和接口。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[开发者代码] --> B[Client API]\n B --> C[Locator API]\n B --> D[Page API]\n B --> E[BrowserContext API]\n C --> F[ChannelOwner]\n D --> F\n E --> F\n F --> G[Playwright Driver]\n G --> H[Browser Process]\n G --> I[CDP Connection]\n H --> J[Chromium/Firefox/WebKit]\n```\n\n客户端实现采用了分层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| API 层 | Page, Frame, Locator, ElementHandle | 提供高级用户接口 |\n| 通道层 | ChannelOwner | 管理与驱动程序的通信通道 |\n| 传输层 | Playwright Driver | 处理协议编解码和消息传递 |\n\n## 核心组件\n\n### ChannelOwner 基类\n\n`ChannelOwner` 是所有客户端对象的基类，负责：\n\n- 管理与 Playwright Driver 的底层通信通道\n- 处理远程过程调用（RPC）\n- 管理对象的生命周期\n- 处理事件订阅和分发\n\n所有客户端对象（Page、Frame、BrowserContext、Locator 等）都继承自 `ChannelOwner`，共享相同的通信机制和生命周期管理模式。\n\n### Page 类\n\n`Page` 代表浏览器中的一个页面，是最常用的交互入口。主要功能包括：\n\n| 功能类别 | 方法示例 | 说明 |\n|----------|----------|------|\n| 导航 | goto, goBack, goForward, reload | 页面导航控制 |\n| 交互 | click, fill, hover, type | 用户操作模拟 |\n| 状态 | title, url, content | 获取页面信息 |\n| 截图 | screenshot, pdf | 页面内容导出 |\n| 等待 | waitForSelector, waitForLoadState | 条件等待机制 |\n\n### Frame 类\n\n`Frame` 表示页面中的一个 iframe 或主框架。Playwright 中的 Frame 实现支持：\n\n- 嵌套框架的遍历和定位\n- 框架级别的操作隔离\n- 跨框架元素交互\n\n### Locator API\n\nLocator 是 Playwright 现代化的元素定位和交互方式，相比传统的 `ElementHandle`，Locator 具有以下优势：\n\n| 特性 | ElementHandle | Locator |\n|------|---------------|---------|\n| 定位时机 | 创建时立即定位 | 操作时延迟定位 |\n| 重试机制 | 无自动重试 | 自动重试直到元素可操作 |\n| 稳定性 | 可能因 DOM 变化失效 | 每次操作重新定位 |\n| 链式调用 | 不支持 | 支持链式定位 |\n\nLocator 提供了丰富的方法链：\n\n```typescript\n// 链式定位示例\nlocator\n .frameLocator('#iframe')\n .locator('button.submit')\n .click();\n```\n\n### ElementHandle 类\n\n`ElementHandle` 代表 DOM 中的一个元素，提供直接的元素级操作：\n\n- `click()` - 点击元素\n- `fill()` - 填写表单\n- `hover()` - 鼠标悬停\n- `evaluate()` - 在元素上下文中执行 JavaScript\n\n### BrowserContext 类\n\n`BrowserContext` 表示一个独立的浏览器会话，具有以下特性：\n\n| 特性 | 说明 |\n|------|------|\n| 隔离存储 | 独立的 Cookie、LocalStorage、SessionStorage |\n| 并行执行 | 可创建多个 Context 同时运行 |\n| 权限控制 | 可精细控制地理位置、摄像头等权限 |\n| 隐私模式 | 每个 Context 相互隔离 |\n\n## 对象关系图\n\n```mermaid\ngraph LR\n A[Browser] --> B[BrowserContext]\n B --> C[Page]\n C --> D[Frame]\n D --> E[ElementHandle]\n C --> F[Locator]\n F -.-> E\n B --> G[BrowserServer]\n B --> H[Tracing]\n```\n\n核心对象关系：\n\n- **Browser** 可以包含多个独立的 **BrowserContext**\n- 每个 **BrowserContext** 可以包含多个 **Page**\n- **Page** 包含一个主 **Frame** 和可能的嵌套 **Frame**\n- **ElementHandle** 和 **Locator** 都用于定位和操作 **Frame** 中的 DOM 元素\n\n## 生命周期管理\n\n### 对象创建\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant API as Client API\n participant Channel as ChannelOwner\n participant Driver as Playwright Driver\n \n User->>API: new Page(channel)\n API->>Channel: 初始化通道\n Channel->>Driver: 创建远程对象\n Driver-->>Channel: 返回对象引用\n Channel-->>API: 返回实例\n API-->>User: Page 实例\n```\n\n### 资源释放\n\n客户端对象在以下情况下会被自动或手动释放：\n\n1. **显式关闭**：调用 `page.close()`, `context.close()`\n2. **作用域结束**：在测试框架中，测试完成后自动清理\n3. **强制关闭**：调用 `browser.close()` 关闭整个浏览器\n\n## 事件系统\n\n客户端实现了基于订阅的事件系统：\n\n| 事件类型 | 触发时机 | 使用场景 |\n|----------|----------|----------|\n| `load` | 页面加载完成 | 等待页面就绪 |\n| `domcontentloaded` | DOM 解析完成 | 快速验证 |\n| `console` | 控制台消息 | 调试和日志 |\n| `request` | 网络请求发起 | 流量监控 |\n| `response` | 网络响应接收 | 断言验证 |\n| `crash` | 页面崩溃 | 错误处理 |\n\n## 等待机制\n\nPlaywright 客户端提供了智能的等待机制来处理异步操作：\n\n### 内置等待\n\n| 等待类型 | 说明 |\n|----------|------|\n| 导航等待 | 自动等待页面加载完成 |\n| 元素等待 | 等待元素出现、可见、可点击 |\n| 函数等待 | 等待条件满足 |\n| 超时控制 | 可配置全局或单次超时 |\n\n### 自定义等待\n\n```typescript\n// 等待元素包含特定文本\nawait page.locator('div.status').waitFor({ \n hasText: 'Success' \n});\n\n// 等待函数返回 true\nawait page.waitForFunction(() => {\n return document.querySelectorAll('li').length > 10;\n});\n```\n\n## 错误处理\n\n客户端实现了完善的错误处理机制：\n\n| 错误类型 | 触发条件 | 处理建议 |\n|----------|----------|----------|\n| TimeoutError | 操作超时 | 增加超时时间或检查页面状态 |\n| TargetClosedError | 目标已关闭 | 检查对象生命周期 |\n| NotFoundError | 元素未找到 | 验证选择器或等待条件 |\n| NavigationError | 导航失败 | 检查网络或 URL |\n\n## 与 CLI 的集成\n\nPlaywright CLI (`playwright-cli`) 提供了命令行界面的浏览器自动化能力，与客户端 API 共享相同的底层实现：\n\n```bash\n# CLI 命令对应客户端 API\nplaywright-cli click e15 # => page.locator('#selector').click()\nplaywright-cli screenshot # => page.screenshot()\nplaywright-cli goto url # => page.goto(url)\n```\n\nCLI 和客户端共享相同的 Page、Frame、Locator 实现，保证了行为一致性。\n\n## 源码结构\n\n```\npackages/playwright-core/src/client/\n├── channelOwner.ts # 基础通道所有者类\n├── page.ts # 页面实现\n├── frame.ts # 框架实现\n├── locator.ts # 定位器实现\n├── elementHandle.ts # 元素句柄实现\n├── browserContext.ts # 浏览器上下文\n├── browser.ts # 浏览器实例\n└── ...\n```\n\n## 总结\n\nPlaywright 的客户端实现提供了一套完整、高层次的浏览器自动化 API。其核心设计理念包括：\n\n1. **统一通道架构**：所有客户端对象通过 ChannelOwner 与驱动程序通信\n2. **延迟定位**：Locator 机制确保元素操作的稳定性\n3. **智能等待**：内置自动等待，减少 flaky tests\n4. **丰富的事件系统**：支持各种页面状态和行为的监控\n5. **完善的错误处理**：清晰的错误类型和合理的默认行为\n\n这套客户端架构使得开发者能够以声明式的方式编写浏览器自动化测试和脚本，同时保证了跨浏览器的一致性。\n\n---\n\n\n\n## 服务器端实现\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [客户端实现](#client-implementation), [浏览器支持](#browser-support)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/server/browser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browser.ts)\n- [packages/playwright-core/src/server/browserContext.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browserContext.ts)\n- [packages/playwright-core/src/server/page.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/page.ts)\n- [packages/playwright-core/src/server/dispatchers/dispatcher.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/dispatchers/dispatcher.ts)\n- [packages/playwright-core/src/server/network.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/network.ts)\n- [packages/playwright-core/src/server/index.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/index.ts)\n \n\n# 服务器端实现\n\n## 概述\n\nPlaywright 的服务器端实现是框架的核心架构层，负责在 Node.js 环境中管理与浏览器实例的通信。该层封装了浏览器启动、页面操作、网络拦截、上下文隔离等底层功能，为上层 API 提供统一的接口抽象。\n\n服务器端实现的主要职责包括：\n\n- 管理浏览器进程的生命周期\n- 处理跨进程通信协议\n- 协调浏览器上下文和页面状态\n- 处理网络请求和响应\n- 分发器（Dispatcher）模式的消息路由\n\n资料来源：[packages/playwright-core/src/server/index.ts:1-20]()\n\n## 架构设计\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n A[playwright-core] --> B[Server Index]\n B --> C[Browser]\n B --> D[BrowserContext]\n B --> E[Page]\n B --> F[Network]\n C --> D\n D --> E\n E --> F\n B --> G[Dispatcher]\n G --> C\n G --> D\n G --> E\n G --> F\n```\n\n### 层次结构\n\nPlaywright 服务器端采用分层架构设计，从底层到高层依次为：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 传输层 | Protocol 协议 | 定义客户端与服务端的消息格式 |\n| 路由层 | Dispatcher | 消息分发与路由 |\n| 业务层 | Browser/Context/Page | 核心业务逻辑 |\n| 实现层 | Browser API | 与底层浏览器通信 |\n\n资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts:1-30]()\n\n## Browser 服务器实现\n\n### Browser 类职责\n\nBrowser 类是服务器端的核心入口，负责以下功能：\n\n- 浏览器进程启动与关闭\n- 浏览器类型检测（Chromium/Firefox/WebKit）\n- 版本信息管理\n- 发射器（Launch Server）管理\n\n### 主要方法\n\n```typescript\nclass Browser {\n // 启动浏览器\n async launch(options: LaunchOptions): Promise\n \n // 连接已存在的浏览器\n async connect(wsEndpoint: string): Promise\n \n // 创建新上下文\n async newContext(options?: ContextOptions): Promise\n \n // 关闭浏览器\n async close(): Promise\n \n // 获取所有上下文\n contexts(): BrowserContext[]\n}\n```\n\n资料来源：[packages/playwright-core/src/server/browser.ts:30-100]()\n\n### 浏览器上下文管理\n\n```mermaid\ngraph LR\n A[Browser] -->|创建| B[BrowserContext 1]\n A -->|创建| C[BrowserContext 2]\n A -->|创建| D[BrowserContext N]\n B --> E[Page 1]\n B --> F[Page 2]\n C --> G[Page 3]\n D --> H[Page 4]\n```\n\n## BrowserContext 服务器实现\n\nBrowserContext 代表一个独立的浏览器会话，每个上下文拥有独立的存储空间、Cookie、缓存等。\n\n### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 隔离存储 | 独立的 localStorage、sessionStorage |\n| Cookie 隔离 | 每个上下文维护独立的 Cookie 存储 |\n| 权限管理 | 可独立控制地理位置、摄像头等权限 |\n| 代理配置 | 支持为单个上下文配置代理服务器 |\n\n### 主要方法\n\n```typescript\nclass BrowserContext {\n // 创建新页面\n async newPage(): Promise\n \n // 添加 cookies\n async addCookies(cookies: Cookie[]): Promise\n \n // 获取 cookies\n async cookies(urls?: string[]): Promise\n \n // 清除所有 cookies\n async clearCookies(): Promise\n \n // 授权权限\n async grantPermissions(permissions: string[]): Promise\n \n // 截图\n async screenshot(options?: ScreenshotOptions): Promise\n \n // 关闭上下文\n async close(): Promise\n}\n```\n\n资料来源：[packages/playwright-core/src/server/browserContext.ts:50-150]()\n\n## Page 服务器实现\n\nPage 类代表浏览器中的一个标签页或框架，是与网页内容交互的主要接口。\n\n### 元素定位与交互\n\n```typescript\nclass Page {\n // 元素定位\n locator(selector: string): Locator\n getByRole(role: AriaRole, options?: GetByRoleOptions): Locator\n getByText(text: string, options?: GetByTextOptions): Locator\n getByTestId(testId: string): Locator\n \n // 交互操作\n async click(selector: string, options?: ClickOptions): Promise\n async fill(selector: string, value: string): Promise\n async type(selector: string, text: string, options?: TypeOptions): Promise\n async hover(selector: string): Promise\n async dragAndDrop(source: string, target: string): Promise\n}\n```\n\n### 导航操作\n\n```typescript\nclass Page {\n // 页面导航\n async goto(url: string, options?: GotoOptions): Promise\n async goBack(options?: NavigationOptions): Promise\n async goForward(options?: NavigationOptions): Promise\n async reload(options?: NavigationOptions): Promise\n \n // 等待导航完成\n async waitForNavigation(options?: WaitForNavigationOptions): Promise\n \n // 事件监听\n async waitForLoadState(state: LoadState): Promise\n waitForURL(url: string | RegExp): Promise\n}\n```\n\n资料来源：[packages/playwright-core/src/server/page.ts:100-250]()\n\n## Dispatcher 分发器\n\nDispatcher 是 Playwright 服务器端的消息路由核心，采用发布-订阅模式处理客户端请求。\n\n### 工作原理\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[Protocol Handler]\n B --> C[Dispatcher]\n C --> D{路由判断}\n D -->|Browser| E[BrowserDispatcher]\n D -->|Context| F[BrowserContextDispatcher]\n D -->|Page| G[PageDispatcher]\n D -->|Network| H[NetworkDispatcher]\n E --> I[执行结果]\n F --> I\n G --> I\n H --> I\n```\n\n### 消息流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Protocol as Protocol Handler\n participant Dispatcher as Dispatcher\n participant Handler as 业务处理器\n \n Client->>Protocol: 发送命令\n Protocol->>Dispatcher: 路由消息\n Dispatcher->>Handler: 分发请求\n Handler->>Handler: 处理业务逻辑\n Handler-->>Dispatcher: 返回结果\n Dispatcher-->>Protocol: 格式化响应\n Protocol-->>Client: 返回执行结果\n```\n\n### Dispatcher 基类\n\n```typescript\nclass Dispatcher {\n // 构造函数接收根对象和唯一标识\n constructor(scope: object, uid: number)\n \n // 内部对象引用\n protected _scope: object\n protected _uid: number\n \n // 回调方法\n protected _dispatchEvent(method: string, params: any): void\n protected _writeObjectToLog(logName: string, obj: any): void\n}\n```\n\n资料来源：[packages/playwright-core/src/server/dispatchers/dispatcher.ts:30-80]()\n\n## Network 网络管理\n\nNetwork 模块负责处理页面的网络请求和响应，支持请求拦截、修改、模拟等功能。\n\n### 网络拦截\n\n```typescript\nclass Route {\n // 继续请求（可选修改）\n async continue(options?: ContinueRequestOptions): Promise\n \n // 完成响应\n async fulfill(response: Partial): Promise\n \n // 中止请求\n async abort(errorCode?: string): Promise\n}\n\nclass Request {\n // 获取请求信息\n url(): string\n method(): string\n headers(): Record\n postData(): string | null\n \n // 响应对象\n response(): Response | null\n}\n```\n\n### 路由规则配置\n\n| 方法 | 说明 |\n|------|------|\n| `route(url, handler)` | 为匹配 URL 的请求设置处理函数 |\n| `unroute(url, handler?)` | 移除路由规则 |\n| `routeList()` | 列出所有活动路由 |\n\n资料来源：[packages/playwright-core/src/server/network.ts:50-120]()\n\n## 服务器启动流程\n\n```mermaid\ngraph TD\n A[导入 Server Index] --> B[初始化传输层]\n B --> C[加载浏览器驱动]\n C --> D{检查浏览器安装}\n D -->|未安装| E[触发自动安装]\n D -->|已安装| F[启动浏览器进程]\n F --> G[建立 WebSocket 连接]\n G --> H[初始化 Dispatcher]\n H --> I[导出公共 API]\n I --> J[服务器就绪]\n```\n\n## 关键配置选项\n\n### 浏览器启动配置\n\n| 选项 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `headless` | boolean | 是否无头模式运行 | true |\n| `args` | string[] | 浏览器启动参数 | [] |\n| `proxy` | ProxyOptions | 代理服务器配置 | undefined |\n| `viewport` | Viewport | 视口大小 | 800x600 |\n| `userAgent` | string | 用户代理字符串 | 浏览器默认 |\n| `timeout` | number | 操作超时时间(毫秒) | 30000 |\n\n### 上下文配置\n\n| 选项 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `storageState` | string/StorageState | 预加载存储状态 | undefined |\n| `permissions` | string[] | 默认授权的权限 | [] |\n| `geolocation` | Geolocation | 地理位置模拟 | undefined |\n| `ignoreHTTPSErrors` | boolean | 忽略 HTTPS 错误 | false |\n| `baseURL` | string | 相对 URL 的基础地址 | undefined |\n\n资料来源：[packages/playwright-core/src/server/browserContext.ts:200-280]()\n\n## 与客户端的通信\n\nPlaywright 服务器端通过 CDP（Chrome DevTools Protocol）协议与浏览器通信，同时通过自定义协议与 Node.js 客户端交互。\n\n```mermaid\ngraph LR\n A[Node.js 客户端] <-->|Playwright Protocol| B[Server]\n B <-->|CDP Protocol| C[Chromium]\n B <-->|CDP Protocol| D[Firefox]\n B <-->|WebKit Protocol| E[WebKit]\n```\n\n## 扩展与定制\n\n### 自定义浏览器驱动\n\n开发者可以通过继承 Browser 类来支持自定义浏览器：\n\n```typescript\nclass CustomBrowser extends Browser {\n protected async _launchServer(): Promise {\n // 自定义启动逻辑\n }\n}\n```\n\n### 添加新的协议处理器\n\n通过扩展 Dispatcher 基类，可以添加新的协议处理能力：\n\n```typescript\nclass CustomDispatcher extends Dispatcher {\n constructor(scope: object, uid: number) {\n super(scope, uid);\n }\n \n // 实现自定义方法\n async customMethod(params: any): Promise {\n // 处理逻辑\n }\n}\n```\n\n## 最佳实践\n\n### 资源管理\n\n- 及时关闭不再使用的 Page、BrowserContext\n- 使用 `async/await` 确保资源释放\n- 设置合理的超时时间避免资源泄漏\n\n### 错误处理\n\n```typescript\ntry {\n await page.goto('https://example.com', { timeout: 10000 });\n} catch (error) {\n if (error instanceof TimeoutError) {\n // 处理超时\n } else if (error instanceof net.Error) {\n // 处理网络错误\n }\n}\n```\n\n### 并发控制\n\n| 场景 | 推荐做法 |\n|------|----------|\n| 多页面并发 | 使用多个 BrowserContext |\n| 批量操作 | 控制并发数量避免资源耗尽 |\n| 资源密集型 | 考虑使用 `browser.close()` 释放资源 |\n\n## 相关模块索引\n\n| 模块路径 | 职责 |\n|----------|------|\n| `src/server/browser.ts` | 浏览器进程管理 |\n| `src/server/browserContext.ts` | 会话上下文管理 |\n| `src/server/page.ts` | 页面操作与交互 |\n| `src/server/dispatchers/dispatcher.ts` | 消息路由分发 |\n| `src/server/network.ts` | 网络请求拦截 |\n| `src/server/index.ts` | 服务端导出入口 |\n\n---\n\n本页面持续更新中，如有问题请提交 Issue 或 Pull Request。\n\n---\n\n\n\n## 浏览器支持\n\n### 相关页面\n\n相关主题：[架构概览](#architecture-overview), [服务器端实现](#server-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/server/chromium/crBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/chromium/crBrowser.ts)\n- [packages/playwright-core/src/server/firefox/ffBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/firefox/ffBrowser.ts)\n- [packages/playwright-core/src/server/webkit/wkBrowser.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/webkit/wkBrowser.ts)\n- [packages/playwright-core/src/server/browserType.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/browserType.ts)\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n- [packages/trace-viewer/src/ui/browserFrame.tsx](https://github.com/microsoft/playwright/blob/main/packages/trace-viewer/src/ui/browserFrame.tsx)\n- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)\n- [packages/playwright-core/src/server/codegen/csharp.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/codegen/csharp.ts)\n \n\n# 浏览器支持\n\nPlaywright 是一个跨浏览器自动化测试框架，支持三大主流浏览器引擎：Chromium、Firefox 和 WebKit。每个浏览器都通过独立的实现模块进行抽象和管理，使得上层 API 能够以统一的方式与不同浏览器进行交互。\n\n## 支持的浏览器类型\n\nPlaywright 原生支持以下三种浏览器：\n\n| 浏览器 | 渲染引擎 | 协议实现 | 源码目录 |\n|--------|----------|----------|----------|\n| Chromium | Blink/V8 | Chrome DevTools Protocol (CDP) | `packages/playwright-core/src/server/chromium/` |\n| Firefox | Gecko/SpiderMonkey | Firefox DevTools Protocol (FDP) | `packages/playwright-core/src/server/firefox/` |\n| WebKit | WebKit/JavaScriptCore | Apple WebKit Protocol (WKP) | `packages/playwright-core/src/server/webkit/` |\n\n资料来源：[packages/playwright-core/src/server/browserType.ts]()\n\n## 浏览器启动流程\n\nPlaywright 的浏览器启动遵循统一的工厂模式，通过 `browserType.ts` 中的 `launch()` 方法创建浏览器实例。\n\n```mermaid\ngraph TD\n A[launchBrowser] --> B{浏览器类型}\n B -->|Chromium| C[createChromiumBrowser]\n B -->|Firefox| D[createFirefoxBrowser]\n B -->|WebKit| E[createWebKitBrowser]\n C --> F[连接 CDP 端口]\n D --> G[启动 Juggler 进程]\n E --> H[连接 WebKit 调试器]\n F --> I[返回 Browser 实例]\n G --> I\n H --> I\n```\n\n### 启动参数配置\n\n`launch()` 方法支持丰富的配置选项：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `headless` | boolean | 是否以无头模式运行，默认 `true` |\n| `channel` | string | 浏览器渠道，如 `chrome`, `chrome-beta`, `msedge` |\n| `args` | string[] | 传递给浏览器的额外命令行参数 |\n| `proxy` | object | 代理服务器配置 |\n| `downloadPath` | string | 下载文件保存路径 |\n| `viewport` | object | 视口尺寸配置 |\n| `userAgent` | string | 自定义 User-Agent |\n| `slowMo` | number | 操作延迟（毫秒），用于调试 |\n\n资料来源：[packages/playwright-core/src/server/browserType.ts]()\n\n## 浏览器会话管理\n\n### CLI 会话管理\n\nPlaywright CLI (`playwright-cli`) 提供了完整的浏览器会话管理能力：\n\n```bash\n# 创建新的命名会话\nplaywright-cli -s=mysession open https://example.com\n\n# 使用持久化配置文件\nplaywright-cli -s=mysession open https://example.com --persistent\n\n# 删除会话数据\nplaywright-cli -s=mysession delete-data\n\n# 关闭所有浏览器\nplaywright-cli close-all\n\n# 强制终止所有浏览器进程\nplaywright-cli kill-all\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md]()\n\n### 会话状态持久化\n\n浏览器状态可以通过以下方式保存和恢复：\n\n| 存储类型 | 命令 | 说明 |\n|----------|------|------|\n| 完整状态 | `state-save`, `state-load` | 保存/恢复 cookies、localStorage、sessionStorage |\n| Cookies | `cookie-list`, `cookie-set`, `cookie-delete` | 独立管理 cookies |\n| LocalStorage | `localstorage-list`, `localstorage-set` | 键值对存储 |\n| SessionStorage | `sessionstorage-list`, `sessionstorage-set` | 会话级存储 |\n\n```bash\n# 保存当前状态\nplaywright-cli state-save auth.json\n\n# 恢复状态\nplaywright-cli state-load auth.json\n```\n\n## 浏览器帧组件\n\nTrace Viewer 使用 `browserFrame.tsx` 组件渲染浏览器外观模拟，该组件展示地址栏、菜单栏等 UI 元素：\n\n```tsx\n\n {url || 'about:blank'}\n {url && }\n
\n```\n\n资料来源：[packages/trace-viewer/src/ui/browserFrame.tsx]()\n\n## 网络路由与拦截\n\nPlaywright 支持对网络请求进行拦截和修改：\n\n```bash\n# 拦截特定 URL 并返回自定义状态\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 使用自定义响应体\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\n```\n\n## 元素定位与交互\n\n### 角色定位器\n\nPlaywright 内置了基于 ARIA 角色的定位器支持，通过 `roleUtils.ts` 实现：\n\n| HTML 元素 | 默认 ARIA 角色 |\n|-----------|---------------|\n| `BUTTON` | button |\n| `A` | link |\n| `INPUT[type=\"search\"]` | searchbox |\n| `INPUT[type=\"email\"]` | textbox |\n| `SELECT` | listbox |\n| `DIALOG` | dialog |\n| `FORM` | form (仅当有显式可访问名称时) |\n| `IMG[alt=\"\"]` | presentation |\n| `IMG[alt!=\"\"]` | img |\n| `H1-H6` | heading |\n| `HEADER` | banner |\n| `FOOTER` | contentinfo |\n\n```typescript\n'INPUT': (e: Element) => {\n const type = (e as HTMLInputElement).type.toLowerCase();\n if (type === 'search')\n return e.hasAttribute('list') ? 'combobox' : 'searchbox';\n if (['email', 'tel', 'url'].includes(type))\n return 'textbox';\n}\n```\n\n资料来源：[packages/injected/src/roleUtils.ts]()\n\n### 元素交互命令\n\nPlaywright CLI 支持多种元素定位方式：\n\n```bash\n# 使用快照引用\nplaywright-cli click e15\n\n# CSS 选择器\nplaywright-cli click \"#main > button.submit\"\n\n# 角色定位器\nplaywright-cli click \"getByRole('button', { name: 'Submit' })\"\n\n# 测试 ID\nplaywright-cli click \"getByTestId('submit-button')\"\n```\n\n## 代码生成中的浏览器支持\n\n代码生成模块针对不同浏览器生成优化代码。以 C# 为例：\n\n```csharp\n// 检测是否为新页面操作\nif (action.name === 'openPage' || action.name === 'closePage')\n return '';\n\n// 生成页面变量\nvar page = await context.NewPageAsync();\n\n// 根据 URL 导航\nif (action.url)\n await page.GotoAsync(action.url);\n\n// 处理对话框事件\nvoid page_Dialog_EventHandler(object sender, IDialog dialog)\n{\n dialog.DismissAsync();\n}\n```\n\n资料来源：[packages/playwright-core/src/server/codegen/csharp.ts]()\n\n## Trace 与浏览器状态\n\nTrace Viewer 能够在不打开浏览器的情况下查看浏览器状态快照：\n\n```bash\n# 打开 trace 文件\nnpx playwright trace open test-results/my-test/trace.zip\n\n# 查看特定操作后的快照\nnpx playwright trace snapshot 12\n\n# 获取 DOM 内容\nnpx playwright trace snapshot 12 -- eval \"document.body.outerHTML\"\n```\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n### Trace 元数据展示\n\nTrace Viewer 通过 `MetadataView` 组件展示浏览器元数据：\n\n| 元数据字段 | 说明 |\n|-----------|------|\n| playwrightVersion | Playwright 版本 |\n| userAgent | 用户代理字符串 |\n| baseURL | 基础 URL 配置 |\n| viewport | 视口尺寸 (width × height) |\n| isMobile | 是否移动设备模拟 |\n| deviceScaleFactor | 设备像素比 |\n\n资料来源：[packages/trace-viewer/src/ui/metadataView.tsx]()\n\n## 浏览器环境变量\n\n| 环境变量 | 作用 |\n|----------|------|\n| `PLAYWRIGHT_CLI_SESSION` | 设置默认浏览器会话名称 |\n| `PLAYWRIGHT_HTML_OPEN` | 控制 HTML 报告打开行为 |\n| `PLAYWRIGHT_BROWSERS_PATH` | 浏览器可执行文件存储路径 |\n\n## 最佳实践\n\n### 会话命名规范\n\n```bash\n# 推荐：清晰的命名\nplaywright-cli -s=github-auth open https://github.com\nplaywright-cli -s=docs-scrape open https://docs.example.com\n\n# 避免：通用命名\nplaywright-cli -s=s1 open https://github.com\n```\n\n### 清理策略\n\n| 场景 | 建议操作 |\n|------|----------|\n| 正常完成 | 使用 `close` 优雅关闭 |\n| 异常退出 | 使用 `kill-all` 强制终止 |\n| 磁盘空间不足 | 使用 `delete-data` 清理旧会话 |\n\n### 无头模式与有头模式\n\n```bash\n# 无头模式（默认）\nplaywright-cli open https://example.com\n\n# 有头模式（可见浏览器窗口）\nplaywright-cli open https://example.com --headed\n```\n\n## 架构总结\n\nPlaywright 的浏览器支持层采用适配器模式设计：\n\n```mermaid\ngraph LR\n A[用户代码] --> B[Playwright API]\n B --> C[BrowserType 工厂]\n C --> D[ChromiumBrowser]\n C --> E[FirefoxBrowser]\n C --> E --> F[Juggler 桥接]\n C --> G[WebKitBrowser]\n D --> H[CDP 连接]\n G --> I[WKP 连接]\n```\n\n这种设计使得：\n- 新增浏览器支持只需实现新的适配器\n- 上层 API 保持稳定\n- 协议差异被隔离在各自的实现模块中\n\n---\n\n\n\n## 测试框架\n\n### 相关页面\n\n相关主题：[断言系统](#assertions), [定位器和选择器](#locators-and-selectors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright/src/common/config.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/config.ts)\n- [packages/playwright/src/common/fixtures.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/fixtures.ts)\n- [packages/playwright/src/common/test.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/test.ts)\n- [packages/playwright/src/runner/testRunner.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/testRunner.ts)\n- [packages/playwright/src/runner/dispatcher.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/runner/dispatcher.ts)\n- [packages/playwright/src/worker/workerMain.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/worker/workerMain.ts)\n- [packages/playwright/src/common/poolBuilder.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/common/poolBuilder.ts)\n \n\n# 测试框架\n\nPlaywright 测试框架是微软开发的一个端到端测试框架，提供了用于编写、管理和执行浏览器自动化测试的完整工具链。该框架支持多浏览器（Chromium、Firefox、WebKit）、多语言（JavaScript/TypeScript、Python、Java、.NET）以及丰富的断言和定位器 API。\n\n## 架构概述\n\nPlaywright 测试框架采用分层架构设计，核心组件包括配置管理、Fixtures 系统、测试运行器和 Worker 进程池。\n\n```mermaid\ngraph TD\n A[Playwright Test CLI] --> B[Test Runner]\n B --> C[Configuration]\n B --> D[Dispatcher]\n D --> E[Worker Pool]\n E --> F[Worker Process 1]\n E --> G[Worker Process 2]\n E --> H[Worker Process N]\n F --> I[Browser Context]\n G --> J[Browser Context]\n I --> K[Test Fixture]\n J --> L[Test Fixture]\n```\n\n## 核心组件\n\n### 配置系统\n\n配置系统负责管理测试运行的全局参数，包括测试目录、测试超时、并发配置等。\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| testDir | 测试文件目录 | 当前工作目录 |\n| timeout | 单个测试超时时间 | 30000ms |\n| retries | 失败测试重试次数 | 0 |\n| workers | 并发 Worker 数量 | CPU 核心数 |\n| reporter | 测试报告格式 | list |\n\n配置通过 `playwright.config.ts` 文件定义，框架在启动时加载并验证配置的有效性。资料来源：[packages/playwright/src/common/config.ts]()\n\n### Fixtures 系统\n\nFixtures 是 Playwright 测试框架的核心特性之一，用于在测试运行时提供上下文和资源管理。Fixtures 可以是浏览器上下文、页面对象、认证状态或任何测试所需的数据。\n\n```typescript\n// Fixtures 定义示例结构\nexport interface TestFixtures {\n page: Page;\n context: BrowserContext;\n request: APIRequestContext;\n}\n```\n\nFixtures 支持以下特性：\n\n- **自动生命周期管理**：自动处理资源的创建和销毁\n- **依赖注入**：Fixtures 可以依赖其他 Fixtures\n- **参数化支持**：支持动态参数化配置\n- **作用域控制**：可设置 Function Scope（Function、Test、Worker、Project）\n\n资料来源：[packages/playwright/src/common/fixtures.ts]()\n\n### 测试定义\n\n测试通过 `test` 函数定义，支持分组、标注和元数据管理。\n\n```typescript\ntest.describe('测试分组', () => {\n test.beforeEach(async ({ page }) => {\n // 前置条件\n });\n \n test('示例测试', async ({ page }) => {\n await page.goto('https://example.com');\n // 测试步骤\n });\n \n test.afterEach(async ({ page }) => {\n // 清理工作\n });\n});\n```\n\n资料来源：[packages/playwright/src/common/test.ts]()\n\n## 运行机制\n\n### 测试运行器\n\n测试运行器（Test Runner）是框架的核心调度引擎，负责解析配置、加载测试文件并协调整个测试执行流程。\n\n```mermaid\ngraph LR\n A[Load Config] --> B[Discover Tests]\n B --> C[Build Worker Pool]\n C --> D[Dispatch Tests]\n D --> E[Execute in Worker]\n E --> F[Report Results]\n F --> G[Cleanup]\n```\n\n运行器的主要职责包括：\n\n1. 解析命令行参数和配置文件\n2. 发现并加载测试文件\n3. 构建 Worker 进程池\n4. 分发测试任务到 Worker\n5. 收集并汇总测试结果\n\n资料来源：[packages/playwright/src/runner/testRunner.ts]()\n\n### 分发器\n\n分发器（Dispatcher）负责将测试任务分配给可用的 Worker 进程，支持智能负载均衡和失败重试机制。\n\n| 特性 | 说明 |\n|------|------|\n| 动态分配 | 根据 Worker 负载动态分配测试 |\n| 失败重试 | 支持按测试或全局配置重试 |\n| 超时控制 | 监控测试执行时间 |\n| 进度追踪 | 实时汇报测试执行进度 |\n\n分发器采用基于队列的模型，新测试被发现后立即加入执行队列。每个 Worker 进程独立运行，可以并行执行多个测试。\n\n资料来源：[packages/playwright/src/runner/dispatcher.ts]()\n\n### Worker 进程\n\nWorker 进程是测试代码的实际执行环境，每个 Worker 拥有独立的浏览器实例和上下文池。\n\n```mermaid\ngraph TD\n A[Worker Main] --> B[Load Fixtures]\n B --> C[Create Browser Context]\n C --> D[Run Test]\n D --> E[Assert Results]\n E --> F{Cleanup}\n F --> G[Destroy Context]\n G --> H[Ready for Next Test]\n```\n\nWorker 的生命周期管理包括：\n\n- 初始化阶段：加载必要的 Fixtures 和依赖\n- 执行阶段：运行单个测试用例\n- 清理阶段：销毁浏览器上下文，释放资源\n\n资料来源：[packages/playwright/src/worker/workerMain.ts]()\n\n### 进程池构建器\n\n进程池构建器（Pool Builder）负责创建和管理 Worker 进程池，优化资源利用率。\n\n```mermaid\ngraph TD\n A[Pool Request] --> B{Check Pool}\n B -->|有可用 Worker| C[Reuse Worker]\n B -->|无可用 Worker| D[Create Worker]\n D --> E[Initialize]\n C --> F[Execute Test]\n E --> F\n F --> G[Return to Pool]\n```\n\n进程池支持以下配置策略：\n\n| 策略 | 说明 |\n|------|------|\n| 并发数量 | 最大同时运行的 Worker 数 |\n| 空闲超时 | 空闲 Worker 的存活时间 |\n| 启动延迟 | 预热 Worker 的延迟配置 |\n\n资料来源：[packages/playwright/src/common/poolBuilder.ts]()\n\n## 追踪与调试\n\n### 追踪查看器\n\nPlaywright 提供追踪查看器（Trace Viewer）用于回放和调试测试执行过程。追踪文件是包含快照、网络请求、控制台日志的 ZIP 包。\n\n```bash\n# 打开追踪文件\nnpx playwright trace open \n\n# 查看特定 action 的详细信息\nnpx playwright trace action \n\n# 获取 DOM 快照\nnpx playwright trace snapshot \n```\n\n追踪查看器支持以下功能：\n\n- 时间线视图：可视化测试执行的时间轴\n- 快照回放：查看每一步操作后的页面状态\n- 网络监控：分析请求和响应详情\n- 控制台日志：捕获 JavaScript 控制台输出\n- 错误追踪：定位测试失败的具体原因\n\n资料来源：[packages/trace-viewer/src/ui/workbenchLoader.tsx]()\n\n### CLI 工具\n\nplaywright-cli 提供命令行界面用于调试和探索性测试。\n\n| 命令 | 功能 |\n|------|------|\n| `goto` | 导航到指定 URL |\n| `click` | 点击页面元素 |\n| `snapshot` | 获取页面快照 |\n| `screenshot` | 截取页面截图 |\n| `pdf` | 生成 PDF 文档 |\n| `console` | 查看控制台输出 |\n| `requests` | 查看网络请求 |\n| `eval` | 执行 JavaScript 代码 |\n\n```bash\n# 启动调试会话\nplaywright-cli open https://example.com\n\n# 获取带引用标记的快照\nplaywright-cli snapshot\n\n# 使用引用标记交互\nplaywright-cli click e15\n```\n\n## 报告生成\n\n### HTML 报告器\n\nPlaywright 生成详细的 HTML 测试报告，包含测试结果统计、失败原因分析、截图对比等信息。\n\n报告界面主要组件：\n\n| 组件 | 说明 |\n|------|------|\n| 测试摘要 | 通过/失败/跳过统计 |\n| 测试列表 | 按项目分组的测试项 |\n| 测试详情 | 单个测试的执行信息 |\n| 元数据视图 | 测试环境配置信息 |\n\n资料来源：[packages/html-reporter/src/testCaseView.tsx]()\n\n报告支持以下数据展示：\n\n- 测试执行时长（毫秒转换显示）\n- 测试标签和项目分组\n- 重试次数和历史记录\n- 注释和标注信息\n- 追踪链接（跳转到 Trace Viewer）\n\n## 浏览器支持\n\nPlaywright 支持三大主流浏览器引擎：\n\n| 浏览器 | 引擎 | 平台支持 |\n|--------|------|----------|\n| Chromium | Blink | Windows、macOS、Linux |\n| Firefox | Gecko | Windows、macOS、Linux |\n| WebKit | WebKit | Windows、macOS、Linux |\n\n每个浏览器通过独立的项目（Project）配置，支持不同的视口大小、用户代理、设备模拟等参数。\n\n## 相关资源\n\n- 官方文档：https://playwright.dev\n- 追踪查看器：https://trace.playwright.dev\n- 测试配置参考：Playwright 配置文件规范\n- Fixtures API：自定义 Fixtures 开发指南\n\n---\n\n\n\n## 定位器和选择器\n\n### 相关页面\n\n相关主题：[客户端实现](#client-implementation), [测试框架](#test-framework)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)\n- [packages/injected/src/selectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEngine.ts)\n- [packages/injected/src/roleSelectorEngine.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleSelectorEngine.ts)\n- [packages/injected/src/selectorGenerator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorGenerator.ts)\n- [packages/injected/src/selectorEvaluator.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/selectorEvaluator.ts)\n- [packages/isomorphic/locatorUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/locatorUtils.ts)\n \n\n# 定位器和选择器\n\n## 概述\n\nPlaywright 中的**定位器（Locator）**和**选择器（Selector）**是自动化浏览器交互的核心组件。定位器是 Playwright 推荐的元素定位方式，提供了比传统 `Page.locator()` API 更加健壮的元素查找机制。选择器则是用于匹配 DOM 元素的字符串表达式，支持多种定位策略。\n\n定位器与选择器的关系可以通过以下架构图说明：\n\n```mermaid\ngraph TD\n A[用户代码] --> B[Locator API]\n B --> C{查找策略}\n C --> D[CSS 选择器]\n C --> E[Role 选择器]\n C --> F[文本选择器]\n C --> G[测试ID选择器]\n C --> H[XPath 选择器]\n D --> I[selectorEngine.ts]\n E --> J[roleSelectorEngine.ts]\n F --> I\n G --> I\n H --> I\n I --> K[selectorEvaluator.ts]\n K --> L[DOM 元素]\n \n style A fill:#e1f5ff\n style L fill:#c8e6c9\n```\n\n## 核心概念\n\n### 定位器（Locator）\n\n定位器是 Playwright 用来定位页面元素的异步可重用对象。与传统的 `querySelector` 不同，定位器具有以下特点：\n\n| 特性 | 说明 |\n|------|------|\n| **自动重试** | 元素未找到时自动等待并重试 |\n| **可复用** | 定位器对象可以多次使用 |\n| **惰性执行** | 定位器在交互时才执行查询 |\n| **可组合** | 支持链式调用构建复杂定位器 |\n\n定位器 API 提供了丰富的交互方法，包括 `click()`、`fill()`、`hover()`、`getByRole()` 等。\n\n### 选择器（Selector）\n\n选择器是用于匹配 DOM 元素的字符串表达式。Playwright 支持多种选择器类型：\n\n| 类型 | 语法示例 | 说明 |\n|------|----------|------|\n| CSS | `#id`, `.class`, `div > span` | 标准 CSS 选择器 |\n| Role | `getByRole('button')` | ARIA 角色选择器 |\n| 文本 | `getByText('Submit')` | 按文本内容定位 |\n| 测试ID | `getByTestId('submit')` | data-testid 属性 |\n| XPath | `xpath=//button` | XPath 表达式 |\n| 混合 | `role=button[name='Login']` | 属性组合 |\n\n## 源码架构\n\n### 模块职责划分\n\n```mermaid\ngraph LR\n A[packages/playwright-core
客户端封装] --> B[packages/isomorphic
跨平台工具]\n B --> C[packages/injected
注入脚本]\n \n A1[locator.ts] --> B1[locatorUtils.ts]\n C1[selectorEngine.ts] --> C4[selectorEvaluator.ts]\n C2[roleSelectorEngine.ts] --> C4\n C3[selectorGenerator.ts] --> C4\n \n style A fill:#fff3e0\n style B fill:#e3f2fd\n style C fill:#f3e5f5\n```\n\n### 关键源文件\n\n| 文件路径 | 职责 |\n|----------|------|\n| `client/locator.ts` | 定义Locator类，提供元素交互API |\n| `injected/selectorEngine.ts` | 实现基础选择器引擎 |\n| `injected/roleSelectorEngine.ts` | 实现ARIA角色选择器引擎 |\n| `injected/selectorGenerator.ts` | 自动生成健壮的选择器 |\n| `injected/selectorEvaluator.ts` | 评估和验证选择器匹配 |\n| `isomorphic/locatorUtils.ts` | 提供跨平台的定位器工具函数 |\n\n## 选择器引擎\n\n### 选择器引擎架构\n\n选择器引擎是 Playwright 解析和执行选择器的核心组件，采用插件化架构支持多种选择器类型。\n\n```mermaid\ngraph TD\n A[选择器字符串] --> B[解析器]\n B --> C{选择器类型}\n C -->|CSS| D[CSS Engine]\n C -->|role| E[Role Engine]\n C -->|text| F[Text Engine]\n C -->|test-id| G[TestId Engine]\n C -->|xpath| H[XPath Engine]\n \n D --> I[querySelector]\n E --> J[roleSelectorEngine.ts]\n F --> K[文本匹配]\n G --> L[data-testid]\n H --> M[XPath 评估]\n \n I --> N[selectorEvaluator.ts]\n J --> N\n K --> N\n L --> N\n M --> N\n \n N --> O[匹配结果]\n```\n\n### 角色选择器引擎\n\n角色选择器（Role Selector）是 Playwright 推荐的元素定位方式，基于 ARIA 规范实现。\n\n```mermaid\ngraph LR\n A[getByRole
'button'] --> B[roleSelectorEngine.ts]\n B --> C[ARIA 属性检查]\n C --> D{匹配类型}\n D -->|implicit| E[通过角色推断]\n D -->|explicit| F[通过 aria-* 属性]\n E --> G[返回元素]\n F --> G\n \n style A fill:#e1f5ff\n style G fill:#c8e6c9\n```\n\n角色选择器支持的选项参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | string \\| RegExp | 角色关联的 accessible name |\n| `level` | number | ARIA level（如 heading 角色） |\n| `checked` | boolean | checkbox/radio 的选中状态 |\n| `pressed` | boolean | button 的按下状态 |\n| `expanded` | boolean | 展开/折叠状态 |\n| `selected` | boolean | option 的选中状态 |\n\n## Locator API\n\n### 创建定位器\n\n定位器可以通过多种方式创建：\n\n```typescript\n// 通过 CSS 选择器\npage.locator('css=.submit-button');\n\n// 通过角色\npage.locator('role=button[name=\"Submit\"]');\n\n// 通过文本内容\npage.locator('text=Click here');\n\n// 通过测试ID\npage.locator('test-id=submit-btn');\n\n// 链式定位器\npage.locator('form').locator('button[type=\"submit\"]');\n```\n\n### 交互方法\n\n| 方法 | 说明 | 示例 |\n|------|------|------|\n| `click()` | 点击元素 | `locator.click()` |\n| `dblclick()` | 双击元素 | `locator.dblclick()` |\n| `fill()` | 填充输入框 | `locator.fill('text')` |\n| `hover()` | 鼠标悬停 | `locator.hover()` |\n| `type()` | 逐字符输入 | `locator.type('hello')` |\n| `press()` | 按下按键 | `locator.press('Enter')` |\n| `check()` | 勾选复选框 | `locator.check()` |\n| `selectOption()` | 选择下拉选项 | `locator.selectOption('value')` |\n| `waitFor()` | 等待元素可见 | `locator.waitFor()` |\n| `getAttribute()` | 获取属性值 | `locator.getAttribute('href')` |\n\n### 过滤与断言\n\n定位器支持通过 `filter()` 方法进一步过滤元素：\n\n```typescript\n// 过滤条件示例\npage.locator('li').filter({ hasText: 'Item 1' });\npage.locator('button').filter({ hasNotText: 'Disabled' });\npage.locator('tr').filter({ has: page.locator('td.name') });\n```\n\n## 选择器生成\n\n### 自动生成选择器\n\nPlaywright 提供自动生成健壮选择器的功能。`selectorGenerator.ts` 分析 DOM 元素并生成可靠的选择器字符串。\n\n```mermaid\ngraph TD\n A[DOM 元素] --> B[selectorGenerator.ts]\n B --> C[收集元素信息]\n C --> D{检查优先级}\n D -->|测试ID| E[优先使用 test-id]\n D -->|角色+名称| F[回退到 role+name]\n D -->|CSS| G[最后使用 CSS 路径]\n E --> H[返回选择器字符串]\n F --> H\n G --> H\n \n style A fill:#e1f5ff\n style H fill:#c8e6c9\n```\n\n选择器生成优先级：\n\n1. `data-testid` 属性\n2. ARIA role + accessible name 组合\n3. 其他 ARIA 属性组合\n4. 文本内容\n5. CSS 路径\n\n### 生成 API\n\n在浏览器控制台中可以使用 `playwright` 对象生成选择器：\n\n```javascript\n// 获取元素的选择器\nplaywright.selector(element);\n\n// 生成特定语言的定位器\nplaywright.generateLocator(element, 'playwright');\nplaywright.generateLocator(element, 'cypress');\nplaywright.generateLocator(element, 'puppeteer');\n```\n\n## 选择器评估\n\n### 评估器职责\n\n`selectorEvaluator.ts` 负责评估选择器表达式与 DOM 元素的匹配关系：\n\n| 功能 | 说明 |\n|------|------|\n| **匹配验证** | 验证元素是否匹配选择器 |\n| **唯一性检查** | 确保选择器匹配唯一元素 |\n| **可见性检查** | 考虑元素可见性状态 |\n| **优先级排序** | 对多个匹配结果排序 |\n\n### 评估流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户代码\n participant L as Locator\n participant E as selectorEvaluator\n participant D as DOM\n \n U->>L: locator.click()\n L->>E: evaluate(selector)\n E->>D: querySelectorAll()\n D-->>E: [elements]\n E->>E: filterByVisibility()\n E->>E: sortByPriority()\n E-->>L: [matchedElements]\n L->>L: waitForMatch()\n L->>D: performAction()\n```\n\n## 最佳实践\n\n### 选择器选择优先级\n\n| 优先级 | 方法 | 示例 | 适用场景 |\n|--------|------|------|----------|\n| 1 | `getByRole()` | `getByRole('button', {name:'Submit'})` | 推荐首选 |\n| 2 | `getByLabel()` | `getByLabel('Username')` | 表单输入 |\n| 3 | `getByText()` | `getByText('Submit')` | 可见文本 |\n| 4 | `getByTestId()` | `getByTestId('submit-btn')` | 测试专用 |\n| 5 | CSS/XPath | `locator('.class')` | 复杂定位 |\n\n### 健壮性原则\n\n1. **避免脆弱选择器** - 不要依赖随机生成的类名\n2. **使用语义角色** - 优先使用 `getByRole()` 而非 CSS 类\n3. **添加 name 约束** - 角色选择器配合 accessible name 更可靠\n4. **避免绝对路径** - XPath 不使用 `html/body/div[1]/div[2]`\n5. **保持测试ID稳定** - 避免频繁更改 `data-testid`\n\n### 性能优化\n\n| 问题 | 解决方案 |\n|------|----------|\n| 元素查找慢 | 使用更具体的选择器 |\n| 频繁重试 | 减少选择器复杂度 |\n| 跨框架定位 | 使用 `frameLocator()` |\n\n## 控制台 API\n\nPlaywright 注入脚本在浏览器控制台暴露了调试工具：\n\n```javascript\n// 查找单个元素\nplaywright.$('button.submit');\n\n// 查找所有匹配元素\nplaywright.$$('li.item');\n\n// 检查元素信息\nplaywright.inspect('button');\n\n// 获取元素选择器\nplaywright.selector(element);\n\n// 生成定位器代码\nplaywright.generateLocator(element, 'playwright');\n\n// 获取 ARIA 快照\nplaywright.ariaSnapshot();\n```\n\n这些 API 用于 `playwright-cli` 工具的调试和诊断功能。\n\n## 总结\n\nPlaywright 的定位器和选择器系统提供了强大而灵活的页面元素定位能力：\n\n- **Locator API** 是高级封装，提供自动重试和惰性执行\n- **选择器引擎** 支持多种定位策略，采用插件化架构\n- **角色选择器** 基于 ARIA 规范，是推荐的定位方式\n- **选择器生成器** 自动创建健壮的选择器表达式\n- **评估器** 确保选择器正确匹配目标元素\n\n合理使用这些组件可以编写出稳定、可维护的浏览器自动化测试脚本。\n\n---\n\n**相关资料：**\n\n- Locator 客户端实现：`packages/playwright-core/src/client/locator.ts`\n- 选择器引擎核心：`packages/injected/src/selectorEngine.ts`\n- 角色选择器：`packages/injected/src/roleSelectorEngine.ts`\n- 选择器生成器：`packages/injected/src/selectorGenerator.ts`\n- 选择器评估器：`packages/injected/src/selectorEvaluator.ts`\n- 跨平台工具：`packages/isomorphic/locatorUtils.ts`\n\n---\n\n\n\n## 断言系统\n\n### 相关页面\n\n相关主题：[测试框架](#test-framework), [定位器和选择器](#locators-and-selectors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright/src/matchers/expect.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/expect.ts)\n- [packages/playwright/src/matchers/matchers.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/matchers.ts)\n- [packages/playwright-core/src/client/locator.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/locator.ts)\n- [packages/isomorphic/assert.ts](https://github.com/microsoft/playwright/blob/main/packages/isomorphic/assert.ts)\n- [packages/injected/src/roleUtils.ts](https://github.com/microsoft/playwright/blob/main/packages/injected/src/roleUtils.ts)\n- [README.md](https://github.com/microsoft/playwright/blob/main/README.md)\n \n\n# 断言系统\n\n## 概述\n\nPlaywright 断言系统是端到端测试框架的核心组件，提供了一套完整的 Web 页面状态验证机制。该系统基于\"Web-First 断言\"理念设计，具有自动等待、可重试、软断言等关键特性，旨在消除人工设置超时和避免 flaky 测试。\n\n断言系统的核心设计目标包括：\n\n- **自动等待**：在断言执行前自动等待目标元素达到预期状态\n- **可重试机制**：断言会自动重试直到条件满足或超时\n- **软断言支持**：允许收集多个失败而非立即中断测试\n- **丰富的匹配器**：覆盖 Web 交互中的各类验证场景\n\n资料来源：[README.md:1-100]()\n\n## 核心架构\n\nPlaywright 断言系统采用分层架构设计，主要包含以下层次：\n\n```mermaid\ngraph TD\n A[用户测试代码] --> B[expect API]\n B --> C[软断言控制器]\n C --> D[匹配器集合]\n D --> E[等待策略]\n E --> F[Locator/Page 对象]\n F --> G[底层 CDP 通信]\n \n H[自定义匹配器] --> D\n I[toBe/toHave/toContain...] --> D\n```\n\n### 核心组件表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| expect | `packages/playwright/src/matchers/expect.ts` | 入口函数，创建断言上下文 |\n| 匹配器 | `packages/playwright/src/matchers/matchers.ts` | 实现具体断言逻辑 |\n| Locator | `packages/playwright-core/src/client/locator.ts` | 元素定位与断言绑定 |\n| 断言工具 | `packages/isomorphic/assert.ts` | 底层断言辅助函数 |\n\n资料来源：[packages/playwright/src/matchers/expect.ts:1-50]()\n\n## expect API\n\n### 基本用法\n\n`expect` 是 Playwright 断言系统的入口函数，支持多种使用方式：\n\n```typescript\nimport { test, expect } from '@playwright/test';\n\n// 页面级断言\nawait expect(page).toHaveTitle('Playwright');\n\n// 定位器断言\nawait expect(page.getByRole('button')).toBeVisible();\n\n// 期望值断言\nexpect(value).toBe(42);\n```\n\n### expect 函数实现\n\n`expect` 函数接受一个实际值作为参数，返回一个包含所有断言方法的 Expect 对象：\n\n```typescript\n// packages/playwright/src/matchers/expect.ts 核心签名\nfunction expect(value: any): Expect\n```\n\n Expect 对象提供的方法分为两类：\n1. **布尔匹配器**：直接返回布尔结果的断言\n2. **可等待匹配器**：返回 Promise 并自动等待的断言\n\n资料来源：[packages/playwright/src/matchers/expect.ts:50-150]()\n\n### 软断言\n\n软断言允许在测试执行过程中收集多个失败断言，而不是在第一个失败时立即停止：\n\n```typescript\ntest('soft assertions example', async ({ page }) => {\n await expect.soft(page).toHaveTitle('Expected Title');\n await expect.soft(page.getByRole('button')).toBeVisible();\n // 即使前一个失败，后续断言仍会执行\n});\n```\n\n软断言的失败会在测试结束时统一报告，测试状态标记为失败。\n\n资料来源：[packages/playwright/src/matchers/expect.ts:150-200]()\n\n## 内置匹配器\n\n### 页面级匹配器\n\n页面级匹配器直接作用于 `Page` 对象，验证页面整体状态：\n\n| 匹配器 | 描述 | 示例 |\n|--------|------|------|\n| `toHaveTitle(title)` | 验证页面标题 | `await expect(page).toHaveTitle(/Playwright/)` |\n| `toHaveURL(url)` | 验证当前 URL | `await expect(page).toHaveURL('**/docs**')` |\n| `toHaveScreenshot(name)` | 验证页面截图 | `await expect(page).toHaveScreenshot('home.png')` |\n\n资料来源：[packages/playwright/src/matchers/matchers.ts:1-100]()\n\n### 元素级匹配器\n\n元素级匹配器通过 Locator 链式调用，用于验证单个或多个元素的状态：\n\n```typescript\n// 可见性断言\nawait expect(page.locator('#submit')).toBeVisible();\nawait expect(page.locator('.loading')).toBeHidden();\n\n// 内容断言\nawait expect(page.getByRole('button')).toHaveText('Submit');\nawait expect(page.locator('.error')).toContainText('Invalid');\n\n// 属性断言\nawait expect(page.getByRole('input')).toHaveAttribute('required');\nawait expect(page.locator('img')).toHaveAttribute('src', /logo/);\n\n// 表单值断言\nawait expect(page.getByRole('textbox')).toHaveValue('default text');\n```\n\n资料来源：[packages/playwright/src/matchers/matchers.ts:100-300]()\n\n### 可访问性匹配器\n\nPlaywright 提供 ARIA 角色相关的匹配器，用于验证元素的可访问性语义：\n\n```typescript\n// 验证元素角色\nawait expect(page.locator('dialog')).toHaveRole('dialog');\nawait expect(page.locator('nav')).toHaveRole('navigation');\n```\n\n角色映射定义在 `roleUtils.ts` 中，涵盖了 HTML 语义化元素到 ARIA 角色的转换规则。\n\n资料来源：[packages/injected/src/roleUtils.ts:1-50]()\n\n### 计数与状态匹配器\n\n| 匹配器 | 描述 |\n|--------|------|\n| `toHaveCount(count)` | 验证元素数量 |\n| `toBeChecked()` | 验证复选框/单选框状态 |\n| `toBeEnabled()` | 验证元素可用状态 |\n| `toBeDisabled()` | 验证元素禁用状态 |\n| `toBeFocused()` | 验证焦点状态 |\n\n```typescript\nawait expect(page.getByRole('checkbox', { name: 'Remember me' })).toBeChecked();\nawait expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();\n```\n\n资料来源：[packages/playwright/src/matchers/matchers.ts:300-400]()\n\n## Locator 集成\n\n### Locator 断言方法\n\nLocator 对象直接集成了断言方法，允许链式调用：\n\n```typescript\n// Locator 类中的断言方法\n// packages/playwright-core/src/client/locator.ts\n\nclass Locator {\n // 可见性断言\n async toBeVisible(options?: VisibilityOption): Promise\n \n // 内容断言 \n async toHaveText(expected: string | RegExp | (string | RegExp)[]): Promise\n \n // 属性断言\n async toHaveAttribute(name: string, value?: string | RegExp): Promise\n \n // 值断言\n async toHaveValue(value: string | RegExp): Promise\n}\n```\n\nLocator 断言的显著特点是**自动等待**：如果目标元素尚未满足条件，Playwright 会自动等待直到超时。\n\n资料来源：[packages/playwright-core/src/client/locator.ts:200-350]()\n\n### 等待策略\n\nPlaywright 断言内置智能等待策略：\n\n```mermaid\ngraph LR\n A[执行断言] --> B{元素存在?}\n B -->|否| C[等待 DOM 出现]\n C --> D{条件满足?}\n D -->|否| E[重试]\n E --> D\n D -->|是| F[断言通过]\n B -->|是| G{条件满足?}\n G -->|否| H[等待条件变化]\n H --> G\n G -->|是| F\n```\n\n默认超时时间为 30 秒，可通过配置或方法参数覆盖：\n\n```typescript\n// 使用配置超时\nawait expect(page.locator('.loading')).toBeHidden({ timeout: 5000 });\n\n// 使用全局配置\ntest.setTimeout(10000);\n```\n\n## 底层断言工具\n\n### 断言辅助函数\n\n`packages/isomorphic/assert.ts` 提供了底层断言实现：\n\n```typescript\n// 核心断言函数签名\nexport function expect(value: any, options?: ExpectOptions): ExpectResult\n\n// 软断言标记\nexport type ExpectOptions = {\n isSoft?: boolean\n}\n\n// 断言结果\nexport type ExpectResult = {\n pass: boolean\n message?: string\n}\n```\n\n这些底层函数处理：\n- 布尔值比较\n- 正则表达式匹配\n- 对象深度比较\n- 数组包含检查\n\n资料来源：[packages/isomorphic/assert.ts:1-100]()\n\n## 配置与选项\n\n### 断言超时配置\n\n| 配置方式 | 优先级 | 示例 |\n|----------|--------|------|\n| 方法参数 | 最高 | `toBeVisible({ timeout: 1000 })` |\n| 测试超时 | 中 | `test.setTimeout(10000)` |\n| 全局配置 | 最低 | `playwright.config.ts` 中设置 |\n\n### expect 配置\n\n```typescript\n// 自定义 expect 配置\ntest.use({\n expect: {\n timeout: 5000,\n soft: false\n }\n});\n```\n\n## 最佳实践\n\n### 1. 使用语义化定位器\n\n```typescript\n// 推荐：使用角色定位器\nawait expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();\n\n// 避免：过度依赖 CSS 选择器\nawait expect(page.locator('.btn-primary')).toBeVisible();\n```\n\n### 2. 利用自动等待\n\n```typescript\n// 正确：依赖自动等待\nawait expect(page.getByRole('status')).toHaveText('Saved');\n\n// 错误：手动等待（容易导致 flaky）\nawait page.waitForTimeout(1000);\nawait expect(page.getByRole('status')).toHaveText('Saved');\n```\n\n### 3. 软断言收集错误\n\n```typescript\ntest('form validation', async ({ page }) => {\n await expect.soft(page.getByLabel('Email')).toHaveValue(/@/);\n await expect.soft(page.getByLabel('Phone')).toHaveValue(/^\\d+$/);\n // 两个验证都会执行，错误会一起报告\n});\n```\n\n### 4. 正则表达式匹配\n\n```typescript\n// 动态内容匹配\nawait expect(page.locator('.status')).toContainText(/saved|updated/i);\n\n// URL 模式匹配\nawait expect(page).toHaveURL(/\\?page=\\d+/);\n```\n\n## 错误处理与调试\n\n### 断言错误信息\n\nPlaywright 断言失败时会提供详细的诊断信息：\n\n```\nexpect(received).toHaveText(expected)\n\nExpected string: \"Submit\"\nReceived string: \"Cancel\"\n```\n\n### 调试模式\n\n使用 Playwright CLI 进行断言调试：\n\n```bash\n# 运行测试并进入调试模式\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n\n# 附加到测试会话\nplaywright-cli attach \n```\n\n## 总结\n\nPlaywright 断言系统通过以下设计实现了可靠的 Web 测试：\n\n| 特性 | 优势 |\n|------|------|\n| Web-First 断言 | 自动等待元素就绪，消除人工超时 |\n| 语义化匹配器 | 符合 ARIA 规范，支持可访问性测试 |\n| 软断言支持 | 收集多个失败，提供完整错误报告 |\n| Locator 集成 | 链式调用，代码可读性高 |\n| 可配置超时 | 灵活适应不同测试场景 |\n\n该系统是 Playwright 测试框架的核心支柱，为开发者提供了简洁、可靠、语义化的断言 API。\n\n---\n\n\n\n## 命令行工具\n\n### 相关页面\n\n相关主题：[快速入门](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/playwright-core/src/cli/program.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/program.ts)\n- [packages/playwright-core/src/cli/browserActions.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/browserActions.ts)\n- [packages/playwright-core/src/cli/installActions.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/cli/installActions.ts)\n- [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)\n- [packages/playwright-core/src/tools/backend/tools.ts](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/backend/tools.ts)\n- [packages/playwright-core/src/tools/trace/SKILL.md](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/tools/trace/SKILL.md)\n- [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)\n \n\n# 命令行工具\n\nPlaywright 提供了一套完整的命令行工具体系，用于浏览器自动化、测试执行、轨迹分析和 CLI 客户端交互。本页详细介绍 Playwright 命令行工具的整体架构、各子命令的功能以及典型使用场景。\n\n## 1. 架构概述\n\nPlaywright 命令行工具由多个层次的组件构成，形成了一个分层式的命令行体系。最上层是用户直接调用的 `playwright` 主命令，中间层是针对不同功能域的子命令模块（如浏览器管理、测试运行、轨迹查看等），底层则是负责具体操作执行的工具后端。\n\n```mermaid\ngraph TD\n A[\"用户终端\"] --> B[\"playwright 主程序
program.ts\"]\n B --> C[\"browserActions
浏览器管理\"]\n B --> D[\"installActions
安装管理\"]\n B --> E[\"playwright-cli
CLI客户端\"]\n B --> F[\"playwright test
测试运行\"]\n B --> G[\"playwright trace
轨迹分析\"]\n E --> H[\"tools.ts
工具后端\"]\n H --> I[\"浏览器会话管理\"]\n H --> J[\"快照与截图\"]\n H --> K[\"网络拦截\"]\n H --> L[\"存储管理\"]\n```\n\n主程序入口位于 `program.ts`，负责解析命令行参数并将请求分发到对应的子模块。资料来源：[packages/playwright-core/src/cli/program.ts]()\n\n## 2. 主命令模块\n\n### 2.1 浏览器动作命令\n\n`browserActions.ts` 模块封装了所有与浏览器交互相关的底层操作，包括启动浏览器实例、创建页面、执行导航等核心功能。这些动作构成了所有高级自动化操作的基础。\n\n| 命令类别 | 功能描述 |\n|---------|---------|\n| `open` | 启动新的浏览器会话并导航到指定 URL |\n| `goto` | 在当前会话中导航到目标页面 |\n| `close` | 关闭当前浏览器会话 |\n| `kill-all` | 强制终止所有浏览器进程 |\n\n资料来源：[packages/playwright-core/src/cli/browserActions.ts]()\n\n### 2.2 安装命令\n\n`installActions.ts` 模块负责管理 Playwright 的运行时依赖。最重要的功能是下载和安装浏览器可执行文件。该模块确保所有支持的浏览器（Chromium、Firefox、WebKit）都被正确安装并可用。\n\n```bash\n# 安装所有浏览器\nnpx playwright install\n\n# 安装指定浏览器\nnpx playwright install chromium\nnpx playwright install firefox\nnpx playwright install webkit\n\n# 安装带驱动依赖\nnpx playwright install --with-deps\n```\n\n资料来源：[packages/playwright-core/src/cli/installActions.ts]()\n\n## 3. playwright-cli 客户端\n\n`playwright-cli` 是 Playwright 提供的交互式命令行客户端，提供了比主命令更丰富的浏览器自动化能力。它支持实时快照查看、元素交互、网络拦截、存储管理等高级功能。\n\n### 3.1 核心命令\n\n```mermaid\ngraph LR\n A[\"playwright-cli\"] --> B[\"页面操作\"]\n A --> C[\"元素定位\"]\n A --> D[\"网络控制\"]\n A --> E[\"状态管理\"]\n A --> F[\"调试工具\"]\n \n B --> B1[\"goto / click / fill / type\"]\n C --> C1[\"snapshot / click ref\"]\n D --> D1[\"route / unroute\"]\n E --> E1[\"cookie / localstorage\"]\n F --> F1[\"console / tracing\"]\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/SKILL.md]()\n\n#### 页面操作命令\n\n| 命令 | 功能 | 示例 |\n|-----|------|------|\n| `open` | 打开浏览器并访问 URL | `playwright-cli open https://example.com` |\n| `goto` | 导航到指定页面 | `playwright-cli goto https://example.com` |\n| `click` | 点击元素 | `playwright-cli click e15` |\n| `fill` | 填充输入框 | `playwright-cli fill e5 \"text\"` |\n| `type` | 模拟键盘输入 | `playwright-cli type \"search query\"` |\n| `press` | 按下按键 | `playwright-cli press Enter` |\n| `snapshot` | 获取页面快照 | `playwright-cli snapshot` |\n| `screenshot` | 截图保存 | `playwright-cli screenshot --filename=page.png` |\n| `pdf` | 生成 PDF | `playwright-cli pdf --filename=page.pdf` |\n\n#### 元素定位系统\n\nplaywright-cli 采用基于快照的引用系统来定位页面元素。每个可交互元素在快照中都有一个唯一的引用标识符（如 `e15`），用户可以通过这些引用来执行操作。\n\n```bash\n# 获取带引用的快照\nplaywright-cli snapshot\n\n# 使用引用点击元素\nplaywright-cli click e15\n\n# 也支持 CSS 选择器和 Playwright 定位器\nplaywright-cli click \"#main > button.submit\"\nplaywright-cli click \"getByRole('button', { name: 'Submit' })\"\n```\n\n### 3.2 浏览器会话管理\n\nplaywright-cli 支持多个并发浏览器会话，每个会话可以通过名称标识。这对于同时测试多个场景或进行 A/B 测试非常有用。\n\n```bash\n# 创建命名会话\nplaywright-cli -s=mysession open https://example.com\n\n# 列出所有会话\nplaywright-cli list\n\n# 关闭指定会话\nplaywright-cli -s=mysession close\n\n# 关闭所有会话\nplaywright-cli close-all\n\n# 强制终止所有浏览器进程\nplaywright-cli kill-all\n```\n\n持久化配置文件支持自定义会话设置：\n\n```bash\n# 使用配置文件打开\nplaywright-cli open https://example.com --config=.playwright/my-cli.json\n\n# 指定浏览器类型\nplaywright-cli open https://example.com --browser=firefox\n\n# 以有头模式打开\nplaywright-cli open https://example.com --headed\n\n# 使用持久化配置文件\nplaywright-cli open https://example.com --persistent\nplaywright-cli open https://example.com --profile=/path/to/profile\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/session-management.md]()\n\n### 3.3 存储管理\n\nplaywright-cli 提供了完整的客户端存储管理能力，支持 Cookie、LocalStorage、SessionStorage 的增删改查操作。\n\n```bash\n# 状态持久化\nplaywright-cli state-save auth.json\nplaywright-cli state-load auth.json\n\n# Cookie 管理\nplaywright-cli cookie-list\nplaywright-cli cookie-list --domain=example.com\nplaywright-cli cookie-get session_id\nplaywright-cli cookie-set session_id abc123\nplaywright-cli cookie-delete session_id\nplaywright-cli cookie-clear\n\n# LocalStorage 管理\nplaywright-cli localstorage-list\nplaywright-cli localstorage-get theme\nplaywright-cli localstorage-set theme dark\nplaywright-cli localstorage-delete theme\nplaywright-cli localstorage-clear\n```\n\n### 3.4 网络控制\n\n```bash\n# 拦截请求并返回自定义状态\nplaywright-cli route \"**/*.jpg\" --status=404\n\n# 修改响应体\nplaywright-cli route \"https://api.example.com/**\" --body='{\"mock\": true}'\n\n# 列出所有路由规则\nplaywright-cli route-list\n\n# 移除路由规则\nplaywright-cli unroute \"**/*.jpg\"\nplaywright-cli unroute\n```\n\n### 3.5 标签页管理\n\n```bash\n# 标签页操作\nplaywright-cli tab-list\nplaywright-cli tab-new\nplaywright-cli tab-new https://example.com/page\nplaywright-cli tab-close\nplaywright-cli tab-close 2\nplaywright-cli tab-select 0\n```\n\n## 4. 轨迹工具\n\n`playwright trace` 命令用于分析和调试 `.zip` 格式的轨迹文件，这些文件由 Playwright 测试运行时生成，包含完整的执行过程记录。\n\n### 4.1 轨迹工作流程\n\n```mermaid\ngraph TD\n A[\"trace open\"] --> B[\"trace actions\"]\n B --> C{\"发现问题?\"}\n C -->|是| D[\"trace actions --errors-only\"]\n C -->|否| E[\"继续分析\"]\n D --> F[\"trace action \"]\n F --> G[\"trace snapshot\"]\n G --> H[\"trace requests
trace console\"]\n```\n\n### 4.2 轨迹命令\n\n| 命令 | 功能 |\n|-----|------|\n| `trace open ` | 打开并提取轨迹文件，显示元数据 |\n| `trace close` | 关闭当前轨迹，清理临时文件 |\n| `trace actions` | 列出所有动作，支持 `--grep` 过滤 |\n| `trace actions --errors-only` | 仅显示失败的动作 |\n| `trace action ` | 查看特定动作的详细信息 |\n| `trace snapshot ` | 获取动作执行时的 DOM 快照 |\n| `trace requests` | 查看网络请求列表 |\n| `trace requests --failed` | 仅显示失败的请求 |\n| `trace console` | 查看控制台日志 |\n| `trace console --errors-only` | 仅显示错误日志 |\n| `trace attachments` | 列出所有附件 |\n| `trace attachment ` | 提取指定附件 |\n\n资料来源：[packages/playwright-core/src/tools/trace/SKILL.md]()\n\n## 5. 调试工具\n\nplaywright-cli 集成了多种调试辅助工具，帮助开发者诊断问题。\n\n### 5.1 控制台与网络监控\n\n```bash\n# 查看控制台输出\nplaywright-cli console\nplaywright-cli console warning\n\n# 查看网络请求\nplaywright-cli requests\n\n# 查看特定请求详情\nplaywright-cli request 5\n```\n\n### 5.2 追踪录制\n\n```bash\n# 开始录制追踪\nplaywright-cli tracing-start\n\n# 停止录制并保存\nplaywright-cli tracing-stop\n```\n\n追踪文件包含以下内容：\n\n| 文件/目录 | 内容描述 |\n|----------|---------|\n| `trace-{timestamp}.trace` | 动作日志，包含每个操作的快照和截图 |\n| `trace-{timestamp}.network` | 完整的网络活动记录 |\n| `resources/` | 缓存的资源文件 |\n\n### 5.3 可视化调试\n\n```bash\n# 启动带标注功能的截图工具\nplaywright-cli show --annotate\n\n# 高亮显示元素\nplaywright-cli highlight e5\nplaywright-cli highlight e5 --style=\"outline: 3px dashed red\"\nplaywright-cli highlight --hide\n```\n\n## 6. 代码执行\n\n`run-code` 命令允许在页面上下文中直接执行 JavaScript 代码，这对于动态探测和调试非常有用。\n\n```bash\n# 获取页面信息\nplaywright-cli run-code \"async page => {\n return await page.title();\n}\"\n\n# 读写剪贴板\nplaywright-cli run-code \"async page => {\n await page.context().grantPermissions(['clipboard-read']);\n return await page.evaluate(() => navigator.clipboard.readText());\n}\"\n\n# 执行复杂逻辑\nplaywright-cli run-code \"async page => {\n const multiplier = 5;\n return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);\n}\"\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/running-code.md]()\n\n## 7. 测试集成\n\nPlaywright CLI 与 Playwright Test 框架紧密集成，提供了便捷的测试调试能力。\n\n```bash\n# 运行所有测试\nPLAYWRIGHT_HTML_OPEN=never npx playwright test\n\n# 调试模式运行测试\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n```\n\n调试模式会暂停测试执行并提供会话名称，允许通过 playwright-cli 附加到测试会话进行实时调试：\n\n```bash\n# 等待调试指令输出 tw-XXXX 会话名\nPLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli\n\n# 附加到测试会话\nplaywright-cli attach tw-XXXX\n```\n\n资料来源：[packages/playwright-core/src/tools/cli-client/skill/references/playwright-tests.md]()\n\n## 8. 工具后端架构\n\n`tools.ts` 模块定义了 CLI 工具的后端实现，封装了所有底层浏览器操作能力。这些工具通过 MCP（Model Context Protocol）协议对外提供服务，使得 AI 代理能够通过标准化接口调用 Playwright 功能。\n\n核心工具类别包括：\n\n- **页面操作工具**：导航、点击、输入、提交等\n- **元素查询工具**：快照生成、引用解析、选择器生成\n- **状态管理工具**：Cookie、存储、网络路由\n- **调试工具**：控制台捕获、追踪录制、截图\n\n资料来源：[packages/playwright-core/src/tools/backend/tools.ts]()\n\n## 9. 使用建议\n\n### 9.1 工具选择指南\n\n| 场景 | 推荐工具 |\n|------|---------|\n| 快速浏览网页 | `playwright-cli open` |\n| 调试测试失败 | `playwright test --debug=cli` + `playwright-cli attach` |\n| 分析测试轨迹 | `playwright trace` |\n| 复杂自动化脚本 | `playwright-cli run-code` |\n| 并发多浏览器测试 | `playwright-cli -s=` |\n\n### 9.2 最佳实践\n\n1. **会话命名**：使用有意义的会话名称，便于管理和清理\n2. **资源清理**：完成操作后及时关闭会话或使用 `close-all`\n3. **持久化配置**：复杂场景使用配置文件管理会话设置\n4. **追踪录制**：遇到问题时录制追踪便于事后分析\n5. **快照优先**：使用 `snapshot` 命令而非频繁截图，提高效率\n\n### 9.3 安装与更新\n\n```bash\n# 检查版本\nnpx --no-install playwright-cli --version\n\n# 或使用全局命令\nplaywright-cli --version\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：microsoft/playwright\n\n摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized。\n\n## 1. 安装坑 · 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f8ee5532aee4b6cbf512f4227b0bac6 | https://github.com/microsoft/playwright/issues/40856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ae154da8c374e95842c5b9fed587329 | https://github.com/microsoft/playwright/issues/40857 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d99eb725d0044cc8a856ff77a5034353 | https://github.com/microsoft/playwright/issues/40868 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[Bug]: test body doesn't accept function with a return type other than void\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: test body doesn't accept function with a return type other than void\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_068a984a4ea348dd8b8de11244fbddd2 | https://github.com/microsoft/playwright/issues/40851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[Feature] Allow custom command-line arguments in @playwright/test\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Allow custom command-line arguments in @playwright/test\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_27f460cbef7e4489b323fb9fb7cfc515 | https://github.com/microsoft/playwright/issues/10337 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.56.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.56.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cc7813a33a854a3c8465dd3548ef7684 | https://github.com/microsoft/playwright/releases/tag/v1.56.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.57.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.57.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d76f3b46992422c8b4a18583cabd192 | https://github.com/microsoft/playwright/releases/tag/v1.57.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v1.59.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.59.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4296f1e3e0d4e37bbecccf2fe087c00 | https://github.com/microsoft/playwright/releases/tag/v1.59.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 能力坑 · 来源证据：v1.60.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v1.60.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2bf82c9b52a6418986114131cd1bd2d3 | https://github.com/microsoft/playwright/releases/tag/v1.60.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:221981891 | https://github.com/microsoft/playwright | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：v1.59.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.59.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fa3aef4aac6e4812b8d1e973fb2e88c5 | https://github.com/microsoft/playwright/releases/tag/v1.59.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · 来源证据：v1.55.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.55.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66dddad3517842b38fff2a76a1c00ce0 | https://github.com/microsoft/playwright/releases/tag/v1.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 来源证据：v1.58.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.58.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53b55fd4a28c4da791a8160ca677d10d | https://github.com/microsoft/playwright/releases/tag/v1.58.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：v1.56.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.56.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e050e46d53424e568cf3a0286a0f2739 | https://github.com/microsoft/playwright/releases/tag/v1.56.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v1.58.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91fccb17c1534cbfbc86fc6d7d0f7e30 | https://github.com/microsoft/playwright/releases/tag/v1.58.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.58.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b5831f013464a809b33b71e270d6a82 | https://github.com/microsoft/playwright/releases/tag/v1.58.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：microsoft/playwright\n\n摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized。\n\n## 1. 安装坑 · 来源证据：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: `AggregateError.errors[]` sub-errors are invisible in reporter output — only the top-level message is serialized\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f8ee5532aee4b6cbf512f4227b0bac6 | https://github.com/microsoft/playwright/issues/40856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Unreadable text in textarea.text-editor under dark mode due to forced text color\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9ae154da8c374e95842c5b9fed587329 | https://github.com/microsoft/playwright/issues/40857 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: module.register() deprecation warning (DEP0205) on Node 26\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d99eb725d0044cc8a856ff77a5034353 | https://github.com/microsoft/playwright/issues/40868 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[Bug]: test body doesn't accept function with a return type other than void\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: test body doesn't accept function with a return type other than void\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_068a984a4ea348dd8b8de11244fbddd2 | https://github.com/microsoft/playwright/issues/40851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：[Feature] Allow custom command-line arguments in @playwright/test\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Allow custom command-line arguments in @playwright/test\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_27f460cbef7e4489b323fb9fb7cfc515 | https://github.com/microsoft/playwright/issues/10337 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.56.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.56.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cc7813a33a854a3c8465dd3548ef7684 | https://github.com/microsoft/playwright/releases/tag/v1.56.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：v1.57.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.57.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d76f3b46992422c8b4a18583cabd192 | https://github.com/microsoft/playwright/releases/tag/v1.57.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v1.59.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.59.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c4296f1e3e0d4e37bbecccf2fe087c00 | https://github.com/microsoft/playwright/releases/tag/v1.59.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 能力坑 · 来源证据：v1.60.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：v1.60.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2bf82c9b52a6418986114131cd1bd2d3 | https://github.com/microsoft/playwright/releases/tag/v1.60.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:221981891 | https://github.com/microsoft/playwright | README/documentation is current enough for a first validation pass.\n\n## 11. 运行坑 · 来源证据：v1.59.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.59.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fa3aef4aac6e4812b8d1e973fb2e88c5 | https://github.com/microsoft/playwright/releases/tag/v1.59.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · 来源证据：v1.55.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.55.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_66dddad3517842b38fff2a76a1c00ce0 | https://github.com/microsoft/playwright/releases/tag/v1.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 维护坑 · 来源证据：v1.58.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.58.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53b55fd4a28c4da791a8160ca677d10d | https://github.com/microsoft/playwright/releases/tag/v1.58.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:221981891 | https://github.com/microsoft/playwright | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：v1.56.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.56.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e050e46d53424e568cf3a0286a0f2739 | https://github.com/microsoft/playwright/releases/tag/v1.56.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v1.58.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91fccb17c1534cbfbc86fc6d7d0f7e30 | https://github.com/microsoft/playwright/releases/tag/v1.58.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.58.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.58.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1b5831f013464a809b33b71e270d6a82 | https://github.com/microsoft/playwright/releases/tag/v1.58.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:221981891 | https://github.com/microsoft/playwright | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# playwright - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 playwright 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. getting-started：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：架构概览。围绕“架构概览”模拟一次用户任务，不展示安装或运行结果。\n4. client-implementation：客户端实现。围绕“客户端实现”模拟一次用户任务，不展示安装或运行结果。\n5. server-implementation：服务器端实现。围绕“服务器端实现”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. getting-started\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“架构概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. client-implementation\n输入：用户提供的“客户端实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. server-implementation\n输入：用户提供的“服务器端实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / getting-started：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“架构概览”形成一个小中间产物，并等待用户确认。\n- Step 4 / client-implementation：Step 4 必须围绕“客户端实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / server-implementation：Step 5 必须围绕“服务器端实现”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/microsoft/playwright\n- https://github.com/microsoft/playwright#readme\n- .claude/skills/playwright-dev/SKILL.md\n- .claude/skills/playwright-devops/SKILL.md\n- packages/playwright-core/src/tools/cli-client/skill/SKILL.md\n- packages/playwright-core/src/tools/trace/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n- packages/playwright/package.json\n- packages/playwright-core/package.json\n- packages/playwright-test/package.json\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 playwright 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：microsoft/playwright\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm i -g @playwright/cli@latest\n```\n\n来源：https://github.com/microsoft/playwright#readme\n\n## 来源\n\n- repo: https://github.com/microsoft/playwright\n- docs: https://github.com/microsoft/playwright#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_92cb4f86971644e48c9c64d546891493"
}