版本：v1.0 | 适用阶段：规划期 → MVP → 完整系统

---

一、总体架构设计

1.1 模块划分

系统由五个核心层组成，各层职责清晰、单向依赖：

┌──────────────────────────────────────────────────┐
│              前端操作层（测试人员界面）               │
│  上传文档 / 输入描述 / 查看报告 / 触发执行            │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────┐
│           用例管理模块（Test Case Hub）             │
│  文档解析 → LLM 生成用例 → Gherkin 存储 → 版本管理  │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────┐
│         脚本生成引擎（Script Generation Engine）    │
│  用例驱动生成 / 录制回放转换 / Swagger → API 脚本    │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────┐
│          执行引擎（Execution Engine）               │
│  Playwright Test Runner / 并行调度 / 环境隔离       │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────┐
│         报告服务 + CI 适配层（Reporting & CI）      │
│  Allure / Playwright HTML Report / GH Actions     │
└──────────────────────────────────────────────────┘

1.2 技术栈建议

层级	选型	理由	落地难度
UI 自动化框架	Playwright + TypeScript	前文选型结论，稳定性最优	低
API 自动化	Playwright APIRequestContext	与 UI 脚本共享 context/token，无需引入新框架	低
BDD 格式支持	@cucumber/cucumber + playwright	与 Gherkin 用例直接衔接	中
LLM 接入	Claude API / 通义千问 / DeepSeek API	成本低、无需自建、中文效果佳	低
文档解析	mammoth（Word）/ pdf-parse（PDF）/ marked（MD）	全开源，轻量	低
用例存储	Git 仓库（.feature 文件）	版本可追溯，无需额外数据库	低
报告	Allure Report + Playwright HTML	Allure 提供趋势图，Playwright HTML 提供截图/录屏	低
CI	GitHub Actions / GitLab CI	原生支持，免费额度充足	低
告警通知	企微 Webhook / SMTP	官方支持，免费	低

1.3 数据流与交互描述

用例生成流

测试人员将需求文档（Word/PDF/MD/文本）上传到用例管理模块。模块调用文档解析库提取纯文本，拼装 Prompt 后调用 LLM API，返回结构化 JSON 格式的测试用例（含前置条件、步骤、预期结果、优先级）。系统同时生成对应的 Gherkin .feature 文件并提交到 Git 仓库。

脚本生成流

以 .feature 文件为输入，脚本生成引擎将 Gherkin 步骤再次送入 LLM，生成对应的 Playwright Step Definitions（TypeScript）和 POM 页面对象。生成的代码经过静态检查（tsc --noEmit）后输出到 tests/ 目录。

执行流

CI 触发（PR / 定时 / 手动）→ 安装依赖 → 执行 playwright test → 收集结果 → Allure 生成报告 → 上传 Artifact → 发送告警（仅失败时）。

---

二、各功能模块详细实现方案

2.1 测试用例辅助模块

工具对比

方案	描述	优点	缺点	落地难度	适用规模
LLM API（推荐）	自建轻量服务，调用云端 API	零部署成本，效果最好，可定制 Prompt	需网络，有调用费用	低	任意规模
TestRail + AI 插件	商业用例管理平台，付费 AI 功能	UI 成熟，管理方便	商业付费，$35+/月/人	低	中大型团队
LangChain + 本地模型	本地部署 Ollama + Qwen/Llama	数据不出境	需 GPU，维护成本极高，已排除	高	已排除
纯规则引擎	正则匹配关键词生成模板	零成本，稳定	覆盖率极低，泛化差	低	不推荐

推荐方案：轻量 LLM API 服务

采用一个极简 Node.js/Python 服务（或直接在 CI 脚本中实现），核心 Prompt 设计如下：

系统角色：你是一名资深 QA 工程师。
任务：根据以下需求描述，生成结构化测试用例，并同时输出 Gherkin 格式。
输出格式：严格 JSON，包含 id、title、priority（P0/P1/P2）、
preconditions（数组）、steps（数组，含 action 和 expected）、
gherkin（Feature/Scenario 完整字符串）。
需求描述：{用户输入或文档提取的文本}

