测试自动化平台 使用文档

项目概述

本平台由两个子项目组成：

子项目	技术栈	说明
后端	Spring Boot 2.7.3 + MyBatis-Plus + Playwright	后端服务，提供全部业务逻辑 API
前端	Vue 2 + TypeScript + Element UI + ECharts	前端界面，提供可视化操作页面

平台支持两大核心能力：接口自动化测试 和 UI 自动化测试，并提供 AI 辅助用例生成、定时任务调度、测试结果统计等能力。

---

一、接口自动化测试

1.1 功能概述

接口自动化测试模块支持完整的 HTTP 接口测试生命周期：

• 用例管理（增删改查、批量操作）
• 参数动态替换（变量提取与注入）
• cURL 命令导入用例
• Apifox 规范导入
• 定时执行计划（Cron 调度）
• 执行结果记录与统计

---

1.2 核心模块

1.2.1 用例管理

页面入口： 侧边栏 → 接口测试 → 用例列表（/case）

功能列表：

操作	说明
新建用例	点击「新增用例」进入编辑页
搜索用例	支持按 ID、创建人、URL、所属项目、所属模块过滤
执行用例	点击「运行」图标立即执行并查看响应
删除用例	支持单条删除和批量删除（勾选后操作）
编辑断言	在列表行内直接修改一级/二级断言

1.2.2 用例编辑（新增/修改）

页面入口： 用例列表 → 新增用例（/caseadd）

编辑器分区：

cURL 导入

在「cURL 解析」区域粘贴 cURL 命令，点击解析按钮，自动填充：请求方法、URL、Headers、请求体。

参数后置处理（变量提取）

在「后置处理」标签页配置提取规则，格式：变量名_JSONPath表达式。

示例：

• 提取 Token：token_$.data.token
• 提取用户 ID：userId_$.data.id

提取的变量可在后续用例的 Headers / 请求体中通过 _${变量名} 引用。

实时执行与结果预览

右侧面板实时展示：

• HTTP 状态码（绿色=成功，红色=失败）
• 执行耗时（毫秒）
• 响应 Body（JSON 树状查看器）
• 响应 Headers

---

1.2.3 参数替换键（变量管理）

后端接口： /replacekey

用于管理全局变量，实现用例间数据传递。

接口	方法	说明
/replacekey/addReplace	POST	新增/更新替换键
/replacekey/delReplace	POST	删除替换键
/replacekey/replaceKeyList	POST	分页查询替换键列表
/replacekey/getReplaceKeyById	POST	按用例 ID 获取替换键
/replacekey/searchByRkey	POST	按名称检索替换键

---

1.2.4 测试计划（定时调度）

页面入口： 侧边栏 → 接口测试 → 计划列表（/planview）

功能：

操作	说明
新建计划	配置计划名称、关联用例、执行规则（Cron 表达式）
启动计划	创建 Quartz 定时任务，按 Cron 规则自动执行
暂停计划	停止 Quartz 任务，保留配置
编辑计划	修改计划信息（自动重启任务）
删除计划	删除计划及关联任务

计划字段说明：

字段	说明
计划名称	标识名
关联用例	选择需要执行的用例 ID 列表
执行规则	Cron 表达式，通过可视化 Cron 选择器配置
执行类型	1=全部用例，2=指定用例
运行状态	0=暂停，1=运行中

后端接口：

接口	方法	说明
/plan/addplan	POST	新建计划
/plan/startplan	POST	启动计划
/plan/stopplan	POST	暂停计划
/plan/updataplan	POST	更新计划
/plan/delplan	POST	删除计划
/plan/planlist	GET	分页查询计划列表

---

1.2.5 执行结果查询

页面入口： 侧边栏 → 接口测试 → 执行结果（/caseresult）

筛选条件：

• 用例 ID
• 计划 ID
• 执行结果（成功/失败）
• 最近 N 条

结果字段：

字段	说明
用例 ID	关联的测试用例
执行结果	success / fail
响应数据	完整响应 Body（可展开查看 JSON）
执行次数	累计运行次数
失败原因	断言失败时的具体原因
执行时间	用例触发时间

后端接口：

