一、起源

  • 单元测试与集成测试的失败语义不同:单元测试失败说明代码不可用,应在打包前阻断;集成测试需要先有可部署的产物,失败时也要保留现场信息。
  • 如果两类测试都放在 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,或引入内嵌服务

五、总结

  1. surefire 负责单元测试,绑定 test 阶段,失败立即中断构建。
  2. failsafe 负责集成测试,绑定 integration-test 与 verify,失败后先清理再汇总。
  3. 默认按类名约定拾取测试类,命名与 includes 是"测试未执行"的首要排查点。
  4. 覆盖率工具依赖 argLine 属性,自定义参数时必须保留 @{argLine}。