playwright-e2e-builder

name	playwright-e2e-builder
description	以四阶段 QA 蓝图方式为 Web 项目交付 Playwright UI 自动化资产。产出项目画像、测试蓝图、定位健康度、质量评分卡与运行分诊报告。当用户提到 UI 自动化蓝图、Playwright 质量门禁、定位健康、测试评分卡、运行分诊时使用。

Playwright UI 自动化 · 蓝图交付器

本 Skill 采用 画像 → 蓝图 → 落地 → 验收 四阶段交付，而非「扫描清单六步闭环」。

默认 Runner：Playwright + TypeScript
默认资产根目录：qa/ui-automation/
默认配置：playwright.ui.config.ts

Skill 路径：.cursor/skills/playwright-e2e-builder/

四阶段交付

阶段	动作	产出
A 画像	profile_project.py	.qa/profile.json
B 蓝图	build_blueprint.py	e2e-blueprint.json + locator-health.json
C 落地	Agent 写代码	qa/ui-automation/**
D 验收	运行 + quality_gate.py + triage_runs.py	quality-scorecard.json + run-triage.json + stakeholder-brief.md

阶段 A — 项目画像

python3 .cursor/skills/playwright-e2e-builder/scripts/profile_project.py \
  --workspace . --emit .qa/profile.json --indent

记录 UI 栈、路由模块、API 模块、鉴权信号与推荐目录，不生成用例。

阶段 B — 测试蓝图

python3 .cursor/skills/playwright-e2e-builder/scripts/build_blueprint.py \
  --workspace . \
  --blueprint-out e2e-blueprint.json \
  --locator-out locator-health.json \
  --indent

• e2e-blueprint.json：screens / widgets / endpoints / journeys / candidateCases
• locator-health.json：定位健康指数与 data-qa 改造建议

大规模写 case 前，先与用户确认 blueprint 中的 urlPath 与业务命名。

定位策略（与通用 Playwright 指南不同，本 Skill 优先 data-qa）：

1. data-qa（本 Skill 推荐前缀）
2. ARIA role + accessible name
3. label / placeholder
4. 稳定文案
5. 结构选择器（必须在 brief 中标注风险）

阶段 C — 资产落地

自 assets/templates/ 生成：

模板	目标
playwright.ui.config.ts.template	根目录 Playwright 配置
screen-model.ts.template	工厂函数式 Screen Model
case.spec.ts.template	带 test.step 的分步用例
global-setup.ts.template	登录 / storageState
npm-scripts.fragment.template	package.json 脚本片段
ci-ui-automation.yml.template	CI 工作流
stakeholder-brief.zh.template	中文汇报

目录约定：

qa/ui-automation/
  cases/              # *.spec.ts
  screen-models/      # 页面交互封装
  support/            # fixtures / helpers
  artifacts/          # run-output.json、html 报告
playwright.ui.config.ts

Screen Model 用 工厂函数（非 Class Page Object）：

export function userListScreen(page: Page) {
  return {
    open: async () => { /* ... */ },
    filterBy: async (keyword: string) => { /* ... */ },
  };
}

每个 screen 的 candidateCases 至少覆盖：render、关键 behavior、必要 validation / session-guard。

跨 screen 旅程单独写 cases/journeys/*.spec.ts。

细则见 references/quality-matrix.md。

阶段 D — 质量验收

npx playwright test -c playwright.ui.config.ts

python3 .cursor/skills/playwright-e2e-builder/scripts/quality_gate.py \
  --workspace . \
  --blueprint e2e-blueprint.json \
  --locator-health locator-health.json \
  --case-root qa/ui-automation/cases \
  --emit quality-scorecard.json --indent

python3 .cursor/skills/playwright-e2e-builder/scripts/triage_runs.py \
  --workspace . \
  --run-json qa/ui-automation/artifacts/run-output.json \
  --emit run-triage.json --indent

失败分桶：targeting / timing / expectation / session / routing / network / fixture / misc。

修复循环：分桶修复 → 重跑 → 刷新 scorecard → 更新 qa/ui-automation/artifacts/stakeholder-brief.md。

鉴权与安全

• 复用项目现有登录链路或 global-setup.ts
• 使用 storageState 避免重复登录
• 禁止写入生产账号；未知账号时在 brief 的「待确认」区列出

完成定义

• .qa/profile.json、e2e-blueprint.json、locator-health.json 已生成
• qa/ui-automation/ 下 case 与 screen-model 可独立运行
• quality-scorecard.json 已输出；缺口有 gaps 说明
• 测试已执行或 brief 写明环境阻塞
• stakeholder-brief.md 已写入

JSON 契约：references/artifact-contract.md