WebUI 自动化测试引擎 v3.0

🚀 WebUI 自动化测试引擎 v3.0

① 认证 → ② 录制 → ③ 执行 → ④ 诊断 → ⑤ 修复 → ⑥ 报告 → ⑦ 构建

一体化 WebUI 自动化测试全栈平台，基于 Playwright 1.60 + 本地 Ollama AI

从录制到自愈闭环，终结"脚本写 1 天，修脚本写 3 天"的时代

标准工作流

复制代码

┌───────────────────────────────────────────────────────────────┐
│                    标准工作流（严格按序）                        │
│   ① npm run capture-auth  →  ② npm run record  →  ③ npm start  │
└──────────────────────────┬────────────────────────────────────┘
                           │
    ┌──────────────────────┴──────────────────────┐
    │               三大核心模块                    │
    │  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
    │  │ 认证管理   │  │  录制器   │  │  测试执行器  │  │
    │  │ · 登录态  │  │ · codegen│  │ · 交互运行  │  │
    │  │ · 智能    │  │ · AI生成 │  │ · 元素排查  │  │
    │  │ · 降级    │  │ · 去噪   │  │ · AI诊断    │  │
    │  └──────────┘  │ · PO生成 │  │ · 修复闭环  │  │
    │                 └──────────┘  │ · Screencast │  │
    │                              └────────────┘  │
    └──────────────────────┬───────────────────────┘
                           │
    ┌──────────────────────┴───────────────────────┐
    │               共享基础设施                      │
    │  ┌──────┐ ┌─────────┐ ┌──────┐ ┌─────────┐  │
    │  │Ollama│ │元素库    │ │三层  │ │定位器    │  │
    │  │AI    │ │修复经验  │ │报告  │ │智能选取  │  │
    │  │客户端│ │持久化    │ │体系  │ │+ 验证   │  │
    │  └──────┘ └─────────┘ └──────┘ └─────────┘  │
    │  ┌──────┐ ┌─────────┐                        │
    │  │日志  │ │构建     │                        │
    │  │系统  │ │部署     │                        │
    │  └──────┘ └─────────┘                        │
    └────────────────────────────────────────────┘

一、认证管理系统 --- 第一步：捕获登录态

bash 复制代码

npm run capture-auth

Playwright storageState API 实现，一次登录，永久复用：

浏览器自动打开（非无头模式）
人工完成登录（账号密码 / 扫码 / 验证码 / MFA 均可）
按 Enter 保存 auth.json（Cookie + localStorage + sessionStorage）
后续所有测试自动加载登录态

1.1 智能降级策略

场景	行为
`auth.json` 不存在	自动降级条件登录（读环境变量账号密码填写）
`auth.json` 已过期	自动 reload 最多 3 次恢复会话
仍为登录页	提示手动登录或重新捕获
空 `auth.json`	检测空壳文件，给出明确警告

1.2 全局 Setup / Teardown

global-setup.js：检查 auth.json 的存在性、大小、生成时长、空壳检测
超过 24 小时给出重新捕获建议
global-teardown.js：测试完成标记输出（可扩展清理逻辑）

1.3 降级条件登录

当 auth.json 不存在或失效时，从环境变量读取账号密码自动填写登录表单：

复制代码

1. 检测到 auth.json 缺失/过期
2. 自动打开登录页
3. 读取 BASE_URL / TEST_USERNAME / TEST_PASSWORD
4. 填写账号密码 → 点击登录
5. 等待跳转到非登录页
6. 保存 auth.json
7. 继续执行测试

最佳实践： 首次使用全程手动登录（支持验证码 / MFA），后续测试自动复用。若登录态过期，系统自动降级重登录。

二、录制引擎 --- 第二步：录制测试脚本

bash 复制代码

npm run record

2.1 模式 A --- 浏览器录制（操作即代码）

复制代码

1. 输入脚本名称 → 2. 输入 URL → 3. 浏览器自动打开
4. 所有操作实时录制为 getBy* 脚本
5. 按 Enter 停止录制
6. (可选) 脚本去噪 + AI 优化
7. 输出可直接运行的 .spec.ts 文件