LLM API 成本估算（按月）

以中等规模团队（5 名测试，每天生成 20 份用例文档，每份约 2000 token 输入 + 3000 token 输出）为例：

模型	单价（输入/输出，per M token）	月消耗 token	月费用估算
Claude Haiku 3.5	$0.8 / $4	~150M	约 $8
DeepSeek V3	$0.27 / $1.1	~150M	约 $5
通义千问 Plus	¥0.5 / ¥2 per M	~150M	约 ¥40

推荐：DeepSeek V3 API 作为主力（成本最低，中文效果优秀），Claude Haiku 3.5 作为备用。

与脚本生成的衔接

用例生成后输出两个产物：

1. testcases/TC-001.json：结构化数据，供人工 review 和系统管理
2. features/login.feature：Gherkin 文件，直接作为脚本生成引擎的输入

---

2.2 脚本生成模块

2.2.1 自然语言 / Gherkin → Playwright 脚本

推荐方案：LLM API（非规则引擎）

规则引擎只能处理有限的预定义操作词（点击、输入、断言），遇到稍复杂的业务描述（"验证购物车金额合计正确"）就无法处理。LLM 对自然语言的理解深度远超规则引擎，且代码生成质量可控。

示例工作流

输入（Gherkin Step）：
  Given 用户已打开登录页
  When 用户输入账号 "zdytest" 和密码 "Aa1234567+"
  When 用户点击登录按钮
  Then 页面跳转到 "/yosFrontPage"

↓ Prompt 包含：POM 模式要求 + TypeScript + Playwright 语法规范

输出（Step Definition）：
  Given('用户已打开登录页', async ({ loginPage }) => {
    await loginPage.goto();
  });
  When('用户输入账号 {string} 和密码 {string}', async ({ loginPage }, username, password) => {
    await loginPage.fillCredentials(username, password);
  });
  When('用户点击登录按钮', async ({ loginPage }) => {
    await loginPage.clickLogin();
  });
  Then('页面跳转到 {string}', async ({ page }, path) => {
    await expect(page).toHaveURL(new RegExp(path));
  });

输出（Page Object）：
  export class LoginPage {
    constructor(private page: Page) {}
    async goto() { await this.page.goto('/yos-web'); }
    async fillCredentials(username: string, password: string) {
      await this.page.getByPlaceholder(/账号|用户名/i).fill(username);
      await this.page.getByPlaceholder(/密码/i).fill(password);
    }
    async clickLogin() {
      await this.page.getByRole('button', { name: /登录/i }).click();
    }
  }

关键 Prompt 约束（影响代码质量的核心）

• 强制使用语义化选择器（getByRole、getByPlaceholder），禁止 CSS 类名选择器
• 要求所有断言使用 expect 的 web-first assertions
• 强制 POM 结构：操作方法封装在 Page Object，Step Definition 不含直接 DOM 操作
• 要求生成对应的 fixtures.ts 注入 Page Object 实例

生成脚本的准确率预期

经过良好的 Prompt 工程，LLM 生成的脚本约 60–70% 可直接运行，30–40% 需要人工微调（主要是选择器定位精度问题，因 LLM 无法访问真实页面 DOM）。结合"录制回放"补全选择器，综合成本比手工编写低 60% 以上。

2.2.2 录制回放

方案对比

工具	描述	产出代码质量	POM 结构	落地难度	是否免费
Playwright Codegen（推荐）	官方内置，npx playwright codegen <url>	中（选择器较准）	无，需手动重构	低	免费
Chrome Recorder + Puppeteer	Chrome DevTools 录制，导出 Puppeteer 脚本	低（大量 XPath/CSS）	无	低	免费
Selenium IDE	浏览器插件，导出 Java/Python	低（强依赖 id/name）	无	低	免费
Testim / Mabl	AI 录制平台，自动维护选择器	高	内置	低	商业付费，$300+/月

推荐方案：Playwright Codegen + LLM 重构

