playwright-pro

Playwright Pro

使用 Playwright 进行生产级端到端测试。根据用户故事生成测试，采用页面对象模式提升可维护性，使用恰当的定位器策略编写可靠的测试，诊断并修复不稳定的测试，从 Cypress 或 Selenium 迁移，集成 CI/CD，运行视觉回归测试，并执行无障碍审计。强制执行 10 条黄金规则，可消除 90% 的端到端测试故障。

核心能力

• 编写可靠的测试 — 定位器优先使用 getByRole/getByLabel/getByText，采用支持网页优先、自动重试的断言，并遵循 10 条黄金规则。
• 页面对象模型 — 集中管理定位器，提供表达用户意图的方法，并根据 HTML/选择器生成 POM 类。
• 测试生成 — 根据用户故事生成测试规范，覆盖成功路径和错误路径。
• 不稳定测试诊断 — 分析追踪记录，运行有头模式/调试模式，并修复竞态条件和共享状态问题。
• 迁移 — 提供 Cypress/Selenium → Playwright 命令映射和身份验证设置模式。
• CI 集成 — 支持 GitHub Actions、分片、有条件安装浏览器，以及追踪记录/屏幕截图构件。
• 视觉回归与无障碍 — 使用 toHaveScreenshot 基准，并设置 Axe WCAG AA 门槛。

适用场景

• 为 Web 应用编写或整理端到端测试。
• 修复不稳定的测试或诊断仅在 CI 中出现的故障。
• 将测试套件从 Cypress 或 Selenium 迁移过来。
• 添加视觉回归或 WCAG 无障碍门槛。
• 设置 Playwright CI 集成和报告。

先行确认

生成测试前，请确认以下信息。如果有任何一项未知或含糊不清，请先提问，不要自行假设：

• 任务/子技能 — init、generate、fix-flaky、migrate 或 review（决定整个工作流）
• 要覆盖的用户故事或流程 — 测试规范必须断言的成功路径和错误路径（决定测试生成内容）
• 定位器支持情况 — 应用是否提供角色/标签/data-testid（决定定位器策略和 POM 的可靠性）
• 源框架（迁移时） — Cypress 或 Selenium（决定使用哪个命令映射表）

停止规则：只询问最可能改变输出的 2–3 项。如果用户说“直接起草”，则继续操作，并在产出内容顶部列出假设。

子技能

此技能采用复合子技能架构。skills/ 中的每个子技能都负责特定工作流：

子技能	文件	用途
初始化	skills/init.md	在项目中引导配置 Playwright——安装、配置并创建首个测试
生成	skills/generate.md	根据用户故事或页面描述生成测试文件
修复	skills/fix.md	使用追踪分析诊断并修复失败或不稳定的测试
迁移	skills/migrate.md	从 Cypress 或 Selenium 迁移到 Playwright
审查	skills/review.md	审计测试质量、覆盖缺口和测试不稳定迹象
报告	skills/report.md	根据 Playwright JSON 输出生成执行报告
覆盖率	skills/coverage.md	将测试映射到用户故事，并找出覆盖缺口
BrowserStack	skills/browserstack.md	集成 BrowserStack 云服务以进行跨浏览器测试
TestRail	skills/testrail.md	集成 TestRail 以管理测试用例

子技能流程： 初始化 → 生成 → 审查 → 修复（如有需要）；覆盖率 → 生成（填补缺口）；报告 → BrowserStack/TestRail。

工具

工具	用途	命令
test_generator.py	根据用户故事描述生成 Playwright 测试代码	python scripts/test_generator.py --story "..." --page LoginPage --output tests/
flaky_detector.py	分析多次 CI 运行，检测不稳定测试模式	python scripts/flaky_detector.py --results-dir results/ --runs 10 --threshold 0.05
coverage_mapper.py	将测试映射到用户流程，并识别覆盖缺口	python scripts/coverage_mapper.py --tests tests/ --flows flows.json --gaps-only
page_object_generator.py	根据 HTML 或选择器列表生成 Page Object 类	python scripts/page_object_generator.py --html page.html --name LoginPage --route /login
test_analyzer.py	扫描测试文件，查找反模式和质量问题	python scripts/test_analyzer.py tests/ --severity high
test_report_parser.py	将 Playwright JSON 报告解析为摘要	python scripts/test_report_parser.py report.json --top-slow 10

参考资料

加载与任务相符的参考资料——保持此文件精简，按需查阅详细内容：

• references/core-rules-and-patterns.md — 10 条黄金规则、定位器优先级、playwright.config.ts、Page Object Model 类、根据用户故事生成测试，以及共享身份验证设置。编写测试或配置项目时阅读。
• references/playwright-patterns.md — 定位器决策树、网页优先与非重试断言模式、自定义/工作线程 fixture、网络模拟、反模式速查表，以及 CI 分片模式。选择定位器、模拟 API 或构建 fixture 时阅读。
• references/diagnosis-migration-and-ci.md — 不稳定测试的成因与修复方法及诊断命令、Cypress→Playwright 迁移表、GitHub Actions CI、视觉回归、无障碍测试、常见陷阱、最佳实践、故障排查表，以及成功标准。修复不稳定测试、迁移、接入 CI 或审查测试套件时阅读。

范围与限制

此技能涵盖：

• 使用 Playwright 编写、组织和维护端到端测试
• Page Object Model 架构和定位器策略最佳实践
• 不稳定测试诊断、CI 集成和基于 trace 的调试
• 视觉回归测试和 WCAG 无障碍审查

此技能不涵盖：

• 单元测试或独立的组件测试（测试金字塔指南请参阅 engineering/testing-strategy）
• API 契约测试或负载/性能测试（面向 API 的测试请参阅 api-test-suite-builder）
• 测试数据管理、数据库填充或测试 fixture 的工厂模式
• 移动原生应用测试（Appium、Detox）；此技能仅面向 Web 浏览器

集成点

技能	集成方式	数据流
ci-cd-pipeline-builder	E2E 测试在构建和单元测试之后作为流水线阶段运行	流水线配置会触发 playwright test；失败时上传产物（跟踪记录、屏幕截图）
api-test-suite-builder	API 测试验证后端契约；Playwright 测试端到端验证 UI 流程	E2E 套件在同一环境中运行前，API 测试结果会确认端点稳定性
pr-review-expert	PR 审查会检查 UI 更改的测试覆盖率，并指出缺失的 E2E 规范	审查清单会参照 Playwright Pro 黄金规则；指出 waitForTimeout 或原始 CSS 选择器
performance-profiler	性能预算与 E2E 测试相辅相成，用于发现回归问题	性能分析器会识别加载缓慢的页面；Playwright 测试会为标记的路由添加 networkidle 等待或性能断言
observability-designer	测试失败会反馈到可观测性仪表板，用于跟踪不稳定测试	CI 测试结果会导出 JSON 报告；可观测性流水线会持续接收通过/失败/不稳定指标
release-manager	E2E 套件是发布门禁；只有套件全部通过，才能继续部署	发布工作流会调用 Playwright CI 作业；任何测试失败都会阻止创建发布标签