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:

• 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:

Annotation	Description	Usage
@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