web-ui-autotest-generator

name	web-ui-autotest-generator
description	从前端和后端源码中生成可维护的 Web UI 自动化测试。适用于分析页面、路由、组件、接口、用户流程，生成 Playwright UI 测试，运行测试，生成中文报告，并自检页面功能和跨页面逻辑是否被独立测试资产覆盖。

Web UI 自动化测试生成器

使用本 skill 可以把一个 Web 项目整理成可执行、可复查、可持续维护的 UI 自动化测试套件。

目标不是只写几条临时脚本，而是先分析前端页面、后端接口、用户流程和 UI 状态，再生成 Playwright 测试、覆盖率清单、执行命令和中文报告。生成后的测试资产应能脱离本 skill 独立运行。

默认技术栈

除非目标仓库已经明确使用其他 UI 测试框架，否则默认使用 Playwright + TypeScript。

默认输出结构：

tests/e2e/
  pages/                 # Page Object 模型
  specs/                 # 按页面或路由组织的测试用例
  fixtures/              # 登录状态、测试数据、接口 mock
  utils/                 # 通用辅助函数
  reports/               # 测试报告和中文总结
playwright.config.ts
ui-test-manifest.json
ui-test-coverage.json

内置资源：

scripts/generate_manifest.py       # 源码扫描，生成 ui-test-manifest.json
scripts/audit_selectors.py         # 选择器稳定性审计，生成 ui-selector-audit.json
scripts/check_coverage.py          # 清单和用例覆盖率检查，生成 ui-test-coverage.json
scripts/analyze_failures.py        # Playwright JSON 报告分析，生成 ui-test-repair-plan.json
assets/templates/                  # Playwright 起始模板
assets/templates/summary.zh-CN.md.template # 中文最终测试报告模板

工作流程

1. 检查项目结构和已有测试工具。
2. 分析前端路由、页面、组件、UI 控件、状态管理和接口调用。
3. 如存在后端代码、OpenAPI、Swagger 或 Apifox 文档，补充分析接口契约。
4. 生成页面、功能、接口和流程清单。
5. 审计选择器稳定性，并记录 data-testid 等改造建议。
6. 生成 Playwright Page Object、fixture、spec 和 CI 脚本。
7. 条件允许时在本地运行测试。
8. 如果测试失败，分析失败原因并修复生成的测试。
9. 按覆盖率规则自检生成结果并输出评分。
10. 生成中文测试报告，说明执行结果、覆盖缺口、选择器风险和后续动作。

生成或评审测试时，按需读取 references/coverage-rubric.md。

编写清单、覆盖率或报告时，按需读取 references/output-contract.md。

脚本化初筛

先使用内置脚本得到稳定的基础扫描结果，再结合项目代码进行人工判断和修正。

生成初始清单：

python3 path/to/web-ui-autotest-generator/scripts/generate_manifest.py --root . --out ui-test-manifest.json --pretty

审计选择器稳定性：

python3 path/to/web-ui-autotest-generator/scripts/audit_selectors.py --root . --out ui-selector-audit.json --pretty

生成测试后检查覆盖率：

python3 path/to/web-ui-autotest-generator/scripts/check_coverage.py --root . --manifest ui-test-manifest.json --selector-audit ui-selector-audit.json --tests-dir tests/e2e --out ui-test-coverage.json --pretty

如果 Playwright 执行失败且已有 JSON 报告，生成修复计划：

python3 path/to/web-ui-autotest-generator/scripts/analyze_failures.py --report tests/e2e/reports/results.json --out ui-test-repair-plan.json --pretty

脚本输出是草稿，需要复核：

• 生成大量测试前，先修正错误的路由、页面和文件映射。
• 如果源码高度动态，补充业务名称、权限信息和接口映射。
• 使用 ui-selector-audit.json 选择更稳定的定位方式，并给出 data-testid 建议。
• 不要静默忽略覆盖缺口；应在 ui-test-coverage.json 中写明原因。

发现规则

从快速本地检查开始：

rg --files

重点识别：

• 包管理器：package.json、lockfile、workspace 文件。
• 前端框架：React、Next.js、Vue、Nuxt、Angular、Svelte、Vite、Umi、qiankun、微前端。
• 路由定义：router 文件、文件路由约定、路由配置、菜单配置。
• 页面根目录：src/pages、src/views、app、pages、routes。
• 复用 UI 组件：弹窗、抽屉、表格、表单、上传器、选择器、标签页、步骤条。
• 接口层：src/api、src/services、请求客户端、生成式客户端、GraphQL 文档。
• 状态与鉴权：store、context、cookie、localStorage、路由守卫、权限校验。
• 现有测试约定：命名方式、fixture、测试 id、mock 风格、CI 脚本。

优先沿用仓库已有风格。如果已有 Playwright，直接扩展现有体系。如果项目已经稳定使用 Cypress，且用户没有指定 Playwright，则跟随 Cypress。