1. 测试人员执行 npx playwright codegen <url> 录制操作，得到原始 flat 脚本
2. 将原始脚本送入 LLM，配合专用 Prompt 将其重构为 POM 结构：
   • 识别页面边界，自动分割成多个 Page Object
   • 将重复的选择器提取为 page 属性
   • 补全 await expect() 断言
3. 输出可维护的 POM 代码

这个"录制 → LLM 重构"的组合是目前成本最低、落地最快的方式，完全免费且不依赖任何第三方服务。

2.2.3 接口自动化（Swagger / OpenAPI → 脚本）

工具对比

工具	描述	与 UI 共享数据	落地难度	免费
Playwright APIRequestContext（推荐）	Playwright 内置，与 UI 脚本同仓库	天然共享 context/token/storage state	低	免费
Postman + Newman	图形化接口测试，CLI 执行	需额外导出/导入，共享麻烦	低	免费（基础）
Swagger Codegen / OpenAPI Generator	从 Swagger 生成 SDK，再封装测试	可通过 fixture 共享	中	免费
HttpRunner	YAML 定义接口测试，支持参数化	独立运行，需桥接	中	免费

推荐方案：OpenAPI → Playwright API 测试脚本

核心思路：解析 Swagger JSON → 提取 endpoint/参数/schema → LLM 生成 Playwright APIRequestContext 测试代码。

与 UI 测试共享数据的方式：

// fixtures.ts - UI 与 API 测试共用同一 fixture
export const test = base.extend<{ apiToken: string; loginPage: LoginPage }>({
  // 通过 API 登录获取 token，UI 测试也可注入 storage state 跳过登录
  apiToken: async ({ request }, use) => {
    const res = await request.post('/api/auth/login', {
      data: { username: process.env.E2E_USERNAME, password: process.env.E2E_PASSWORD }
    });
    const { token } = await res.json();
    await use(token);
  },
});

Swagger 解析 → 脚本生成的简要工作流

1. 拉取 /swagger.json 或 /openapi.yaml
2. 用 swagger-parser 解析，提取 paths、parameters、requestBody、responses 的 schema
3. 按 tags 分组，每个 tag 对应一个 API 测试文件
4. 对每个 endpoint 生成：正常请求用例（200）+ 边界参数用例 + 鉴权失败用例（401）
5. LLM 补全断言逻辑（验证 response schema 字段）

---

2.3 执行与 CI/CD 集成（简述）

此模块按要求暂不深入，仅列出关键配置点：

• 触发方式：PR 触发（on: pull_request）+ 定时（on: schedule: cron）+ 手动（on: workflow_dispatch）
• 并行分片：--shard=1/4 到 4/4，GitHub Actions matrix 并行，无需付费
• 环境隔离：通过 .env.test / .env.staging 切换 baseURL，Playwright config 读取 process.env.ENV
• 浏览器缓存：actions/cache 缓存 ~/.cache/ms-playwright，减少 CI 时间约 2 分钟

---

2.4 报告与通知

报告方案对比

工具	趋势图	截图/录屏	失败分类	部署成本	免费
Allure Report（推荐）	有	支持	支持自定义	静态文件，GitHub Pages 可托管	免费
Playwright HTML Report	无	内置优秀	无自动分类	静态文件	免费
组合使用（最优）	Allure 看趋势	Playwright HTML 看详情	—	GitHub Pages	免费
ReportPortal	强大	支持	AI 分类	需自建服务器	开源免费，运维成本高

推荐：Allure + Playwright HTML 双报告

• Playwright HTML：每次 CI 的详细产物（截图、录屏、trace），上传为 Artifact
• Allure：历史趋势、用例统计、失败率分析，部署到 GitHub Pages（免费）

失败截图/录屏自动挂载配置

// playwright.config.ts
use: {
  screenshot: 'only-on-failure',   // 失败时自动截图
  video: 'retain-on-failure',      // 失败时保留录屏
  trace: 'on-first-retry',         // 第一次重试时录制 Trace
}

Allure 集成只需安装 allure-playwright 并在 reporter 中添加，截图自动附加到对应用例。

告警通知

企微机器人 Webhook 在 CI 最后一步调用：

