一、起源
- 单元测试与集成测试的失败语义不同:单元测试失败说明代码不可用,应在打包前阻断;集成测试需要先有可部署的产物,失败时也要保留现场信息。
- 如果两类测试都放在
test 阶段,集成测试会在打包前执行,无法使用打包后的构件,也无法在失败后继续收集结果。
- Maven 因此把两类测试分给两个插件:surefire 处理单元测试,failsafe 处理集成测试。
二、原理
2.1 阶段绑定差异
| 插件 | 绑定阶段 | 目标 | 失败后的行为 |
| maven-surefire-plugin | test | test | 立即中断构建,不会继续打包 |
| maven-failsafe-plugin | integration-test | integration-test | 记录失败但不中断,继续执行后续清理 |
| maven-failsafe-plugin | verify | verify | 汇总结果,存在失败时使构建失败 |
- failsafe 拆成两个阶段的原因:集成测试失败后仍需要执行
post-integration-test 中的清理动作,例如关闭容器、删除临时数据。
- 只执行
mvn test 不会运行 failsafe,必须执行到 verify 阶段。
2.2 默认类名约定
| 插件 | 默认匹配的类名 |
| surefire | **/Test*.java、**/*Test.java、**/*Tests.java、**/*TestCase.java |
| failsafe | **/IT*.java、**/*IT.java、**/*ITCase.java |
- 命名不符合约定时,插件不会拾取该类,表现为"测试写了但没有执行"。
- 可以通过
includes 与 excludes 显式指定,但应保持项目内命名一致。
2.3 类路径差异
- surefire 运行在测试类路径上,依赖范围
test 的构件可用。
- failsafe 同样使用测试类路径,但运行时机在
package 之后,可以使用已打包的产物与本模块的 target/classes。
- 需要启动外部依赖(数据库、消息队列、容器)的测试应放在 failsafe,避免单元测试阶段依赖外部环境。
三、实现
3.1 surefire 配置
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<includes>
<include>**/*Test.java</include>
</includes>
<excludes>
<exclude>**/*IT.java</exclude>
</excludes>
<argLine>-Xmx512m -Dfile.encoding=UTF-8</argLine>
<forkCount>2</forkCount>
<reuseForks>true</reuseForks>
</configuration>
</plugin>
forkCount 控制并发测试进程数,reuseForks 控制是否复用进程,测试之间存在静态状态污染时应关闭复用。
argLine 中的参数会传给测试进程,内存不足导致的测试失败通常通过调整该值解决。
3.2 failsafe 配置
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<includes>
<include>**/*IT.java</include>
</includes>
</configuration>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
- 必须显式声明
integration-test 与 verify 两个目标,否则插件不会执行。
- 只执行到
package 时集成测试不会运行,属于预期行为。
3.3 执行命令
# 只运行单元测试
mvn test
# 运行单元测试与集成测试
mvn verify
# 只运行指定的集成测试类
mvn verify -Dit.test=OrderServiceIT
# 跳过集成测试但保留单元测试
mvn verify -DskipITs
-Dit.test 是 failsafe 的专用参数,-Dtest 只作用于 surefire。
- 插件的完整清单与配置方式见 Maven 常用插件。
3.4 跳过开关
| 参数 | 影响范围 | 说明 |
-DskipTests | surefire 与 failsafe | 跳过执行,测试代码仍编译 |
-Dmaven.test.skip=true | surefire 与 failsafe | 跳过编译与执行 |
-DskipITs | failsafe | 只跳过集成测试 |
-Dtest=类名 | surefire | 指定运行的单元测试类 |
-Dit.test=类名 | failsafe | 指定运行的集成测试类 |
- 跳过测试会隐藏失败信息,发布构建中不建议长期使用。
3.5 jacoco 覆盖率集成
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.8.11</version>
<executions>
<execution>
<id>prepare-agent</id>
<goals><goal>prepare-agent</goal></goals>
</execution>
<execution>
<id>report</id>
<phase>verify</phase>
<goals><goal>report</goal></goals>
</execution>
</executions>
</plugin>
prepare-agent 会设置 argLine 属性,如果同时自定义了 <argLine>,必须写成 <argLine>@{argLine} -Xmx512m</argLine>,否则 jacoco 的输出参数被覆盖,报告为空。
- 集成测试的覆盖率需要在 failsafe 执行后合并数据,通常通过
prepare-agent-integration 与 report-integration 两个目标处理。
3.6 并行与稳定性
- 测试并行度受
forkCount 与测试框架自身并行配置共同影响,两者都开启时容易超出机器资源。
- 依赖外部端口的测试并行执行会互相冲突,应放入 failsafe 串行执行,或为每个测试分配独立端口。
- 测试报告中出现
Flakes 或随机失败时,优先排查共享状态、时间依赖与端口占用。
四、常见问题
| 现象 | 常见原因 | 处理方式 |
| 测试类写了但没有执行 | 类名不符合默认约定,或 includes 过滤掉了 | 调整命名,或显式配置 includes |
mvn verify 不运行集成测试 | 未声明 failsafe 的执行目标 | 补充 integration-test 与 verify 目标 |
| jacoco 报告为空 | 自定义 argLine 覆盖了 prepare-agent 设置的同名属性 | 使用 @{argLine} 引用原有参数 |
| 测试进程内存溢出 | argLine 中的堆内存过小,或 fork 数量过多 | 调大 -Xmx,降低 forkCount |
| 集成测试失败但构建仍成功 | 只执行到 integration-test 阶段,未执行 verify | 改为执行 mvn verify |
| 单元测试依赖外部服务导致不稳定 | 测试放错插件 | 迁移到 failsafe,或引入内嵌服务 |
五、总结
- surefire 负责单元测试,绑定
test 阶段,失败立即中断构建。
- failsafe 负责集成测试,绑定
integration-test 与 verify,失败后先清理再汇总。
- 默认按类名约定拾取测试类,命名与 includes 是"测试未执行"的首要排查点。
- 覆盖率工具依赖
argLine 属性,自定义参数时必须保留 @{argLine}。