JUnit 5 Conditional Test Execution Examples

Learn to enable or disable the execution of the specific tests in JUnit 5 using inbuilt conditional execution annotations. These annotations run or skip tests based on environment configurations such as: The following table summarizes these annotations in more detail: Annotation Description Usage @EnabledOnOs@DisabledOnOs Enables/disables the test if …

junit5 logo

Learn to enable or disable the execution of the specific tests in JUnit 5 using inbuilt conditional execution annotations. These annotations run or skip tests based on environment configurations such as:

  • Operating System Conditions: Use @EnabledOnOs and @DisabledOnOs for OS-specific tests.
  • JRE Conditions: @EnabledOnJre and @DisabledOnJre allow test execution based on Java versions. We can also use @EnabledForJreRange and @DisabledForJreRange
  • System Properties: Control test execution by system properties via @EnabledIfSystemProperty and @DisabledIfSystemProperty.
  • Environment Variables: Use environment variables for conditional execution with @EnabledIfEnvironmentVariable and @DisabledIfEnvironmentVariable.
  • Custom Conditions: Use @EnabledIf and @DisabledIf for custom conditions, allowing dynamic control over test execution.

The following table summarizes these annotations in more detail:

AnnotationDescriptionUsage
@EnabledOnOs
@DisabledOnOs
Enables/disables the test if the specified operating system(s) is running.@EnabledOnOs(OS.WINDOWS)
@DisabledOnOs(OS.MAC)
@EnabledOnJre
@DisabledOnJre
Enables/disables the test if the specified Java Runtime Environment (JRE) version is running.@EnabledOnJre(JRE.JAVA_21)
@DisabledOnJre(JRE.JAVA_8)
@EnabledForJreRange
@DisabledForJreRange
Enables/disables the test if the Java Runtime Environment is within the specified version range.@EnabledForJreRange(min = JRE.JAVA_8, max = JRE.JAVA_11)
@DisabledForJreRange(min = JRE.JAVA_9, max = JRE.JAVA_10)
@EnabledIf
@DisabledIf
Enables/disables the test if the specified condition (via a custom expression or method) is met.@EnabledIf(“myCustomCondition”)
@DisabledIf(“isWeekend”)
@EnabledIfSystemProperty
@DisabledIfSystemProperty
Enables/disables the test if a specified system property matches the given value.@EnabledIfSystemProperty(named = “os.arch”, matches = “amd64”)
@DisabledIfSystemProperty(named = “user.language”, matches = “fr”)
@EnabledIfEnvironmentVariable
@DisabledIfEnvironmentVariable
Enables/disables the test if a specified environment variable matches the given value.@EnabledIfEnvironmentVariable(named = “ENV”, matches = “test”)
@DisabledIfEnvironmentVariable(named = “ENV”, matches = “production”)
@EnabledIfCondition
@DisabledIfCondition
Enables/disables the test if the specified custom ExecutionCondition is met (custom conditional logic).A custom condition class implementing ExecutionCondition is provided.

1. @EnabledOnOs and @DisabledOnOs

  • These annotations enable or disable the execution of the annotated test based on a particular operating system.
  • The supported operating systems are listed in enum org.junit.jupiter.api.condition.OS are AIX, Linux, Mac, Solaris, Windows and Others.
  • When applied at the class level, all test methods within that class will be enabled on the same specified operating systems.
  • If a test method is disabled via this annotation, the test class will be initiated, only the test method and its life cycle methods will not be executed.
@Test
@EnabledOnOs(OS.MAC)
void testOnMacOs() {
    assertTrue(true);
}

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

2. @EnabledOnJre and @DisabledOnJre

  • These annotations can help in enabling or disabling the test for particular JRE version.
  • The supported values can be found in the latest version of the JRE enum.
  • If the current JRE version cannot be detected then none of the constants defined in JRE enum will be considered.
@Test
@DisabledOnJre(JRE.JAVA_8)
void disabledOnJava8() {
    assertTrue(true);
}