- name: 企微通知（仅失败时）
  if: failure()
  run: |
    curl -X POST "${{ secrets.WECOM_WEBHOOK }}" \
      -H 'Content-Type: application/json' \
      -d '{
        "msgtype": "markdown",
        "markdown": {
          "content": "### ❌ E2E 测试失败\n
          **分支**：${{ github.ref_name }}\n
          **触发人**：${{ github.actor }}\n
          **报告地址**：${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
        }
      }'

邮件告警使用 dawidd6/action-send-mail Action，免费，支持 SMTP 配置。

---

三、落地路径与优先级

Phase 1（第 1–2 周）：基础框架 + 手工脚本 + CI 报告

目标：跑通完整 CI 流水线，团队建立信心

任务	工作量	交付物
初始化 Playwright + TypeScript 项目	0.5 天	项目骨架（前文已提供）
设计 POM 基础结构 + 公共 fixtures	1 天	pages/、fixtures.ts
手工编写核心业务流程脚本（登录、核心功能 3–5 个）	3 天	tests/ 下核心用例
GitHub Actions CI 配置	0.5 天	.github/workflows/e2e.yml
Playwright HTML + Allure 报告配置	1 天	报告自动发布到 GitHub Pages
企微 / 邮件告警	0.5 天	失败自动通知

落地难度：低
团队要求：1 名有 TypeScript 基础的测试工程师即可

---

Phase 2（第 3–5 周）：录制回放 + 接口脚本生成

目标：提升脚本编写效率，覆盖接口层

任务	工作量	交付物
录制回放流程文档化（Codegen 使用规范）	0.5 天	内部使用手册
编写 LLM Prompt 将 flat 录制代码重构为 POM	2 天	scripts/refactor-codegen.ts 工具脚本
接入 Swagger 解析，生成 API 测试骨架	3 天	tests/api/ 目录 + 生成脚本
UI 与 API 共享 fixture（token、测试账号）	1 天	更新 fixtures.ts
Cucumber/Gherkin 环境搭建（可选，按需）	2 天	BDD 运行环境

落地难度：中
团队要求：需要 1 名熟悉 API 测试的工程师协同

---

Phase 3（第 6–9 周）：需求文档 → 用例 + LLM 生成脚本

目标：实现 AI 辅助的完整闭环

任务	工作量	交付物
文档解析服务（Word/PDF/MD → 纯文本）	2 天	tools/doc-parser/
LLM 用例生成 Prompt 工程 + 测试验证	3 天	tools/case-generator/
Gherkin 输出 + 版本管理规范	1 天	features/ 目录规范
Gherkin → Playwright 脚本生成	4 天	tools/script-generator/
生成脚本静态检查 + 人工 Review 流程	2 天	CI 中加入 tsc --noEmit 检查
完整端到端流程演示与团队培训	1 天	演示文档

落地难度：中高（主要复杂度在 Prompt 工程调优）
团队要求：需要 1 名对 LLM Prompt 有经验的工程师主导

---

里程碑总览

第1周  ██████████ 基础框架 + 手工脚本
第2周  ██████████ CI 流水线 + 报告通知
第3周  ████████   录制回放 + Codegen 重构工具
第4周  ████████   接口自动化 + Fixture 共享
第5周  ████        Cucumber 集成（可选）
第6周  ████████   文档解析服务
第7周  ████████   LLM 用例生成调优
第8周  ████████   Gherkin → 脚本生成
第9周  ████        联调 + 培训 + 文档

---

四、风险与应对

4.1 脚本维护成本（高优先级）

风险描述：UI 经常改版，选择器失效导致大量脚本需要修改，维护成本高于人工测试。

应对策略：

• 强制使用语义化选择器（getByRole、getByText），而非 CSS 类名或 XPath，语义化选择器对 UI 改版的耐受性高 3–5 倍
• POM 集中管理选择器，改版时只改一处
• 为高变更页面增加"选择器健康检查"脚本，CI 中每日执行，主动发现失效

---

4.2 Flaky 测试

风险描述：网络抖动、动画未完成、接口响应慢等导致用例间歇性失败，降低团队信任度。

应对策略：