接口	方法	说明
/response/searchbykeys	POST	按条件分页查询结果
/response/selectRunCount	POST	按日期统计执行量（成功/失败/总计）
/response/getSystemCount	GET	获取系统总览数据（用例数/用户数）
/response/getCaseNumByCreater	GET	按创建人统计用例数
/response/getCaseNumByProject	GET	按项目统计用例数
/response/getCaseNumByModule	GET	按模块统计用例数
/response/selectCaseRuntime	GET	获取最慢的 10 条接口耗时

---

1.2.6 工具接口

接口	方法	功能
/utils/curltorequest	POST	cURL 命令转接口用例（自动解析 method/url/headers/body）
/utils/apifoxtolocal	POST	Apifox 接口规范导入为本地用例
/utils/resets	POST	重置验证码

---

1.2.7 接口执行

接口	方法	说明
/test/dotestbybody	POST	按请求体参数执行用例（需传 method/type）
/test/dotestonebyid	POST	按用例 ID 执行

---

1.3 接口自动化整体流程

1. 新建用例
   ├── 手动填写（URL / Method / Headers / Body）
   ├── 粘贴 cURL 自动解析
   └── Apifox 导入

2. 配置断言
   ├── 一级断言（JSONPath 表达式）
   └── 二级断言

3. 配置变量提取（后置处理）
   └── 提取响应值 → 供后续用例引用

4. 手动执行 / 加入测试计划

5. 查看执行结果
   └── 支持历史查询 + 数据统计

---

---

二、UI 自动化测试

2.1 功能概述

UI 自动化测试模块基于 Playwright（Java） 实现，支持 H5 / Android / iOS 三端，提供：

• 测试用例管理（步骤级编排）
• 页面信息管理（被测页面注册）
• 元素选择器管理（复用元素库）
• AI 辅助解析 HTML 提取元素
• AI 自然语言生成测试用例
• 定时执行计划
• 执行结果与截图查看

---

2.2 核心模块

2.2.1 被测页面管理

页面入口： 侧边栏 → UI 自动化 → 页面管理（/uitestpagemanage）

在执行 UI 测试前，需要先注册被测页面（URL）。

字段说明：

字段	必填	说明
页面名称	是	可读名称，如「登录页」
页面 URL	是	完整 URL，如 https://example.com/login

后端接口：

接口	方法	说明
/page-info/addPageInfo	POST	新增页面
/page-info/updatePageInfo	PUT	更新页面信息
/page-info/deletePageInfo	DELETE	删除页面
/page-info/pageInfoList	GET	分页查询页面列表（支持按名称筛选）
/page-info/getPageInfoById	GET	按 ID 获取页面详情

---

2.2.2 元素选择器管理

页面入口： 侧边栏 → UI 自动化 → 元素管理（/uiselectormanage）

为每个页面定义可复用的 UI 元素定位信息。

字段说明：

字段	必填	说明
关联页面	是	元素所属页面
元素名称	是	可读名称，如「登录按钮」
定位表达式	是	CSS 选择器 或 XPath，如 #loginBtn、//button[@type='submit']

后端接口：

接口	方法	说明
/selector-info/addSelectorInfo	POST	新增元素
/selector-info/updateSelectorInfoById	POST	更新元素
/selector-info/deleteSelectorInfoById	POST	删除元素
/selector-info/getSelectorInfoList	POST	分页查询元素列表（支持按页面/名称/定位符筛选）
/selector-info/getSelectorInfoListByPageId	POST	按页面 ID 获取该页面所有元素
/selector-info/parseSelectorByAi	POST	AI 解析 HTML 自动提取元素

---

2.2.3 AI 解析 HTML 提取元素

页面入口： 侧边栏 → UI 自动化 → AI 导入元素（/uiselectoraimport）

使用步骤：

1. 在「关联页面」下拉框选择目标页面
2. 在文本框中粘贴页面 HTML 源码（最大 200KB）
3. 点击「AI 解析」
4. 系统自动识别页面中的可交互元素（按钮、输入框、链接等），生成元素名称和定位表达式
5. 以表格或 JSON 格式预览结果
6. 确认后保存到元素库

---

2.2.4 UI 测试用例管理

