版本：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 输出）为例：

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

模型	单价（输入/输出，per M token）	月消耗 token	月费用估算

推荐：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 录制回放

方案对比

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

工具	描述	产出代码质量	POM 结构	落地难度	是否免费

推荐方案：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 → 脚本）

工具对比

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

工具	描述	与 UI 共享数据	落地难度	免费

推荐方案：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 效率指标

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

指标	当前基准（假设纯手工）	Phase 1 目标	Phase 3 目标

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 活跃

工具	用途	开源/免费	维护状态