• Playwright 内置自动等待，禁用 page.waitForTimeout()（硬等待），统一使用 expect(locator).toBeVisible() 等 web-first 断言
• CI 中配置 retries: 2，连续失败 3 次才标记真正失败
• 建立 flaky 测试追踪机制：将重试成功的用例标记为 flaky，定期治理

---

4.3 LLM 生成脚本的准确性

风险描述：LLM 无法访问真实页面，生成的选择器可能不准确，或生成幻觉代码。

应对策略：

• 将 LLM 生成脚本定位为"草稿"而非"成品"，必须经过人工 Review 才能合入
• CI 中加入 tsc --noEmit 检查，语法错误在 Review 前自动拦截
• 提供"先 Codegen 录制 → 再 LLM 重构"的双重保障路径，录制的选择器天然准确，LLM 只负责结构重构
• 建立 Prompt 版本管理，持续迭代优化，记录每个版本的准确率基线

---

4.4 录制代码的可维护性

风险描述：Playwright Codegen 产出的 flat 代码直接使用时，复用性差，选择器可能包含动态属性。

应对策略：

• 制定团队编码规范：录制代码必须经过 LLM 重构为 POM 结构后才能提交
• Codegen 录制时配合 data-testid 属性（与前端团队约定），产出更稳定的选择器
• Code Review Checklist 中增加"是否有直接 DOM 操作在 Step Definition 中"的检查项

---

4.5 团队能力与采纳阻力

风险描述：测试人员不熟悉 TypeScript / Git，学习曲线导致推进缓慢。

应对策略：

• Phase 1 提供完整的脚手架和示例，测试人员只需"填空"而非从零开始
• 提供 Playwright 常用 API 速查表，降低学习成本
• Phase 3 的 LLM 辅助生成，让不熟悉代码的测试人员也能产出脚本草稿
• 指定 1 名工程师作为"自动化负责人"，负责架构维护，其他人员只负责编写/审核用例

---

五、可评估的成功指标

5.1 效率指标

指标	当前基准（假设纯手工）	Phase 1 目标	Phase 3 目标
从需求到首个自动化脚本时长	2–3 天	1 天（手工 POM）	2–4 小时（LLM 辅助）
回归测试执行时间	2 天（手工点击）	30 分钟（并行 CI）	30 分钟（稳定维持）
新脚本编写时间（单功能模块）	—	4 小时	1–2 小时

5.2 质量指标

指标	目标值	说明
脚本稳定性（非 flaky 率）	≥ 95%	连续 10 次执行失败次数 ≤ 1 次
CI 通过率（绿色主干）	≥ 90%	非产品 bug 导致的失败 ≤ 10%
LLM 生成脚本直接可用率	≥ 60%	无需修改直接运行通过
用例覆盖率（核心流程）	100% Phase 1 核心流；≥ 70% 全量 Phase 3	—

5.3 工程效能指标

指标	目标值
CI 平均执行时长	≤ 15 分钟（并行 4 shards）
失败告警到达时间	≤ 5 分钟（CI 结束后）
月度脚本维护工时占比	≤ 20%（相对总测试工时）

5.4 成本指标

项目	预估月成本
LLM API（DeepSeek / Claude Haiku）	¥30–100
GitHub Actions CI 时间（公共仓库）	免费
Allure / GitHub Pages 托管	免费
工具链合计	¥30–100 / 月

---

附录：推荐工具速查

工具	用途	开源/免费	维护状态
Playwright 1.44+	UI + API 自动化	免费	Microsoft 活跃维护
@playwright/test	测试运行器	免费	同上
@cucumber/cucumber	BDD/Gherkin 支持	免费	活跃
allure-playwright	报告生成	免费	活跃
mammoth	Word 文档解析	开源 MIT	活跃
pdf-parse	PDF 文本提取	开源 MIT	活跃
swagger-parser	OpenAPI 解析	开源 Apache 2.0	活跃
DeepSeek API	LLM 用例/脚本生成	商业 API，价格极低	活跃
Claude Haiku 3.5 API	LLM 备用	商业 API	Anthropic 维护
dawidd6/action-send-mail	GitHub Actions 邮件	免费 Action	活跃