企业级增强：

跨页面持久化录制（新页签/新窗口无缝衔接）
Ant Design 全组件兼容：Menu / Dropdown / Cascader / TreeSelect / DatePicker / Drawer / Modal / Table
iframe 穿透录制
语义化定位器自动 .first() 降级：解决 SPA 系统中文本重复导致的 strict mode violation
遮挡点击处理 ：智能添加 force: true
录制脚本幂等备份（.backup-{timestamp}.spec.ts）

2.2 模式 B --- AI 需求生成（描述即脚本）

复制代码

1. 选择「AI 生成脚本」
2. 方式一：手动输入需求描述 + URL
   方式二：读取 specs/ 目录的 .md 结构化需求文件
3. AI 自动调 page.ariaSnapshot() 抓取页面交互元素树
4. 生成带语义化定位器的完整脚本
5. 批量生成：相同 URL 只抓取一次快照，多用例并行

2.3 脚本后处理

处理	说明
🧹 去噪	移除录制中相同文本元素的冗余导航点击，保留有效页面跳转
🤖 AI 优化	添加中文注释、expect 断言、waitForURL 等待（严格禁止修改定位器和测试数据）
🔑 认证复用	自动注入 `test.use({ storageState: 'auth.json' })`

2.4 验证码识别

javascript 复制代码

// 自动调用截图 → AI 视觉模型识别 → OCR 兜底
const code = await captcha.recognize('captcha.png');
// 输出: 'A1B2C'

内置 CaptchaRecognizer 模块（src/recorder/captcha.js），双引擎智能降级：

方案	引擎	说明
🥇 首选	Ollama Vision (`llama3.2-vision`)	视觉模型截图识别，文本类验证码效果较好
🥈 降级	Tesseract.js	纯 OCR 备选，对干扰线/扭曲验证码识别率有限

实现状态： 代码已完整实现双降级逻辑（Vision 识别失败自动回退到 Tesseract）。实际识别率取决于验证码图片复杂度（字体变形程度、干扰线密度等），建议在目标系统上实测验证。

2.5 AI 定位器选取 + PO 类生成

bash 复制代码

npm run record → 在录制器菜单中选择「AI 定位器选取」

打开浏览器非无头模式，点击要选取的元素
自动调用 pickLocator() + normalize() 生成最优定位器
实时展示优先级分析（🟢 getByTestId > 🟢 getByRole > 🟡 getByText > 🟠 CSS > 🔴 XPath）
自动生成 PO 类骨架代码
可选 AI 增强：为 PO 类添加业务操作方法

三、测试执行器 --- 第三步：交互式运行测试

bash 复制代码

npm start

不只是 npx playwright test，而是智能交互式执行引擎：

能力	描述
🎯 智能文件选择	自动扫描 `tests/` 目录，交互式勾选要执行的测试文件
🔐 登录态自动检测	启动时检查 `auth.json` 有效性，过期自动降级条件登录
🤖 AI 按需启用	启动时检测 Ollama 可用性，AI 就绪则开启自动驾驶，不可用则优雅降级
🌐 多浏览器支持	Chromium / Firefox / WebKit 三引擎可选
📊 三层报告体系	Playwright 原生报告 + 自定义步骤级报告 + 多次回放对比报告

3.1 元素排查工具（Element Inspector）--- 核心闭环

测试失败后不是抛 log 给你猜，而是开启交互式排查菜单：

复制代码

  失败定位器: getByTitle('运维人员管理asd')
  ═══════════════════════════════════════════════
  1. 回放到元素位置验证（确认元素状态）
  2. 交互式选取新定位器（完整修复流水线）
  3. 查看元素库（智能匹配修复建议）
  4. 退出元素排查，查看报告

选项 1 --- 回放验证

自动加载 auth.json 登录态，无需重复登录
从 spec 文件智能提取导航步骤，逐帧回放到失败位置
验证定位器在当前页面下的可见性
通过则标记为"偶发失败"；失败则确认定位器确实失效