前端分析

建立页面清单。每个页面都应尽量识别：

• 路由路径和路由参数。
• 页面标题或业务名称。
• 访问权限和登录要求。
• 主组件和子组件。
• 可见控件：按钮、链接、标签页、菜单、筛选项、输入框、下拉框、日期选择器。
• 表单字段、校验规则、必填项、禁用态。
• 表格或列表列、行操作、分页、排序、批量操作。
• 弹窗、抽屉、浮层及其提交、取消流程。
• 空态、加载态、错误态、成功态和无权限状态。
• 页面跳转和跨页面流转。
• 页面加载或用户操作触发的接口调用。

优先基于源码和稳定选择器生成测试。如果 UI 元素缺少稳定选择器，使用 getByRole、getByLabel、getByText 等可访问定位方式，并在报告中说明哪些位置适合补充 data-testid。

选择器优先级：

1. data-testid 或项目已有测试 id 约定。
2. 可访问角色和名称。
3. 表单字段 label。
4. 稳定可见文本。
5. 稳定组件属性。
6. 只有没有更好方式时才使用 CSS 选择器。

生成 spec 前先运行 scripts/audit_selectors.py。根据审计结果决定：

• 使用已有稳定选择器生成测试。
• 当可访问信息足够时，优先使用 role、label、text 定位。
• 对缺少稳定选择器的关键元素写入 missingStableSelectors 建议。
• 只有用户同意修改产品代码时，才补充 data-testid。

核心流程不要悄悄使用脆弱选择器。无法避免时，必须在最终中文报告中说明。

后端与接口分析

使用后端代码、OpenAPI、Swagger 或 Apifox 文档增强 UI 测试。

提取：

• 接口方法和路径。
• 请求参数、body 结构和必填字段。
• 响应字段和业务状态。
• 错误码和校验信息。
• 鉴权方式和角色要求。
• 数据生命周期约束，例如创建 -> 列表 -> 详情 -> 更新 -> 删除。

把接口映射回 UI 行为：

页面加载 -> 列表/详情接口
搜索/筛选 -> 查询接口
新增/编辑表单 -> 创建/更新接口
删除/批量操作 -> 变更接口
下载/导出 -> 文件接口
路由跳转 -> 详情页或子页面接口

如果没有后端代码，从前端接口客户端推断契约，并在必要时使用 route mock。

清单优先

生成大量测试前，先创建或更新 ui-test-manifest.json。

清单应描述：

• 页面和路由。
• 每个页面的功能项。
• UI 元素和操作。
• 接口依赖。
• 跨页面流程。
• 建议测试场景。
• 已覆盖和缺失项。

把清单作为生成和评审的事实来源。清单错误时，先修正清单，再扩展测试。

测试生成规则

按页面和用户流程生成测试。

创建新的 Playwright 文件时，使用 assets/templates/ 作为起点：

• page-object.ts.template：Page Object 类。
• page-spec.ts.template：页面级测试。
• playwright.config.ts.template：项目没有 Playwright 配置时使用。
• auth-fixture.ts.template：需要鉴权但项目登录方式不明确时使用。
• package-scripts.json.template：补充 npm scripts 时使用。
• github-actions-e2e.yml.template：补充 GitHub Actions CI 时使用。
• summary.zh-CN.md.template：编写最终中文测试报告时使用。

每个业务页面通常应覆盖：

• 页面可以正常加载。
• 核心可见控件渲染。
• 主列表、表格或主要内容渲染。
• 搜索、筛选、重置流程。
• 支持新增时覆盖新增流程。
• 支持编辑时覆盖编辑流程。
• 支持删除或危险操作时覆盖确认与结果。
• 支持详情或跳转时覆盖导航流程。
• 必填字段和表单校验错误。
• 接口失败或空态。
• 相关的无权限或未登录状态。

跨页面流程应生成场景 spec，不要在单页面测试中重复堆叠：

登录 -> 新建实体 -> 搜索实体 -> 打开详情 -> 编辑实体 -> 回到列表验证 -> 删除实体

避免脆弱测试：

• 不断言用户看不到的实现细节。
• 不依赖任意固定等待。
• 除非 fixture 明确创建数据，否则不依赖顺序敏感的数据。
• 不绑定生成式 CSS 类名。
• 如果应用支持 i18n，不假设固定中英文文本，应检查语言文件。

使用确定性测试数据：

• 优先使用 API 做 setup 和 teardown。
• 测试数据名称使用时间戳或生成 ID 保持唯一。
• 创建的数据要隔离并清理。
• 如果清理有风险，危险场景优先使用 mock。

Page Object 规则

重复交互和稳定页面语义应放入 Page Object。

好的 Page Object 暴露用户语义动作：

await userListPage.search({ name: 'Alice' })
await userListPage.createUser(data)
await userListPage.deleteUser('Alice')

不要把底层选择器作为主要接口，除非确实需要。

