# Playwright E2e Builder

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

- Skill: `ruhedanghaoyigexuesheng/playwright-e2e-builder` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add ruhedanghaoyigexuesheng/playwright-e2e-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruhedanghaoyigexuesheng/playwright-e2e-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ruhedanghaoyigexuesheng (https://skillmd.com/u/ruhedanghaoyigexuesheng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ruhedanghaoyigexuesheng/playwright-e2e-builder

---


# 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 — 项目画像

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

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

## 阶段 B — 测试蓝图

```bash
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` | 中文汇报 |

目录约定：

```text
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）：

```ts
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](references/quality-matrix.md)。

## 阶段 D — 质量验收

```bash
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](references/artifact-contract.md)