页面入口： 侧边栏 → UI 自动化 → 用例列表（/uitestcaselist）

用例列表操作：

操作	说明
搜索	按用例名称、测试平台（H5/Android/iOS）、优先级筛选
展开详情	查看用例包含的步骤列表
编辑	进入步骤编辑页
复制	复制用例及所有步骤
删除	软删除用例

后端接口：

接口	方法	参数	说明
/ui-auto-test-case/page	GET	page, size, casename, testdevice, priority	分页查询 UI 用例
/ui-auto-test-case/list	GET	无	获取全部 UI 用例
/ui-auto-test-case/add	POST	UiAutoTestCaseDto	新增用例（含步骤）
/ui-auto-test-case/update	POST	UiAutoTestCaseDto	更新用例（含步骤）
/ui-auto-test-case/selectByCaseId	POST	{id}	获取用例详情及步骤

---

2.2.5 用例步骤编辑

页面入口： 用例列表 → 新增用例 / 编辑（/uitestcaseadd）

基础信息：

字段	说明
用例名称	可读描述，如「H5 登录成功」
测试平台	H5 / Android / iOS
优先级	高 / 中 / 低

步骤配置（每条步骤）：

字段	说明
步骤名称	描述该步骤用途，如「点击登录按钮」
操作类型	click / input / assert / navigate 等（支持自动补全提示）
目标元素	通过「页面 → 元素」两级联动下拉框选择（来自元素库）
元素序号	若同选择器匹配多个元素，指定第 N 个（从 0 开始）
操作值	input 时填写输入内容；assert 时填写期望值
步骤序号	执行顺序编号（从 1 开始）
截图	开关，执行后是否截图留档（需填截图文件名）

步骤管理操作：

• 在任意步骤前/后插入新步骤
• 删除步骤
• 拖拽调整顺序（序号字段）

---

2.2.6 AI 生成测试用例

页面入口： 侧边栏 → UI 自动化 → AI 生成用例（/uitestcaseaigenerate）

使用步骤：

1. 选择关联的接口测试用例（可选）
2. 选择涉及的页面（多选，从页面库中选取）
3. 用自然语言描述测试场景，如：测试用户输入正确的用户名和密码后能成功登录
4. 点击「AI 生成」
5. 系统结合页面元素信息，自动生成完整步骤列表（包含操作类型、元素、操作值）
6. 确认后保存为测试用例

后端接口： POST /ui-auto-test-case/parseByAi

---

2.2.7 测试执行

后端接口：

接口	方法	说明
/uitest/douitest	POST	按用例 ID 列表执行 UI 测试
/uitest/douitestbyplan	POST	按测试计划 ID 执行 UI 测试
/uitest/sendmail	POST	执行完成后发送邮件 + 飞书通知

执行引擎基于 Playwright Java 1.54，默认使用 Chromium 浏览器。

浏览器安装状态检查：

# 检查安装状态
curl http://localhost:8080/api/playwright/status

# 重新安装
curl -X POST http://localhost:8080/api/playwright/reinstall

---

2.2.8 执行结果查询

页面入口： 侧边栏 → UI 自动化 → 执行结果（/uitestresult）

筛选条件：

• 用例 ID
• 执行结果（成功/失败）
• 执行次数
• 计划 ID

结果展示：

字段	说明
用例 ID	关联的 UI 测试用例
执行结果	1=成功，0=失败（标签颜色区分）
执行时间	本次执行触发时间
关联计划	所属测试计划

展开后查看步骤详情：

字段	说明
步骤执行日志	每步执行的详细日志文本
截图	内嵌图片预览，点击放大
步骤耗时	每步执行时间

后端接口：

接口	方法	说明
/uitest-result/saveresult	POST	保存用例执行结果
/uitest-result/gettestresultbyuitestResult	POST	分页查询执行结果（带筛选）
/uitest-result/getalltestresult	POST	获取全部执行结果
/uitest-step-result/saveStepResult	POST	保存步骤级执行结果（含截图）

---

2.2.9 综合测试计划（接口 + UI）

后端接口： /all-test-plan

用于将接口测试和 UI 测试统一到一个计划中执行。