选项 2 --- 六步闭环修复流水线

复制代码

Step 1: 📦 备份脚本 → *.backup-{timestamp}.spec.ts
Step 2: 🚀 自动导航到失败元素位置
Step 3: 🖱️  交互式选取（浏览器非无头，点击正确元素）
Step 4: 📝  自动替换定位器（正则精准匹配）
Step 5: 🔄  重新执行测试验证
Step 6: 💾  记录到元素库（沉淀修复经验）

关键细节：

URL 自动清理 /login 尾缀，避免打到登录页
导航步骤失败时，提示用户在浏览器中手动展开菜单，再按 Enter 继续选取
新定位器自动调用 normalize() 升级为最佳实践（getByRole > getByText > locator）

选项 3 --- 元素库智能匹配

修复过的元素自动入库，按定位器文本关键词智能匹配
支持"精确匹配"和"文本匹配"两级匹配策略
匹配成功后一键应用 + 验证，无需重新选取

3.2 AI 诊断与自动修复

Ollama 本地模型驱动，数据不出网：

模型	用途	能力
`qwen2.5-coder:32b`	脚本生成 + 修复	代码生成能力强，定位器选择精准
`deepseek-r1:14b`	失败诊断	推理能力强，定位器失效根因分析
`llama3.2-vision`	验证码识别	视觉模型，截图识别验证码

AI 诊断流程：

测试失败 → 自动提取失败信息（双路径兜底：summary.json / 终端输出正则）
读取 error-context.md（含 ARIA 快照和源码片段）
调用 AI 分析根因（元素变更 / 页面重构 / 网络超时 / 登录态失效）
输出修复建议（根本原因 + 置信度 + 代码变更）
用户确认后 AI 自动生成修复代码 → 备份 → 写入 → 验证（最多 3 轮）

失败定位器高容错提取：

从 Playwright 错误消息自动提取 getByTitle('xxx') 表达式
若错误消息无定位器，自动从 spec 文件失败行号回读定位器
双路径兜底，确保修复流水线始终有正确的旧定位器

3.3 报告体系

自定义步骤级明细报告

项目	内容
概览统计	通过/失败/跳过数、总耗时、通过率
失败根因分类	8 种自动识别：超时/定位器/Strict Mode/导航/iframe/网络/断言/其他
步骤明细表	每个 click/fill/goto 的状态、耗时
截图画廊	失败步骤的页面截图汇总

多次回放对比报告

稳定性分析：自动识别"始终通过 / 间歇失败 / 始终失败"
步骤级对比矩阵：颜色编码（🟢 通过 / 🔴 失败 / ⚪ 缺失）
失败聚合：所有回放的失败类型分布统计
每列支持打开 Playwright 原生报告（截图 + 视频 + Trace）

Playwright 原生报告

自动通过 npx playwright show-report HTTP 服务打开，避免 file:// 协议下 Trace Viewer 无法加载。

3.4 非交互式测试执行

bash 复制代码

# 自动化运行所有测试（无菜单交互，适用于 CI）
npm run test:auto

# 等同于 run-tests.js 脚本，自动执行 → 生成日志 → 输出摘要

3.5 全量采集能力 --- Trace / 视频 / 错误截图

playwright.config.ts 默认全量采集，每次测试运行自动生成三份工件：

工件	配置	用途
🎞️ Trace (Trace Viewer)	`trace: 'on'`	完整记录每步操作的 DOM 快照、网络请求、控制台日志、时间轴。通过 `npx playwright show-report` 在交互式 Trace Viewer 中回放，逐帧查看操作前后的页面状态
📹 视频	`video: 'on'`	录制整个测试过程的浏览器画面，查看页面跳转、动画、弹窗等视觉变化
🖼️ 错误截图	`screenshot: 'on'`	每一步操作和失败时刻都会截图，在自定义报告中以缩略图画廊形式展示

查看方式：

bash 复制代码

