We previously learned to execute the tests conditionally based on some assumptions. To implement these assumptions, we need to write some custom logic inside our test methods.

JUnit 5 provides us with conditional execution annotations, which we use in our tests to standardize this feature.

The following are the different annotation types.

Operating system conditions

We can enable or disable a test on a particular operating system (OS) where the test is running.

@EnabledOnOs

We need to provide the desired value of the OS type to enable this test. We can use the OS enum to do that.

It is used in the following two ways:

@EnabledOnOs({OS.LINUX, OS.MAC})

@EnabledOnOs({OS.WINDOWS})

@DisabledOnOs

The @DisabledOnOs annotation prevents our tests from running based on the provided OS value…

Press + to interact
package io.educative.junit5;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.DisabledOnOs;
import org.junit.jupiter.api.condition.EnabledOnOs;
import org.junit.jupiter.api.condition.OS;
class ConditionalExecutionTests {
    @Test
    @DisplayName("Run the tests only on Linux and MAC OS")
    @EnabledOnOs({OS.LINUX, OS.MAC})
    void shouldRunTestsOnlyOnLinuxAndMACOS() {
        // Some Test Code
    }
    @Test
    @DisplayName("Should not Run on Windows OS")
    @DisabledOnOs(OS.WINDOWS)
    void shouldNotRunOnWindowsOS() {
        // Some Test Code
    }
    @Test
    @DisplayName("Should Run on Windows OS")
    @EnabledOnOs(OS.WINDOWS)
    void shouldRunOnWindowsOS() {
        // Some Test Code
    }
}

If we run the above tests on Windows OS, the tests with names Should not Run on Windows OS and Run the tests only on Linux and MAC OS will be disabled.

Only the Should Run on Windows OS test will be executed.

Java runtime environment conditions

We can enable or disable a test based on our version of the Java Runtime Environment (JRE).

The following are the available annotations:

@EnabledOnJre

This annotation has an attribute of enum type JRE. The possible values of this enum start with JRE_8 and go all the way to the latest version.

@DisabledOnJre

The tests will be disabled if the version of JRE matches the one installed on the machine.

@EnabledForJreRange

The tests will be enabled if the installed version of JRE is within a specific range of JRE versions. We define this range using the min and max attributes on the annotation.

@DisabledForJreRange

The tests will be disabled if the installed version of JRE lies between the specified range of JRE versions.

Press + to interact
package io.educative.junit5;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.*;
class ConditionalExecutionTests {
    @Test
    @DisplayName("Should Run only on JRE 17")
    @EnabledOnJre(JRE.JAVA_17)
    void shouldRunOnJre17() {
        // Some Test Code
    }
    @Test
    @DisplayName("Should Run on Java version from 8 to 17")
    @EnabledForJreRange(min = JRE.JAVA_8, max = JRE.JAVA_17)
    void shouldRunOnJreFrom8to17() {
        // Some Test Code
    }
    @Test
    @DisplayName("Should Not Run on JRE 16")
    @DisabledOnJre(JRE.JAVA_16)
    void shouldNotRunOnJRE16() {
        // Some Test Code
    }
    @Test
    @DisplayName("Should Run on Java version from 8 to 15")
    @DisabledForJreRange(min = JRE.JAVA_8, max = JRE.JAVA_15)
    void shouldNotRunOnJreFrom8to15() {
        // Some Test Code
    }
}

When we run the above code on JRE 16, the tests with the names Should Run on Java version from 8 to 17 and Should Run on Java version from 8 to 15 run successfully.

System property conditions

We can also enable or disable a test execution based on the value of the named system property of the Java virtual machine (JVM). We use the following annotations for this function.

@EnabledIfSystemProperty

The tests run only when the named attribute is equal to the value provided in the matches attribute.

Here’s how it’s used:

@EnabledIfSystemProperty( named= "os.arch", matches = ".*64.*")

This test only runs when the os.arch system property is running on a 64-bit OS.

Note: The matches attribute takes a regular expression (regex) string as input.

@DisabledIfSystemProperty

In contrast, the @DisabledIfSystemProperty annotation disables a test if the given system property value exists.

Press + to interact
package io.educative.junit5;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.DisabledIfSystemProperty;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
class ConditionalExecutionTests {
    @Test
    @DisplayName("Should Run on 64 Bit Architecture")
    @EnabledIfSystemProperty(named = "os.arch", matches = ".*64.*")
    void enableOn64BitMachines() {
        // Some Test code
    }
    @Test
    @DisplayName("Disabled on 64 Bit Architecture")
    @DisabledIfSystemProperty(named = "os.arch", matches = ".*64.*")
    void disableOn64BitMachines() {
        // Some Test code
    }
}

Environment variable conditions

We can enable or disable a test execution based on the provided environment variable name and value.

@EnabledIfEnvironmentVariable

The test only executes when the given value for the named attribute is equal to the matches attribute.

It takes a string input, which is interpreted as a regex.

Here’s how it’s used:

@EnabledIfEnvironmentVariable(named = "ENV", matches = "staging-server")

@DisabledIfEnvironmentVariable

The test will not be executed if the provided value matches the environment variable.

Custom conditions

We can enable or disable a test execution based on custom conditions using the @EnabledIf and @DisabledIf annotations. These annotations take the method name as input. Its return type is boolean.

Press + to interact
package io.educative.junit5;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.DisabledIf;
import org.junit.jupiter.api.condition.EnabledIf;
class ConditionalExecutionTests {
    @Test
    @DisplayName("Run Test if Custom Condition Matches")
    @EnabledIf("customCondition")
    void runTestIfCustomConditionMatches() {
        // Some Test Code
    }
    @Test
    @DisplayName("Do Not Run Test if Custom Condition Matches")
    @DisabledIf("customCondition")
    void doNorunTestIfCustomConditionMatches() {
        // Some Test Code
    }
    boolean customCondition() {
        return true;
    }
}

The above code shows the results where we provide the customCondition method as an attribute to the @EnabledIf or @DisabledIf annotation.