Playwright Pro

大多数项目的推荐顺序：

1. /pw:init          → 脚手架化配置、CI 流水线和第一个冒烟测试
2. /pw:generate      → 根据你的规范或 URL 生成测试
3. /pw:review        → 验证质量并标记反模式      ← 始终在生成后运行
4. /pw:fix <test>    → 诊断并修复任何失败/不稳定的测试  ← 当 CI 变红时运行

验证检查点：

• 在 /pw:generate 之后 — 在提交之前始终运行 /pw:review；它会自动捕获选择器反模式和缺失的断言。
• 在 /pw:fix 之后 — 在本地重新运行整个套件 (npx playwright test) 以确认修复没有引入回归。
• 在 /pw:migrate 之后 — 在停用 Cypress/Selenium 测试之前运行 /pw:coverage 以确认与旧套件的一致性。

示例：生成 → 审查 → 修复

# 1. 根据用户故事生成测试
/pw:generate "As a user I can log in with email and password"

# 已生成：tests/auth/login.spec.ts
# → Playwright Pro 使用 auth 模板创建文件。

# 2. 审查生成的测试
/pw:review tests/auth/login.spec.ts

# → 标记：一个测试使用了 page.locator('input[type=password]') — 建议使用 getByLabel('Password')
# → 已自动应用修复。

# 3. 在本地运行以确认
npx playwright test tests/auth/login.spec.ts --headed

# 4. 如果测试在 CI 中不稳定，进行诊断
/pw:fix tests/auth/login.spec.ts
# → 识别缺失的网络优先 (web-first) 断言；将 waitForTimeout(2000) 替换为 expect(locator).toBeVisible()

金科玉律

1. 优先使用 getByRole() 而非 CSS/XPath — 对标记更改具有弹性
2. 绝不使用 page.waitForTimeout() — 使用网络优先断言
3. expect(locator) 会自动重试；expect(await locator.textContent()) 不会
4. 隔离每个测试 — 测试之间不共享状态
5. 在配置中使用 baseURL — 零硬编码 URL
6. 重试：CI 中 2 次，本地 0 次
7. 追踪：'on-first-retry' — 丰富的调试信息且不降低速度
8. 优先使用 Fixture 而非全局变量 — 使用 test.extend() 处理共享状态
9. 每个测试一个行为 — 可以包含多个相关的断言
10. 仅模拟外部服务 — 绝不模拟你自己的应用

选择器优先级

1. getByRole()        — 按钮、链接、标题、表单元素
2. getByLabel()       — 带有标签的表单字段
3. getByText()        — 非交互式文本
4. getByPlaceholder() — 带有占位符的输入框
5. getByTestId()      — 当不存在语义化选项时
6. page.locator()     — 作为最后手段的 CSS/XPath

包含内容

• 9 个带有详细分步指令的技能
• 3 个专门的 Agent：test-architect、test-debugger、migration-planner
• 55 个测试模板：auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility
• 2 个 MCP 服务 (TypeScript)：TestRail 和 BrowserStack 集成
• 智能钩子：自动验证测试质量、自动检测 Playwright 项目
• 6 份参考文档：金科玉律、选择器、断言、Fixture、陷阱、不稳定测试
• 迁移指南：Cypress 和 Selenium 映射表

集成设置

TestRail（可选）

export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="your-api-key"

BrowserStack（可选）

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"

快速参考

请参阅 reference/ 目录获取：

• golden-rules.md — 10 条不可逾越的规则
• locators.md — 完整的选择器优先级及速查表
• assertions.md — 网络优先断言参考
• fixtures.md — 自定义 Fixture 和 storageState 模式
• common-pitfalls.md — 前 10 名错误及修复方案
• flaky-tests.md — 诊断命令和快速修复

查看 templates/README.md 获取完整的模板索引。