Java单元测试入门：使用JUnit 5编写第一个测试用例

一、为什么需要单元测试与 JUnit 5

在 Java 开发中，单元测试旨在验证程序中最小可测试单元（通常是单个方法）的行为是否符合预期。许多初学者习惯在业务类中编写 main 方法，通过 System.out.println 打印结果并人工肉眼核对。这种方式在项目初期看似简单，但随着代码规模扩大，每次修改都需要重新手动执行和检查，不仅效率低下，且极易遗漏回归错误。

引入测试框架的核心价值在于自动化断言。测试框架不仅能自动执行被测逻辑，还能将实际运行结果与预期结果进行程序化比对，并直观地汇总成功或失败状态，彻底解放人力。

目前 Java 领域最主流的测试框架是 JUnit。虽然 JUnit 4 曾广泛使用，但现代项目已普遍迁移至 JUnit 5（代号 Jupiter）。与旧版本不同，JUnit 5 采用了模块化架构，主要包含三个子模块：

• JUnit Platform：基础平台层，负责在 JVM 上发现并启动测试，支持 Maven、Gradle 等构建工具及 IDE 集成。
• JUnit Jupiter：核心编程模型，提供编写测试所需的新注解（如 @Test、@DisplayName）和断言 API。
• JUnit Vintage：兼容引擎，用于在 JUnit 5 平台上运行旧的 JUnit 3 或 JUnit 4 测试代码。

图 1：JUnit 5 架构构成（Platform、Jupiter 与 Vintage 的关系）

二、工程结构与 Maven 依赖配置

在标准的工业级 Java 工程中，源码与测试代码必须严格分离。以 Maven 项目为例：

• 业务源码：存放于 src/main/java
• 测试代码：存放于 src/test/java

两者的包路径通常保持一致。这种结构既方便测试类访问同包下默认访问权限（package-private）的方法，又能确保在打包发布时，测试代码不会被包含进最终的生产 JAR 包中。

图 2：标准 Maven 项目源码与测试代码的目录结构分离规范

要使用 JUnit 5，需在项目的 pom.xml 文件中添加 junit-jupiter 依赖，并将作用域（scope）设置为 test，以确保其仅在测试阶段生效：

    
        org.junit.jupiter
        junit-jupiter
        5.10.2
        test
    

三、编写被测类与第一个测试用例

1. 准备被测代码

首先在 src/main/java/com/example/math/Calculator.java 中创建一个简单的计算器类，包含加法和除法两个方法：

package com.example.math;

public class Calculator {

    public int add(int a, int b) {
        return a + b;
    }

    public int divide(int dividend, int divisor) {
        if (divisor == 0) {
            throw new IllegalArgumentException("除数不能为零");
        }
        return dividend / divisor;
    }
}

2. 编写测试类

在 src/test/java/com/example/math/CalculatorTest.java 中创建对应的测试类。编写单元测试时，推荐遵循行业通用的 AAA（Arrange - Act - Assert） 三段式设计原则：

1. Arrange（准备）：初始化对象、准备输入参数及模拟数据。
2. Act（执行）：调用目标方法，获取实际结果。
3. Assert（断言）：验证实际结果是否与预期一致。

以下是完整的测试代码：

package com.example.math;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

class CalculatorTest {

    @Test
    @DisplayName("测试正整数相加：2 + 3 应该等于 5")
    void testAddPositiveNumbers() {
        // 1. Arrange（准备环境与数据）
        Calculator calculator = new Calculator();
        int a = 2;
        int b = 3;

        // 2. Act（调用被测方法）
        int result = calculator.add(a, b);

        // 3. Assert（验证结果）
        assertEquals(5, result, "2 + 3 的计算结果应该为 5");
    }

    @Test
    @DisplayName("测试除数为零时抛出异常")
    void testDivideByZero() {
        Calculator calculator = new Calculator();
        
        // 验证执行 divide(10, 0) 时是否抛出 IllegalArgumentException
        assertThrows(IllegalArgumentException.class, () -> {
            calculator.divide(10, 0);
        });
    }
}

注意细节：

• 修饰符简化：在 JUnit 4 中，测试类和方法必须声明为 public。而在 JUnit 5 中，测试类和测试方法可以使用默认访问权限（包私有），无需显式声明 public，使代码更简洁。
• 导包区别：务必引入 org.junit.jupiter.api.Test，而非 JUnit 4 的 org.junit.Test。

四、测试执行流程与断言机制

单元测试的执行是一个确定性的状态转换过程。测试引擎接管执行后，会根据结果标记状态：

• Passed（成功）：所有断言通过，无未捕获异常。
• Failed（失败）：断言不匹配（如期望值与实际值不等），触发 AssertionFailedError。
• Error（错误）：抛出了非预期的异常。

图 3：测试用例执行流与终端执行结果反馈

五、运行测试与排查失败

1. 运行方式

• IDE 运行：在 IntelliJ IDEA 或 Eclipse 中，点击测试类或方法左侧的绿色运行图标即可单独执行。
• 命令行运行：在终端或 CI/CD 环境中，使用 Maven 命令触发全量测试：

mvn test

2. 失败排查示例

假设我们在业务代码中故意引入一个 Bug：

public int add(int a, int b) {
    return a + b + 1; // 模拟手误
}

再次运行测试，JUnit 5 会中断构建并输出清晰的错误报告：

org.opentest4j.AssertionFailedError: 2 + 3 的计算结果应该为 5 ==> 
Expected :5
Actual   :6
    at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:55)
    at org.junit.jupiter.api.AssertEquals.failNotEqual(AssertEquals.java:197)
    at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:150)
    at com.example.math.CalculatorTest.testAddPositiveNumbers(CalculatorTest.java:21)

排查思路：

1. 检查测试用例本身的入参和断言期望值是否符合业务逻辑。
2. 若测试无误，根据堆栈跟踪定位到具体的业务代码行（如本例中的 Calculator.java），修复逻辑错误。

六、核心要点总结

编写高质量的单元测试并非一定要引入复杂的设计模式，关键在于建立自动化验证与契约思维。对于初学者，掌握以下核心要素即可应对大部分基础场景：

图 4：JUnit 5 单元测试编写与实践要点全景总结

单元测试不是开发的负担，而是防止代码回归错误的最有效防线。在熟练掌握 @Test、assertEquals 和 assertThrows 后建议进一步探索生命周期注解（如 @BeforeEach）和参数化测试（@ParameterizedTest），以提升测试代码的复用性与整洁度。