@Test
@EnabledOnJre({ JRE.JAVA_17, JRE.JAVA_18 })
void enabledOnJava17Or18() {
    assertTrue(true);
}

3. @EabledForJreRange and @DisabledForJreRange

  • These annotations are used to signal that the annotated test class or test method is only disabled or enabled for a specific range of JRE versions using its min to max attributes.
  • When applied at the class level, all test methods within that class will be enabled on the same specified JRE versions.
@Test
@DisabledForJreRange(min = JRE.JAVA_8, max = JRE.JAVA_11)
void notFromJava8to11() {
    assertTrue(true);
}

@Test
@EnabledForJreRange(min = JRE.JAVA_12, max = JRE.JAVA_18)
void fromJava12to18() {
    assertTrue(true);
}

4. @EnabledIf and @DisabledIf

  • The annotated test class or test method is enabled or disabled only if the provided condition evaluates to true.
  • When applied at the class level, all test methods within that class will be enabled or disabled on the same condition.
  • When these annotations are used at class level, the condition method must always be static.
  • This annotation is not repeatable so can only be declared once.
@Test
@EnabledIf("customConditionalFunction")
void enabled() {
    assertTrue(true);
}

@Test
@DisabledIf("customConditionalFunction")
void disabled() {
    assertTrue(true);
}

boolean customConditionalFunction() {
    return true;
}

5. @EnabledIfEnvironmentVariable and @DisabledIfEnvironmentVariable

  • Use these annotations if we want to enable or disable our tests if the value of an environment variable matches the specified regular expression.
  • When declared at the class level, the result will apply to all test methods within that class as well.
  • If the specified environment variable is undefined, the presence of this annotation will have no effect.
  • This is a repeatable annotation so it can be used multiple times on a test method or class.
@Test
@EnabledIfEnvironmentVariable(named = "ENV", matches = ".*development.*")
public void executeOnlyInDevEnvironment() {
    return true;
}

@Test
@DisabledIfEnvironmentVariable(named = "ENV", matches = ".*prod.*")
public void disabledOnProdEnvironment() {
    return true;
}

6. @EnabledIfSystemProperty and @DisabledIfSystemProperty

  • Use these annotations if we want to enable or disable our tests if the value of the specified JVM system property matches the specified regular expression.
  • When declared at the class level, the result will apply to all test methods within that class as well.
  • If the specified system property is undefined, the presence of this annotation will have no effect.
  • This is also a repeatable annotation so it can be used multiple times on a test method or class.
@Test
@EnabledIfSystemProperty(named = "any.system.property", matches = "value-regex*")
public void onlyIfPropertyValueIsFound() {
    return true;
}

7. @EnabledIfCondition and @DisabledIfCondition

Enables or disables the test based on a custom condition that implements ExecutionCondition.

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfCondition;
import org.junit.jupiter.api.extension.ConditionEvaluationResult;
import org.junit.jupiter.api.extension.ExecutionCondition;
import org.junit.jupiter.api.extension.ExtensionContext;

public class CustomConditionTests {

    @Test
    @EnabledIfCondition(MyCustomCondition.class)
    void testIfCustomConditionMet() {
        // This test runs if MyCustomCondition evaluates to enabled
        System.out.println("Custom condition is met");
    }
}

class MyCustomCondition implements ExecutionCondition {

    @Override
    public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) {

        boolean conditionMet = /* custom logic */ true;
        if (conditionMet) {
            return ConditionEvaluationResult.enabled("Condition met");
        } else {
            return ConditionEvaluationResult.disabled("Condition not met");
        }
    }
}

Happy Learning !!

Download Source Code

Weekly Newsletter

Stay Up-to-Date with Our Weekly Updates. Right into Your Inbox.

Comments

Subscribe
Notify of
0 Comments
Most Voted
Newest Oldest
Inline Feedbacks
View all comments

About Us

HowToDoInJava provides tutorials and how-to guides on Java and related technologies.

It also shares the best practices, algorithms & solutions and frequently asked interview questions.