JUnit 5 条件测试注解详解

---

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);
}

---

四、最佳实践

1. 明确条件范围
   条件应聚焦于外部不可控因素（如环境、版本），而非业务逻辑错误。

2. 提供跳过原因
   在注解中添加 reason 参数，明确记录跳过测试的原因：

   @DisabledOnJre(value = JRE.JAVA_8, reason = "Java 8 不兼容新特性")

3. 避免过度使用
   条件测试会增加复杂度，优先保证测试的独立性。

---

五、总结

通过条件测试注解，可以实现：

• 环境隔离：确保测试在特定环境（如 CI、生产）中运行。
• 版本控制：兼容多版本 Java 或操作系统。
• 动态决策：基于运行时状态灵活跳过测试。

合理使用这些注解能显著提升测试的健壮性和可维护性！