Page Object 应包含：

• goto
• 核心 locator
• 常用用户动作
• 页面 ready 断言
• 表格、表单、弹窗的小型辅助方法

场景特有断言保留在 spec 中，可复用的页面就绪断言放在 Page Object 中。

鉴权策略

如果页面需要登录：

1. 优先复用项目已有鉴权 helper。
2. 优先使用 Playwright storageState fixture。
3. 如果后端支持测试登录接口，用接口完成登录准备。
4. 如果没有稳定测试账号，生成带占位说明的测试，并在报告中标记为需要人工补充。

不要写入真实生产账号或密钥。

执行

新增或复用脚本：

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:report": "playwright show-report"
  }
}

条件允许时运行：

npx playwright test

如果应用需要开发服务器，使用仓库标准 dev 命令启动，并按需配置 Playwright webServer。

如果依赖缺失且网络不可用，仍然生成测试套件，并在中文报告中明确写明未执行原因。

失败修复循环

测试失败时，先做短循环修复，避免只留下原始失败。

1. 使用 JSON reporter 运行 Playwright。
2. 用 scripts/analyze_failures.py 生成 ui-test-repair-plan.json。
3. 将失败归类为：选择器、超时、断言、鉴权、导航、接口、测试数据或未知。
4. 优先修复出现最多的失败类型。
5. 重跑受影响 spec 或完整测试套件。
6. 重新生成 ui-test-coverage.json。

修复建议：

• 选择器失败：改进 Page Object locator，补充稳定选择器建议，只有获得许可时才改产品代码的 data-testid。
• 超时失败：等待用户可见的页面就绪、接口响应或加载态消失。
• 断言失败：断言稳定的用户可见结果，不断言实现细节。
• 鉴权失败：补充 storage state、测试登录 fixture 或账号需求说明。
• 接口/数据失败：补充确定性 setup、route mock 或 cleanup helper。

当测试通过，或遇到必须由用户提供账号、环境、业务规则的明确阻塞时，停止修复循环。

CI/CD 产物

生成后的测试应能脱离本 skill 独立运行。

如果项目使用 npm scripts，新增或合并：

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:ci": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:report": "playwright show-report"
  }
}

如果项目使用 GitHub Actions，复制并调整 assets/templates/github-actions-e2e.yml.template 到 .github/workflows/e2e.yml。

其他 CI 系统也应保持同一契约：

• 安装依赖。
• 安装 Playwright 浏览器。
• 提供 E2E_BASE_URL 和鉴权密钥。
• 运行 npm run test:e2e:ci。
• 上传 HTML、JSON、JUnit、trace 等报告产物。

自检

生成后必须先自检，再交付。

首次生成测试后运行 scripts/check_coverage.py，修复后再次运行。

检查：

• 每个发现到的路由是否至少有一个加载或渲染测试。
• 每个主要按钮或动作是否有测试场景，或有明确排除原因。
• 每个表单是否覆盖必填校验和至少一个成功路径。
• 列表页是否覆盖搜索、重置、分页和空态。
• 危险操作是否覆盖确认、取消和结果验证。
• 是否覆盖接口失败或后端错误状态。
• 重要跨页面流程是否覆盖。
• 测试套件是否能独立运行。
• 选择器是否可维护。
• 测试数据 setup 和 cleanup 是否清晰。

写入 ui-test-coverage.json，包含已覆盖项和缺失项。缺失项可以存在，但必须写明原因。

覆盖率报告应包含：

• 总体评分。
• 页面覆盖率。
• 功能覆盖率。
• API 覆盖率。
• 跨页面流程覆盖率。
• 存在 ui-selector-audit.json 时，包含选择器稳定性评分。

中文报告

最终面向人阅读的测试报告必须使用中文。写入 tests/e2e/reports/summary.md 时，使用 assets/templates/summary.zh-CN.md.template。

报告必须包含：

• 生成了哪些文件。
• 覆盖了哪些页面和路由。
• 生成的测试数量。
• 重新执行命令。
• 如果执行过测试，写明测试结果。
• 覆盖缺口。
• 总体评分和各维度评分。
• 选择器稳定性评分和主要选择器建议。
• 如果测试失败，写明失败修复摘要。
• 仍需人工提供的测试账号、环境变量或业务规则。

机器可读产物包括：

• Playwright HTML report。
• CI 需要时生成 JUnit XML。
• ui-selector-audit.json。
• ui-test-coverage.json。
• 失败时生成 ui-test-repair-plan.json。
• 中文 Markdown 总结：tests/e2e/reports/summary.md。

完成标准

任务只有在以下条件满足时才算完成：

• 测试套件文件已经生成。
• 清单、选择器审计和覆盖率报告已经存在。
• 测试已执行并修复，或报告了明确阻塞原因。
• 已提供可独立运行的本地或 CI 命令。
• 用户可以根据中文报告中的命令重新运行测试。