接口	方法	说明
/all-test-plan/addAllTestPlan	POST	新建综合计划
/all-test-plan/updateAllTestPlan	PUT	更新计划
/all-test-plan/deleteAllTestPlan	DELETE	删除计划
/all-test-plan/getAllTestPlanList	GET	分页查询计划列表（支持按 planType 过滤）
/all-test-plan/getAllTestPlanById	GET	获取计划详情

---

2.3 UI 自动化整体流程

1. 注册被测页面
   └── 维护页面名称 + URL

2. 注册页面元素
   ├── 手动新增（填写元素名称 + CSS/XPath）
   └── AI 解析 HTML 批量导入

3. 编写测试用例（步骤编排）
   ├── 手动编排步骤（选择元素 + 操作类型 + 操作值）
   └── AI 自然语言生成步骤

4. 执行测试
   ├── 手动触发（按用例 ID 执行）
   └── 加入综合计划（定时执行）

5. 查看执行结果
   └── 用例结果 + 步骤日志 + 截图

---

---

三、系统架构与技术说明

3.1 后端技术栈

组件	版本	用途
Spring Boot	2.7.3	Web 框架
MyBatis-Plus	3.4.0	ORM / 分页
Playwright Java	1.54.0	UI 自动化执行引擎
Quartz	2.3.2	定时任务调度
Apollo	1.7.0	配置中心
Jedis	3.7.0	Redis 客户端
ClickHouse JDBC	0.3.1	数据统计查询
Appium Java Client	8.0.0-beta	移动端 UI 测试
OkHttp	4.12.0	HTTP 请求工具
Lark OAPI SDK	2.0.28	飞书消息通知
POI	4.1.1	Excel 读写
TestNG	7.0.0	测试框架

3.2 前端技术栈

组件	版本	用途
Vue.js	2.6.14	前端框架
TypeScript	4.5.5	类型支持
Element UI	2.15.13	UI 组件库
Axios	1.1.3	HTTP 客户端（超时 150s）
ECharts	5.4.2	数据可视化
vue-router	3.6.5	路由管理
Vuex	3.1.2	状态管理
vue-cron	1.0.9	Cron 可视化选择器
vue-json-pretty	1.9.3	JSON 树状展示

3.3 数据模型关键字段说明

接口测试用例（Case）

字段	说明
method	请求 URL（必填）
type	请求方法 GET/POST（必填）
parameters	请求体
headers	自定义请求头（JSON 字符串）
expected / expected1	一级/二级断言
sessionid	Session 值
isrun	是否参与自动化执行

UI 测试步骤（UiTestStep）

字段	说明
operate	操作类型（click/input/assert/navigate 等）
operateselector	元素定位表达式（CSS/XPath）
selectornum	多元素时的序号（从 0 开始）
operatevalue	输入值 / 期望断言值
operateno	步骤执行顺序
screenshot	是否截图（0=否，1=是）

---

四、用户认证

页面： /login

支持两种登录方式：

方式	接口	说明
标准登录	POST /user/login	账号密码验证
LDAP 登录	POST /user/ldaplogin	企业 LDAP 目录认证（当前激活）

登录成功后 Token 与用户信息存储到 localStorage，路由守卫自动检查 Token 有效性，未登录跳转至登录页。

---

五、常见问题

Q1：Playwright 浏览器启动失败

Cannot run program "/tmp/playwright-java-xxx/node"

解决：

mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install chromium"

确保磁盘剩余空间 >= 500MB，且网络可访问 Playwright 官方资源。

---

Q2：前端请求 404 / 跨域

检查 .env 文件中 VUE_APP_SERVER_URL 是否与后端地址一致（vue.config.js 中已配置代理）。

---

Q3：定时任务不执行

1. 确认计划状态为「运行中」（status=1）
2. 检查 Cron 表达式格式是否正确（可用在线 Cron 验证工具）
3. 查看后端日志中 Quartz 相关错误

---

Q4：AI 功能无响应

AI 功能依赖配置中心（Apollo）注入的 AI 服务密钥（AiChatProperties），请确认：

1. Apollo 连接正常
2. AI 服务 Key 已配置到对应 namespace

---

文档生成时间：2026-03-03