内容
# 浏览器测试技能
<p align="center"><img src="assets/browser-test-skills.jpg" width="512" alt="browser-test-skills hero" /></p>
一套 Claude Code 技能，提供完整的端到端浏览器测试流程，使用 Playwright MCP。
## 功能概述
四项技能组成了一个创建、稳定、编译和运行端到端浏览器测试的流程：
```
作者 → 精炼器 → 编译器 → Playwright CI
```
| 技能 | 目的 |
|-------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `browser-test:author` | 通过探索性浏览器运行，将模糊的功能描述转化为结构化的 Markdown 测试用例 |
| `browser-test:refiner` | 通过重复运行测试，修复不稳定的步骤，更新约定，直到连续 N 次通过 |
| `browser-test:runner` | 使用 Claude 和 playwright-mcp 精确执行稳定的测试用例，报告通过/失败并提供证据 |
| `browser-test:compiler` | 通过引导浏览器重放，将稳定的 Markdown 测试用例转换为 Playwright `.spec.ts` 文件 |
## 为什么测试自动化很重要
可靠的自动化测试套件是软件团队可以投资的最高杠杆之一。它提供了信心，即新的更改不会破坏现有的行为，使更快的发布周期成为可能，并在用户发现之前捕获回归。如果没有它，每个部署都是手动验证练习，每个重构都带有隐藏的风险。
但是，构建和维护该套件很困难 — 困难之处不在于测试逻辑本身，而在于机制：编写稳定的选择器，管理时间和异步行为，保持测试与 UI 演变同步，并诊断故障，这些是半产品错误和半测试基础设施的问题。这些是需要时间才能发展的专业技能。
这产生了一个差距，大多数团队都深感其切：**对应用程序应该如何工作的有最深入了解的人通常不是维护测试套件的人。** 领域专家 — 产品所有者，高级开发人员，QA 分析师，他们了解每个边缘情况 — 通常不能直接应用他们的知识，因为工具需要他们没有的自动化专业知识。而可以编写测试的工程师可能并不完全了解他们正在测试的业务逻辑。
结果是测试套件由有时间和 Playwright 知识的人编写，涵盖了最容易自动化的流程，而不是最重要的流程。
**该项目的目标是弥合这一差距。** 通过使用 LLM 处理自动化机制，它让领域专家用自然语言描述应用程序应该做什么，并获得一个工作稳定的测试作为回报 — 而无需了解什么是可访问性树或如何编写可靠的 `waitFor`。
## 工作原理（以及为什么不同）
### 传统的自动化问题
在传统的端到端自动化中，测试由阅读应用程序源代码或使用浏览器开发工具的工程师编写 CSS 选择器，然后将这些选择器硬编码到 Playwright 或 Selenium 脚本中。结果最初有效，但很脆弱：类名重命名，组件重构或 UI 刷新会破坏选择器，即使功能完全未更改。保持测试套件绿色成为与功能工作竞争的维护负担 — 而最有资格知道测试是否**正确**的人通常不是修复它的人。
### LLM 驱动的方法
这些技能使用 LLM 配对 playwright-mcp 浏览器，以与实时应用程序交互，方式与人类测试人员相同：导航到页面，观察屏幕上的内容，单击元素，填写表单并验证结果。选择器来自在会话期间拍摄的实时可访问性快照 — 而不是读取源代码。LLM 看到的可访问性树与屏幕阅读器相同，这意味着选择器基于用户实际体验的内容，而不是可以静默更改的实现细节。
因为 LLM 观察到的是真实的浏览器，所以它也会遇到真正的时间行为，真正的加载状态和真正的边缘情况 — 并记录它如何处理它们。这种文档成为测试用例。
### 流程说明
```
作者 → 精炼器 → 编译器 → Playwright CI
```
| 阶段 | 目的 | 原因 |
|---|---|---|
| **作者** | 探索实时应用，识别场景，生成 Markdown 测试用例 | 在无需自动化专业知识的情况下捕获领域知识，以人类可读的格式 |
| **精炼器** | 重复运行测试，修复不稳定的步骤，更新约定 | 测试一次通过并不可靠；精炼器使其在进入 CI 之前确定 |
| **编译器** | 重放稳定的 Markdown 测试，记录每个选择器，从可访问性快照中生成 `.spec.ts` | 将依赖 LLM 的测试转换为标准 Playwright 文件，在 CI 中无需 LLM 运行 |
| **运行器** | 忠实地执行 Markdown 测试，报告通过/失败并提供证据 | 允许您在任何时候用 Markdown 源验证实时应用，而独立于编译的规范 |
关键见解：**Markdown 测试用例是权威的，而 `.spec.ts` 是派生工件。** 如果编译的测试失败，您可以回到 Markdown — 而不是相反。
### 设计原则
- **浏览器是真相的来源** — 所有选择器都来自实时 `browser_snapshot` 可访问性树，而非读取应用程序源代码。这确保每个选择器在写入之前都针对真实的浏览器会话进行测试。
- **可访问性树优先** — 优先使用 `getByRole`、`getByTestId`、`getByLabel` 而非 CSS 选择器。可访问性属性设计上是稳定的；它们在功能更改时更改，而不是在样式更改时更改。
- **每次运行都是全新会话** — 测试运行之间没有会话泄漏。每个运行都从干净的浏览器状态开始，这消除了因残留的 cookie、缓存状态或先前测试副作用引起的一整类间歇性故障。
- **约定捕获模式** — 可重用的模式（登录序列，会话管理，共同 UI 流程）存在于约定文件中，而非 LLM 的隐含知识中。这使得测试套件在会话和模型之间可移植。
- **Markdown 是权威的** — 测试用例是人类可读的 Markdown，任何团队成员都可以审查，质疑和理解。编译的 `.spec.ts` 文件是生成的输出；Markdown 是您维护的内容。
## 入门指南
熟悉技能流程的最快方法是先在公共演示应用上试用，然后再编写您自己的产品测试。这样可以消除所有环境摩擦 — 无需设置凭证，无需编写约定文件，无需运行开发服务器 — 这样您就可以完全专注于学习技能如何协同工作。
### 在 saucedemo.com 上试用
[Saucedemo](https://www.saucedemo.com) 是一个专门为练习测试自动化而设计的演示电子商务网站。它具有登录，产品列表，购物车和结账流程，这些流程足够真实，有意义，但又足够简单，易于学习。登录凭证在网站的主页上记录。
**步骤 1 — 先手动探索**
在调用任何技能之前，请先在网站上手动探索几分钟。登录，浏览产品，添加一些到购物车，并完成结账。选择一个简单，端到端的流程来转换为测试 — 例如，添加特定商品到购物车并结账为标准用户。
这样做，您会在进入作者步骤时对预期行为有清晰的心理模型。作者技能将生成一个更清晰的测试用例，当您可以精确描述流程时，而不是要求它从头开始发现一个。
**步骤 2 — 编写测试（定向）**
一旦您选择了流程，请直接描述它：
> "编写一个测试，以验证标准用户可以在 <https://www.saucedemo.com> 上将商品添加到购物车并完成结账"
**步骤 3 — 运行完整流程**
```
"精炼 saucedemo 结账测试" → browser-test:refiner
"编译 saucedemo 结账测试" → browser-test:compiler
npx playwright test → 运行生成的 .spec.ts 在 CI 中
```
在 saucedemo 上进行一次完整通过后，您将获得该工作流的肌肉记忆。然后转移到您的真实产品 — 在 [项目设置](#项目设置) 中描述您的项目结构和约定文件，并开始编写反映您团队实际领域知识的测试。
**后续 — 探索式创作**
一旦您熟悉了流程，作者技能也可以驱动发现。要求它探索网站并提出完整的测试计划：
> "在 <https://www.saucedemo.com> 上进行探索性测试，发现存在哪些流程，建议一组按功能区域划分的测试"
`browser-test:author` 将导航网站，识别不同的用户流程，并返回按区域分组的测试场景的优先级列表 — 在编写单个测试用例之前。这更耗时，但会发现您可能没有想到要查找的覆盖范围缺口。
## 要求
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
- [Playwright MCP 服务器](https://github.com/microsoft/playwright-mcp) 配置在您的项目的 `.mcp.json` 中：
### 使用最强大的模型
作者，精炼器和编译器技能涉及复杂的逐步推理 — 选择选择器，诊断不稳定行为，生成稳定的 Playwright 代码。输出质量直接随模型能力而变化。**尽可能使用 Opus。**
要在 Claude Code 中切换模型，请在提示符下使用 `/model` 命令：
```
/model claude-opus-4-8
```
或在启动会话之前将其设置为默认：
```bash
export ANTHROPIC_MODEL=claude-opus-4-8
claude
```
您可以为运行稳定测试的 `browser-test:runner` 切换到更快，更便宜的模型（例如 `claude-sonnet-5` 或 `claude-haiku-4-5`），其中任务是执行而不是推理。但是，对于创作，精炼和编译，投资 Opus 可以通过更少的精炼周期和更强大的生成选择器获得回报。
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser", "chrome"]
}
}
}
```
## 安装
技能作为 Claude Code 插件提供。从此仓库定义的市场安装它们。
### 从市场（推荐）
在 Claude Code 会话中添加市场并安装插件：
/plugin marketplace add Autodesk/claude-browser-test-skills
/plugin install browser-test@browser-test-skills
`browser-test` 是插件名称；`browser-test-skills` 是市场名称（来自 `.claude-plugin/marketplace.json`）。安装后，四个技能可作为 `browser-test:author`，`browser-test:refiner`，`browser-test:compiler` 和 `browser-test:runner` 使用。
### 从本地检查（开发）
要尝试技能而无需发布，请将本地目录添加为市场：
/plugin marketplace add /path/to/claude-browser-test-skills
/plugin install browser-test@browser-test-skills
### 验证插件
在发布更改之前，请从仓库根目录验证清单和技能前置信息：
```bash
claude plugin validate .
```
## 项目设置
技能期望您的项目具有：
```
your-project/
├── .mcp.json # Playwright MCP 服务器配置
├── tests/e2e/
│ ├── conventions.md # 全局测试约定
│ └── {area}/
│ ├── conventions.md # 区域特定约定
│ └── {test-name}.md # 测试用例文件（作者/精炼）
└── playwright-tests/
├── playwright.config.ts
├── utils/
│ ├── INVENTORY.md # 实用工具库存（编译器自动生成）
│ └── *.ts # 共享测试实用工具
├── fixtures/ # 测试数据和凭证
└── journeys/{area}/
├── INVENTORY.md # 区域特定库存（编译器自动生成）
└── *.spec.ts # 编译的测试文件
```
### 实用工具库存
`browser-test:compiler` 技能自动生成 `INVENTORY.md` 文件以跟踪可用的实用工具：
- **`playwright-tests/utils/INVENTORY.md`** — 所有测试区域可用的全局实用工具
- **`playwright-tests/journeys/{area}/INVENTORY.md`** — 特定区域实用工具
这些文件在首次编译时创建，并在提取新实用工具时更新。编译器使用它们避免重复现有的实用工具并为重复模式提出提取。
### 约定文件
技能依赖于约定文件来编码项目特定的模式：
- **`tests/e2e/conventions.md`** — 全局规则：会话管理，等待策略，交互模式，功能区域定义
- **`tests/e2e/{area}/conventions.md`** — 特定区域流程：登录序列，人员工作流，共同 UI 模式
从最小的约定开始，让精炼器在发现模式时逐步建立。
## 用法
### 编写新测试
> "编写一个测试，以验证 Clamp 组件的物料清单（BOM）显示在从所有项目页面导航后恰好 6 个直接子项。"
Claude 调用 `browser-test:author`，执行浏览器探索性运行并生成 Markdown 测试用例。
### 稳定测试
> "精炼物料清单测试"
Claude 调用 `browser-test:refiner`，重复运行测试，识别故障模式并更新测试用例和约定，直到连续通过 N 次。
### 运行测试
> "运行物料清单测试"
Claude 调用 `browser-test:runner`，忠实地执行测试并报告通过/失败并提供证据。
### 编译到 Playwright
> "编译物料清单测试"
Claude 调用 `browser-test:compiler`，在实时浏览器中重放测试，从新鲜的可访问性快照中记录选择器并生成 `.spec.ts` 文件。
生成的 Playwright 规范可以像其他 Playwright 测试一样集成到管道中，无需进一步依赖 LLM。
## 编译测试失败时
如果 `.spec.ts` 测试在 CI 或本地失败，请遵循此决策树诊断是产品错误还是测试质量问题。
```mermaid
flowchart TD
A([".spec.ts 在 CI 或本地失败"]) --> B["使用 browser-test:runner 运行 Markdown 测试"]
B --> C{运行器结果？}
C -->|通过| D["编译\nbrowser-test:compiler"]
C -->|失败| G["检查运行器失败报告\n（步骤，截图，预期 vs. 实际）"]
D --> E{规范通过\n编译后？}
E -->|是| F(["已解决 — 选择器漂移"])
E -->|否| H["稳定 Markdown\nbrowser-test:refiner"]
H --> I["编译\nbrowser-test:compiler"]
I --> J(["已解决 — 测试更新"])
G --> K{一致性故障\n跨 2 次运行？}
K -->|是| L(["产品错误 — 提交回归"])
K -->|否| B
```
### 步骤 1 — 使用 `browser-test:runner` 运行 Markdown 测试
> "运行物料清单测试"
运行器执行 **Markdown 源** 对抗实时应用，使用 playwright-mcp。此操作将编译的工件与底层测试逻辑分离。
| 运行器结果 | 含义 | 下一步 |
|---|---|---|
| **通过** | 应用程序正常；编译的 `.spec.ts` 已过时或选择器漂移 | 参见 [修复过时的编译测试](#修复过时的编译测试) |
| **失败** | 功能本身已损坏或测试逻辑有缺陷 | 参见 [诊断产品错误](#诊断产品错误) |
---
### 修复过时的编译测试
Markdown 测试通过，但 `.spec.ts` 失败。编译文件中的选择器或时序可能已漂移到当前 UI。
**尝试编译** — 这是最便宜的修复：
> "编译物料清单测试"
`browser-test:compiler` 在实时浏览器中重放测试并重新生成所有选择器，从新鲜的可访问性快照中。运行新的 `.spec.ts` 以确认它通过。
**如果编译后的规范仍然失败** ，Markdown 测试本身已变得不稳定或 UI 已更改到需要更新步骤的地步。先稳定，然后再编译：
1. > "精炼物料清单测试"
`browser-test:refiner` 重复运行 Markdown 测试，识别故障模式并更新测试用例和约定，直到连续通过 N 次。
2. > "编译物料清单测试"
一旦 Markdown 稳定，再次编译以生成新的 `.spec.ts`。
---
### 诊断产品错误
Markdown 测试失败 — 运行器无法完成步骤或断言不成立。查看运行器的失败报告：
- **哪一步失败了？** 运行器报告确切的步骤和它观察到的内容。
- **截图证据** — 运行器在失败点捕获截图。
- **预期 vs. 实际** — 将测试用例中的通过条件与浏览器显示的内容进行比较。
如果您确认它是回归，请在产品上提交错误。一旦部署修复，请重新运行 Markdown 测试以确认恢复，然后如果也需要更新编译的 `.spec.ts`。
> **注意：** 如果运行器结果不明确（间歇性失败，环境问题），请在得出结论之前再次运行它。两次运行的一致性失败是可靠的信号。
