当前位置：首页 > article >正文

JUnit 5 条件测试注解详解

article 2025/2/9 5:44:49

JUnit 5 条件测试注解详解

JUnit 5 提供了一系列条件测试注解，允许开发者根据运行时环境、配置或自定义逻辑动态决定是否执行测试。这些注解能有效减少误报，提升测试的灵活性和适应性。以下是所有条件测试注解的详细介绍及示例：

一、条件测试注解列表

注解	说明
`@EnabledOnOs`	仅在指定操作系统上启用测试（如 `OS.LINUX`）。
`@DisabledOnOs`	在指定操作系统上禁用测试。
`@EnabledOnJre`	仅在指定 JRE 版本上启用测试（如 `JRE.JAVA_17`）。
`@DisabledOnJre`	在指定 JRE 版本上禁用测试。
`@EnabledForJreRange`	在 JRE 版本范围内启用测试（如 `min = JRE.JAVA_11`）。
`@DisabledForJreRange`	在 JRE 版本范围内禁用测试。
`@EnabledIfEnvironmentVariable`	当环境变量满足条件时启用测试。
`@DisabledIfEnvironmentVariable`	当环境变量满足条件时禁用测试。
`@EnabledIfSystemProperty`	当系统属性满足条件时启用测试。
`@DisabledIfSystemProperty`	当系统属性满足条件时禁用测试。
`@EnabledIf`	根据 SpEL 表达式或自定义方法启用测试。
`@DisabledIf`	根据 SpEL 表达式或自定义方法禁用测试。

二、注解详解与示例

1. `@EnabledOnOs` / `@DisabledOnOs`

场景：测试依赖特定操作系统的功能（如文件路径、Shell 脚本）。
示例：

@Test
@EnabledOnOs(OS.LINUX)
void runOnlyOnLinux() {
    Assertions.assertTrue(Files.exists(Paths.get("/proc")));
}

@Test
@DisabledOnOs(OS.WINDOWS)
void skipOnWindows() {
    Assertions.assertTrue(true);
}

2. `@EnabledOnJre` / `@DisabledOnJre`

场景：验证代码在不同 Java 版本中的行为（如新版 API 兼容性）。
示例：

@Test
@EnabledOnJre(JRE.JAVA_17)
void testJava17Feature() {
    // 使用 Java 17 的密封类特性
    Assertions.assertTrue(true);
}

@Test
@DisabledOnJre(JRE.JAVA_8)
void skipOnJava8() {
    Assertions.fail("此测试在 Java 8 上禁用");
}

3. `@EnabledForJreRange` / `@DisabledForJreRange`

场景：限定测试在 Java 版本范围内执行。
示例：

@Test
@EnabledForJreRange(min = JRE.JAVA_11, max = JRE.JAVA_17)
void testForJava11To17() {
    Assertions.assertTrue(true);
}

4. `@EnabledIfEnvironmentVariable` / `@DisabledIfEnvironmentVariable`

场景：根据环境变量控制测试（如 CI/CD 环境、密钥配置）。
示例：

@Test
@EnabledIfEnvironmentVariable(named = "ENV", matches = "CI")
void runOnlyInCI() {
    Assertions.assertTrue(true);
}

@Test
@DisabledIfEnvironmentVariable(named = "API_KEY", matches = "none")
void skipIfNoApiKey() {
    Assertions.fail("需要有效的 API_KEY");
}

4.1 在 IDE 中设置环境变量

IntelliJ IDEA：
1. 打开 Run/Debug Configurations。
2. 选择测试类或方法配置。
3. 在 Environment variables 字段中添加变量（如 ENV=CI）。

4.2 通过命令行设置环境变量（Maven/Gradle）

Maven：

mvn test -DENV=CI
# 或通过 .mvn/jvm.config 永久配置

Gradle：

./gradlew test -DENV=CI
# 或通过 gradle.properties 配置

4.3 操作系统级设置环境变量

Windows：

:: 临时设置
set ENV=CI
mvn test

:: 永久设置（需重启）
:: 通过“系统属性 → 高级 → 环境变量”添加

Linux/macOS：
```
# 临时设置
export ENV=CI
mvn test
```

5. `@EnabledIfSystemProperty` / `@DisabledIfSystemProperty`

场景：根据系统属性控制测试（如配置模式、调试标志）。
示例：

@Test
@EnabledIfSystemProperty(named = "test.mode", matches = "stress")
void runStressTest() {
    Assertions.assertTrue(true);
    System.getProperty("test.mode"); //获取系统属性
}

5.1 通过 JVM 参数设置系统属性

在运行测试时通过 -D 参数设置系统属性：

# Maven
mvn test -Dtest.mode=ci -Ddebug=true

# Gradle
./gradlew test -Dtest.mode=ci -Ddebug=true

5.2 在 IDE 中配置系统属性

IntelliJ IDEA：
1. 打开 Run/Debug Configurations。
2. 在 VM options 中添加 -Dtest.mode=ci。

5.3 在代码中动态设置系统属性

通过 System.setProperty() 在测试类中设置系统属性（需注意线程安全和测试隔离）：

@BeforeAll
static void setup() {
    System.setProperty("test.mode", "ci"); // 设置系统属性
}

@AfterAll
static void cleanup() {
    System.clearProperty("test.mode");     // 清理系统属性
}

6. `@EnabledIf` / `@DisabledIf`

场景：自定义复杂条件（如数据库状态、服务可用性）。
示例：基于 SpEL 表达式或静态方法返回值。

@Test
@EnabledIf("'${env}' == 'ci'")  // SpEL 表达式
void runIfEnvIsCI() {
    Assertions.assertTrue(true);
}

@Test
@DisabledIf("customCheck()")    // 调用静态方法
void skipIfCustomCheckFails() {
    Assertions.fail("自定义条件未满足");
}

private static boolean customCheck() {
    return LocalTime.now().getHour() >= 22; // 晚上 10 点后跳过
}

三、组合条件测试

多个条件注解可组合使用，通过逻辑与（AND）或逻辑或（OR）控制测试。
示例：

@Test
@EnabledOnOs(OS.MAC)
@EnabledIfEnvironmentVariable(named = "CI", matches = "true")
void runOnMacInCI() {
    Assertions.assertTrue(true);
}

四、最佳实践

明确条件范围
条件应聚焦于外部不可控因素（如环境、版本），而非业务逻辑错误。
提供跳过原因
在注解中添加 reason 参数，明确记录跳过测试的原因：
```
@DisabledOnJre(value = JRE.JAVA_8, reason = "Java 8 不兼容新特性")
```
避免过度使用
条件测试会增加复杂度，优先保证测试的独立性。