学之思管理端 · API（接口）自动化测试

项目背景

被测系统：学之思开源考试系统（xzs）—— 基于 Spring Boot 的在线考试系统，含管理端与学生端。

测试范围：管理端 REST API，6 个模块、21 个接口 —— 登录 / 登出、学科、题目、任务、试卷、答卷。

要解决的问题：接口自动化最常见的失败模式不是”跑不起来”，而是跑绿了但什么都没测到。数据依赖环境预置、断言写死期望值、执行完留下一地脏数据 —— 这样的用例越多，可信度反而越低。

所以这个项目的目标不是”把 21 个接口跑一遍”，而是建立一套让绿灯可信的机制。

核心成果：环境依赖 0（测试数据由用例现场自造，clone 后可直接运行），数据残留 0（全套执行后 zz_% 前缀 SQL 对账为空）。

技术栈

架构设计

四层分层，职责单一：

xzs-api-test/
├── pom.xml
├── testng.xml                     # 测试套件（按类并行）
├── Jenkinsfile                    # Jenkins 流水线定义
└── src/test/
    ├── resources/
    │   ├── config.properties      # base.uri、admin 账号密码
    │   └── allure.properties
    └── java/com/xzs/
        ├── api/                   # 接口封装层，一个类对应一个模块
        │   ├── LoginApi / SubjectApi / QuestionApi
        │   └── TaskApi / PaperApi / ExamPaperAnswerApi
        ├── common/
        │   ├── ConfigReader       # 读取配置文件
        │   ├── SessionManager     # 登录态管理（ThreadLocal 存 JSESSIONID）
        │   ├── RequestUtil        # 请求公共处理
        │   └── CleanupRegistry    # 清理注册表（栈式逆序清理）
        ├── data/
        │   └── CreateData         # 测试数据工厂：造学科 / 题目 / 试卷 / 任务
        └── test/                  # 测试用例
            ├── BaseTest / PreLoginInBaseTest
            ├── LoginTest / LogoutTest
            ├── SubjectTest / QuestionTest
            └── TaskTest / PaperTest

四个关键设计决策：

1. 接口层与用例层解耦 —— 接口变更只需修改 Api 类，用例零感知。这是”框架”和”一堆脚本”的分界线。

2. CleanupRegistry 栈式清理 —— 按”造数即注册”顺序入栈，@AfterMethod / @AfterClass 逆序执行。 天然满足”下游先删、上游后删”的依赖顺序：把规则内化进数据结构，而不是要求每个人记住规则。

3. 造数链自给自足 —— CreateData 支持 subject → question → paper → task 逐级组合， 已消除对任何环境预置数据的依赖。例如 task 用例现场自造”学科 → 题目 → 试卷 → 任务”全链。

4. 参数化环境 —— base.uri 通过 -Dbase.uri= 注入，本地 / 测试 / 预发一键切换，一套用例多环境执行。

测试设计原则

这部分是本项目真正的产出 —— 规范写进了框架机制，而不是停在文档里。

• 过滤验证黄金法则：每个过滤条件必须给出”阳性（该来的来了）+ 阴性（不该来的没来）“双侧证据。 只验证一侧的用例，本质上什么都没证明。

• 契约型 vs 记录型断言：主键唯一查询断言”恰好一条”（契约型）；对系统数据现状（如答卷表为空） 采用记录型断言锁定现状 —— 现状变化即产生告警，而不是假装它是契约。

• 同通道对照：删除 / 编辑前后的对照必须走同一查询通道、同一参数口径，避免口径差异导致假绿。

• 禁止条件断言：断言不允许藏在不被验证的 if 条件里 —— 前提破坏时用例会静默通过。

• 禁裸字面量：断言中的期望值必须来自变量或本用例刚造的数据，杜绝与环境数据巧合耦合。

• 数据治理规范：测试数据统一 zz_ 前缀 + 时间戳保证唯一； 执行后以 SQL 对账（zz_% 且 deleted=0 应为空）验收清理效果。

# 全量执行（默认 base.uri = http://localhost:8000）
mvn clean test

# 指定被测环境
mvn clean test -Dbase.uri=http://test.example.com:8000

# 单模块执行
mvn test -Dtest=TaskTest

# 查看 Allure 报告
allure serve target/allure-results

SELECT id FROM t_subject    WHERE name  LIKE 'zz_%' AND deleted = 0;
SELECT id FROM t_question   WHERE title LIKE 'zz_%' AND deleted = 0;
SELECT id FROM t_exam_paper WHERE name  LIKE 'zz_%' AND deleted = 0;
SELECT id FROM t_task_exam  WHERE title LIKE 'zz_%' AND deleted = 0;

持续集成与测试报告

Jenkins Declarative Pipeline（仓库根目录 Jenkinsfile）：

• 参数化构建：BASE_URI 下拉多环境选择（本地 / 测试 / 预发），一套用例多环境执行；
• 触发策略：SCM 轮询（每小时）+ 夜间定时构建（每日）；
• 构建与测试：mvn clean test -Dbase.uri=${BASE_URI}；
• 报告归档：JUnit 结果（Surefire XML）与 Allure 报告自动发布； Allure 报告同时打包为构建工件（allure-report.zip）可直接下载；
• 通知：构建失败发送告警邮件；由失败恢复正常时发送恢复通知（状态未变化不打扰）。

最近构建：#20 全绿 —— 35 条用例 0 失败，Allure Report 与 Tests 结果页均已归档。

Allure 报告：按 Epic / Feature / Story 分层组织，标注 Severity。

已知限制与后续规划

1. 答卷模块为结构级覆盖 —— 管理端无造数通道，后续扩展学生端”开考 → 交卷 → 成绩”全流程用例；
2. CI 运行形态 —— 当前 Jenkins 与被测服务均为本地 / 内网环境，后续规划将被测服务容器化 （Docker Compose），实现任意环境一键全链路回归；
3. 后续方向 —— 业务流联动用例（一条流程串联多接口）、被测服务日志自动关联到测试报告。

项目截图

5 张 · 点击放大

测试报告

持续集成

代码结构

关闭 (Esc)