# 测试结束后，执行器中自动弹出选项：
#   1. npx playwright show-report → 启动 HTTP 服务打开 Trace Viewer + 视频回放
#   2. 自定义步骤级报告 → 含截图缩略图画廊 + 失败根因分析
#   3. 对比报告 → 多次运行 Trace/视频 跨列对比

关键细节：

Trace Viewer 必须通过 HTTP 服务（npx playwright show-report）打开，file:// 协议下无法加载
视频为 .webm 格式，可选 ffmpeg 转换为 .mp4
失败步骤自动采集截图路径、错误消息和 ARIA 快照，传递给 AI 诊断模块做根因分析

四、AI Agents 体系

4.1 Test Generator --- AI 脚本生成 Agent

复制代码

src/agents/test-generator.js

基于自然语言描述生成 Playwright 测试脚本
自动抓取页面 ARIA 快照（page.ariaSnapshot()），AI 理解页面结构
支持 API 测试用例自动识别（POST/GET/PUT/DELETE）
占位符智能清理 ：自动检测 your_xxx 占位符并替换为文档中的真实数据
必填测试数据注入：从 .md 需求文件提取"必须使用的测试数据"写入 AI Prompt

✅ 交互集成： 已接入录制器菜单（npm run record → 选项 2「AI 生成脚本」），支持手动输入需求或读取 specs/ 下的 .md 需求文件。详情见[二.2 模式 B](#二.2 模式 B)。

4.2 Test Healer --- AI 自愈 Agent

复制代码

src/agents/test-healer.js

完整修复流程：截图 → 读 ARIA 结构 → 读控制台日志 → LLM 综合分析 → 生成修复方案

方法	功能
`capturePageContext(page)`	截图 + ARIA 快照 + 控制台日志
`diagnose(failureInfo)`	分析根因 + 给出修复建议
`autoFix(page, failureInfo)`	全自动修复流水线
`suggestFix(code, diagnosis)`	基于诊断生成修复后代码
`suggestLocator(selector, html)`	建议新定位器

✅ 交互集成： 已接入执行器修复流水线（npm start → 测试失败后自动调用），支持 AI 诊断 → 生成修复代码 → 备份写入 → 验证闭环（最多 3 轮）。详情见[三.2 AI 诊断与自动修复](#三.2 AI 诊断与自动修复)。

4.3 Test Planner --- AI 测试规划 Agent

复制代码

src/agents/test-planner.js

基于页面 DOM 结构和需求描述生成测试计划
输出 Markdown 格式（场景列表 + 测试步骤 + 预期结果 + 测试数据）
自动保存到 specs/ 目录

⚠️ 注意： 此 Agent 为骨架实现 （72 行），定义了 plan() 和 savePlan() 接口，但尚未集成到交互式菜单中 （runner 和 recorder 均未导入此模块）。当前仅可通过 OpenCode IDE 的 playwright-test-planner Agent 调用。

五、定位器工具集

5.1 交互式定位器选取

bash 复制代码

# 独立运行
node src/utils/locator-picker.js <URL> [authFile]

基于 Playwright 1.59+ 的 pickLocator() + normalize() API：

优先级	类型	说明
🟢 1	`getByTestId()`	最稳定（data-test 属性）
🟢 2	`getByRole()`	语义化定位
🟡 3	`getByText()` / `getByLabel()`	文本直观定位
🟡 4	`getByPlaceholder()`	输入框占位符
🟠 5	CSS 选择器	通用兜底
🔴 6	XPath	不推荐

5.2 定位器验证

复制代码

verifyLocator(url, locator)       → 在目标页面验证定位器可见性
verifyWithContext(specFile, loc)  → 从 spec 提取导航上下文后验证

5.3 批量定位器扫描优化

bash 复制代码

npm run optimize
# 或：node scripts/optimize-locators.js
# 带自动修复：node scripts/optimize-locators.js --fix

扫描所有 spec 文件，识别低质量定位器（CSS/XPath）：

输出每处可优化的代码行 + 改进建议
定位器健康度评分（🟢 ≥80% / 🟡 ≥50% / 🔴 <50%）
类型分类统计（CSS class / CSS id / 复杂 CSS / XPath 等）

5.4 PO 类骨架生成

javascript 复制代码

const poCode = picker.generatePOSkeleton(locators, 'LoginPage');
// 输出：
// export class LoginPage {
//   get usernameInput() { return page.getByRole('textbox', { name: '账号' }); }
//   get passwordInput() { return page.getByRole('textbox', { name: '密码' }); }
//   async load() { await this.page.goto('...'); }
// }

六、Screencast 录屏回放

bash 复制代码

npm start → 主菜单中选择「录制测试操作视频」

使用 Playwright 1.59+ screencast API：

右上角实时显示操作名（fill / click / wait）
被点击元素高亮闪烁
章节标记 + 自定义浮层
关闭浏览器自动停止录制
自动检测 recordVideo 和 screencast 双路径视频文件
可选 ffmpeg 转 MP4

七、构建与部署

7.1 SEA（Single Executable Applications）

bash 复制代码

# 构建 runner 单文件 exe（需 Node.js 20+）
npm run build

# 构建 recorder 单文件 exe
npm run build:recorder

# 构建全部
npm run build:all

构建流程：esbuild 打包 → 生成 SEA blob → 复制 node.exe → postject 注入

7.2 nexe 构建

bash 复制代码

npm run build:nexe          # runner exe
npm run build:nexe:recorder  # recorder exe

八、OpenCode IDE 集成（Agents + MCP）

项目配置了 3 个 OpenCode 子 Agent，支持在 IDE 内直接使用 AI 完成测试工作流：

8.1 playwright-test-generator

创建浏览器自动化测试的 Agent：

读取测试计划 → 设置页面 → 逐步执行操作 → 提取日志 → 生成脚本文件
工具权限：浏览器操作全系列 + 文件读写

8.2 playwright-test-healer

调试和修复失败测试的 Agent：

运行测试 → 识别失败 → 调试器暂停 → 浏览器快照/控制台/网络分析 → 编辑修复 → 验证
工具权限：浏览器诊断 + 文件编辑

8.3 playwright-test-planner

创建测试计划的 Agent：

导航探索 → 分析用户流 → 设计场景（正向/边界/异常） → 保存为 Markdown
工具权限：浏览器探索 + 文件保存

8.4 MCP 配置

json 复制代码

{
  "mcp": {
    "playwright-test": {
      "type": "local",
      "command": ["npx", "playwright", "run-test-mcp-server"],
      "enabled": true
    }
  }
}

九、快速开始

bash 复制代码

# 1. 进入项目
cd Auto_Testing-v1.0

# 2. 一键初始化
npm run init

# 或手动安装
npm install
npx playwright install chromium

# 3. 捕获登录态（首次运行必须先做这一步）
npm run capture-auth

# 4. 录制测试脚本
npm run record

# 5. 运行测试
npm start

参数
用法	说明
npm run clean	交互式确认后清理
npm run clean:force 或 node scripts/clean.js --force	直接清理
node scripts/clean.js --dry-run	预览（不实际删除）
npm run compare	基于已有回放记录生成多次对比报告
npm run report	以 HTTP 服务打开 Playwright 原生报告（Trace Viewer 支持）
注意：清理后目录结构保留，下次运行会自动创建新文件。建议保留最近的 run-* 报告时先用 --dry-run 预览。

环境要求

依赖	要求	说明
Node.js	18+ (推荐 20.x LTS)	运行时环境
Playwright	1.60+	浏览器自动化引擎
Ollama (可选)	任意版本	AI 诊断/生成/修复
ffmpeg (可选)	任意版本	录屏 .webm → .mp4 转换

十、项目结构

复制代码

Auto_Testing-v1.0/
├── src/
│   ├── agents/
│   │   ├── test-generator.js      # AI 脚本生成 Agent (432 行)
│   │   ├── test-healer.js         # AI 自愈 Agent (253 行)
│   │   └── test-planner.js        # AI 测试规划 Agent (72 行，骨架)
│   ├── ollama/
│   │   └── client.js              # Ollama API 封装（生成/流式/视觉/健康检查）
│   ├── recorder/
│   │   ├── index.js               # 录制器（codegen/AI生成/去噪/PO生成）
│   │   └── captcha.js             # AI 验证码识别（Vision + OCR 双降级）
│   ├── reporter/
│   │   ├── custom-reporter.js     # Playwright 自定义 Reporter
│   │   ├── report-generator.js    # 步骤级明细 HTML 报告
│   │   └── compare-generator.js   # 多次回放对比报告
│   ├── runner/
│   │   └── index.js               # 测试执行器（排查/修复/Screencast）
│   └── utils/
│       ├── locator-picker.js      # 定位器选取/验证/元素库/PO生成 (837 行)
│       ├── capture-auth.js        # 登录态捕获工具
│       └── logger.js              # 统一日志模块（级别/轮转/AI交互记录）
├── scripts/
│   ├── init-project.js            # 项目初始化
│   ├── optimize-locators.js       # 定位器批量扫描优化
│   ├── build-sea.js               # SEA 单文件 exe 构建
│   ├── run-tests.js               # 非交互式自动化测试执行
│   ├── debug-playwright-cli.js    # 中文文件名 CLI 调试
│   └── debug-spawn.js             # 中文编码 spawn 调试
├── .opencode/
│   └── prompts/
│       ├── playwright-test-generator.md    # 脚本生成 Agent Prompt
│       ├── playwright-test-healer.md       # 脚本修复 Agent Prompt
│       └── playwright-test-planner.md      # 测试规划 Agent Prompt
├── tests/
│   ├── fixtures/
│   │   ├── global-setup.js        # 全局 Setup（认证状态检查）
│   │   └── global-teardown.js     # 全局 Teardown
│   ├── seed.spec.ts               # 种子脚本（环境 + 降级登录）
│   └── *.spec.ts                  # 测试脚本（含中文名）
├── config/
│   └── default.json               # 应用配置
├── specs/
│   └── *.md                       # 结构化需求文档（AI 生成源）
├── playback-reports/              # 回放报告（summary.json + steps.json + report.html）
├── playwright-report/             # Playwright 原生报告（含 Trace/Video）
├── element-library.json           # 元素库（修复经验持久化）
├── auth.json                      # 登录态文件
├── opencode.json                  # OpenCode IDE Agent 配置
├── playwright.config.ts           # Playwright 配置
└── package.json

十一、配置参考

环境变量 (.env)

变量	说明	默认值
`BASE_URL`	被测系统基础 URL	`http://172.16.21.242:8080/caic/#/caic-web/login`
`AUTH_STORAGE_PATH`	认证文件路径	`./auth.json`
`TEST_USERNAME`	降级登录账号	`admin`
`TEST_PASSWORD`	降级登录密码	`1`
`OLLAMA_HOST`	Ollama 服务地址	`http://localhost:11434`
`OLLAMA_MODEL`	代码生成模型	`qwen2.5-coder:32b`
`OLLAMA_VISION_MODEL`	视觉验证码模型	`llama3.2-vision:latest`
`LOG_LEVEL`	日志级别	`DEBUG`
`LOG_DIR`	日志目录	`./logs`
`LOG_MAX_SIZE`	单文件最大字节	`10485760` (10MB)

Playwright 配置

项	值
浏览器	Chromium / Firefox / WebKit
认证复用	`storageState: './auth.json'`
失败采集	trace + screenshot + video 全量开启
测试超时	120s
操作超时	30s
断言超时	15s
全局重试	1 次 (CI 下 2 次)
视图尺寸	1920x1080

应用配置 (config/default.json)

配置项	默认值	说明
`logging.level`	`DEBUG`	日志级别
`logging.maxSize`	`10485760`	日志轮转阈值
`logging.aiInteractionLogging`	`true`	是否记录 AI 交互详情
`ai.temperature`	`0.2`	AI 生成温度
`ai.maxTokens`	`8192`	最大 Token 数
`ai.timeout`	`120000`	AI 请求超时
`recorder.defaultViewport`	`1920,1080`	录制默认视口
`recorder.enableDenoise`	`true`	启用录制去噪
`runner.timeout`	`180000`	执行超时
`runner.retries`	`1`	失败重试次数
`ffmpeg.enabled`	`true`	启用视频转换

十二、使用场景速查

场景 1：完整工作流（认证 → 录制 → 回放）

bash 复制代码

# 第一步：捕获登录态（仅首次需要，后续自动复用）
npm run capture-auth

# 第二步：录制测试脚本
npm run record          # 模式 1 → 输入脚本名 → 输入 URL → 录制 → 停止

# 第三步：执行回放
npm start               # 选择脚本 → 执行 → 查看报告

场景 2：测试失败 → 元素排查修复

bash 复制代码

npm start → 选中测试文件 → 执行 → 测试失败
# 自动进入元素排查菜单：
#   1 → 回放验证，确认元素是否真的失效
#   2 → 启动修复流水线：备份→导航→选取→更新→验证→入库
#   3 → 查看元素库，智能匹配相同失败
#   4 → 退出，查看报告

场景 3：AI 生成测试脚本

bash 复制代码

npm run record → 选择 2
# 方式 A：手动输入需求描述
# 方式 B：读取 specs/ 下的 .md 需求文件

场景 4：结构化需求文件 → 测试脚本

bash 复制代码

# 1. 编写 specs/ 下的 .md 用例文档（参见 UC-LOGIN-01_登录功能测试.md）
# 2. 运行录制器，选择 AI 生成 → 读取需求文件
# 3. AI 自动解析 TC 步骤 + 预期 + 测试数据 + 环境元数据
# 4. 批量生成多个用例脚本（相同 URL 只抓取一次 ARIA 快照）

场景 5：全量定位器体检

bash 复制代码

npm run optimize
# → 扫描所有 spec 文件，输出低质量定位器 + 替换建议 + 健康度评分

场景 6：多次回放稳定性分析

bash 复制代码

npm start → 多次执行同一脚本 → 菜单中选择"生成对比报告"
# → 步骤级对比矩阵 + 稳定性自动分析（始终通过/间歇失败/始终失败）

场景 7：OpenCode IDE 中使用 Agent

在 OpenCode IDE 中直接使用以下 Agent（需配置 opencode.json）：

/playwright-test-generator --- 创建浏览器测试
/playwright-test-healer --- 调试修复失败测试
/playwright-test-planner --- 创建测试计划

场景 8：构建独立 exe

bash 复制代码

npm run build:all
# → dist/test_runner.exe + dist/script_recorder.exe
# 无需 Node.js 环境，直接双击运行

十三、设计原则

闭环优先 --- 测试失败不是终点，而是修复流水线的起点
经验沉淀 --- 每次修复都入库，单人经验变团队资产
AI 增强不依赖 --- Ollama 可用则自动驾驶，不可用则优雅降级
上下文感知 --- 所有操作都在测试用例上下文中执行
幂等备份 --- 所有修改前先备份，零风险操作
降级优先 --- 认证过期、AI 不可用、页面加载失败，都有降级路径
中文友好 --- 全中文注释 + 中文文件名兼容 + PowerShell 生态适配

版本历史

版本	日期	变更
v3.0.0	2026-06	全面重构：SEA/nexe 构建流水线、OpenCode Agent 集成、MD 需求文件解析、批量 ARIA 快照生成、PO 类生成、验证码识别、Screencast 录屏、定位器批量扫描优化、非交互式自动运行脚本、中文编码调试工具、对比报告生成器、元素库智能匹配
v2.0.0	2026-06	基线版本：元素排查工具闭环、AI 诊断修复、failedLocator 高容错提取、登录态自动恢复、三层报告体系
v1.0.0	2026-05	初始版本：Playwright 基础集成、录制回放

Auto Testing Engine v3.0 --- 终结"测试脚本写 1 天，修脚本写 3 天"的时代。

从录制到自愈，从诊断到构建，一步到位。