Java单元测试环境搭建教程

本文详细解析了Java项目中JUnit 5单元测试环境的正确搭建方法，涵盖依赖配置（仅需junit-jupiter 5.10.2、避免JUnit 4混用）、IDE兼容性（IntelliJ默认支持，Eclipse需插件）、测试类与方法的规范要求（public非final类、public void无参@Test方法）、Surefire插件关键配置（3.2.5+版本及扫描路径设置）、以及提升可维护性的实用技巧——如引入AssertJ获得更清晰的断言失败信息、规避中文乱码等常见陷阱，直击开发者“测试跑不起来”的真实痛点，帮你避开90%的环境配置坑。

用 Maven 引入 JUnit 5 的正确依赖组合

JUnit 5 不是单个 jar，而是由 junit-jupiter（测试编写）、junit-platform-launcher（IDE/构建工具调用）和 junit-platform-console（命令行运行）三部分组成。Maven 项目只需声明 junit-jupiter，它会自动拉取必要传递依赖。

• 在 pom.xml 中添加以下依赖（注意版本号，推荐使用最新稳定版，如 5.10.2）：

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
</dependency>

• 不要同时引入 junit:junit:4.x，否则可能触发混合执行、断言行为不一致（比如 assertThrows 在 JUnit 4 下不可用）
• 若用 IntelliJ IDEA，默认支持 JUnit 5；Eclipse 需确保安装了 JUnit 5 Support 插件（4.13+ 版本已内置）

测试类和方法的命名与注解规范

JUnit 5 不强制要求类名以 Test 结尾或方法名以 test 开头，但 IDE 和构建工具（如 Maven Surefire）默认只扫描满足这些约定的类——这是实际运行失败最常见的原因。

• 类必须是 public，且不能是 final（否则无法被反射实例化）
• 测试方法必须是 public void，无参数，且标注 @Test
• 避免使用 static 方法：JUnit 不会执行静态测试方法
• 生命周期方法用 @BeforeEach / @AfterEach（替代 JUnit 4 的 @Before / @After），类级用 @BeforeAll / @AfterAll（对应方法必须是 static）

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CalculatorTest {
    @Test
    void add_returnsCorrectResult() {
        assertEquals(5, new Calculator().add(2, 3));
    }
}

Maven Surefire 插件配置常见陷阱

默认情况下，Maven 使用 Surefire 插件执行测试，但它对 JUnit 5 的支持取决于插件版本。低于 2.22.0 的版本无法识别 @Test（来自 junit-jupiter），导致 mvn test 显示 “No tests found”。

• 必须显式配置 Surefire 插件版本，并指定 junit-platform-engine 作为 provider：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
    <configuration>
        <includes>
            <include>**/*Test.java</include>
        </includes>
    </configuration>
</plugin>

• 不需要额外添加 surefire-junit5-provider：现代 Surefire 已内置支持
• 如果项目里混用了 TestNG 或 JUnit 4，需通过 排除干扰类，否则可能因类加载冲突导致启动失败

断言失败时看不到堆栈或值？检查 assertj 或日志配置

原生 assertEquals(expected, actual) 在失败时只打印两个值的 toString()，对复杂对象（如嵌套 List、自定义 DTO）可读性差。这不是 JUnit 问题，而是断言库能力边界。

• 推荐搭配 assertj 使用，它提供链式断言和清晰的失败消息：

<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <version>3.24.2</version>
    <scope>test</scope>
</dependency>

• 示例对比：
• assertEquals(list1, list2) 失败时只显示 [1,2] != [1,3]
• assertThat(list1).isEqualTo(list2) 失败时高亮差异位置：expected: [1, 3] but was: [1, 2]
• IDE 控制台编码为 GBK 时，中文断言消息可能乱码——需在运行配置中添加 VM option：-Dfile.encoding=UTF-8

今天关于《Java单元测试环境搭建教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！