In the high-speed world of modern DevOps and CI/CD, the “one size fits all” philosophy is a relic of the past. As architectures move toward microservices and multi-cloud environments, your testing strategy must adapt. You might have a test suite that interacts with a Windows-specific DLL, a legacy integration that requires Java 8, or a performance benchmark that only makes sense on high-spec production-like runners.

Running these tests in the wrong environment doesn’t just lead to confusing failure logs; it creates “noise,” increases build times, and erodes trust in your automation. This is where JUnit 5 Conditional Execution shines. Unlike the blunt @Disabled annotation, JUnit 5 (Jupiter) provides a sophisticated toolkit to programmatically enable or disable tests based on the runtime context.

In this comprehensive guide, we’ll explore the standard annotations and dive into advanced custom conditions to make your test suite truly environment-aware.

1. Operating System Conditions: Target Your Infrastructure

Operating systems handle file systems, networking stacks, and native libraries differently. If your code uses Runtime.exec() or accesses specific paths like C:\Windows\System32, running that test on a Linux build server is a guaranteed failure.

@EnabledOnOs & @DisabledOnOs

These annotations use the OS enum to filter execution. You can target a single OS or a combination.

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.*;

class OsConditionalTest {

    @Test
    @EnabledOnOs(OS.WINDOWS)
    void testWindowsRegistryAccess() {
        System.out.println("Executing Windows-specific logic.");
    }

    @Test
    @EnabledOnOs({OS.LINUX, OS.MAC})
    void testUnixSocketBehavior() {
        System.out.println("Executing Unix-specific logic.");
    }

    @Test
    @DisabledOnOs(OS.SOLARIS)
    void runEverywhereButSolaris() {
        System.out.println("Solaris is not supported for this module.");
    }
}

Execution Output (Running on macOS):

• testWindowsRegistryAccess: Skipped (Reason: Disabled on Mac OS X)
• testUnixSocketBehavior: Passed (Output: Executing Unix-specific logic.)
• runEverywhereButSolaris: Passed (Output: Solaris is not supported for this module.)

2. Java Runtime Conditions: JRE Version Control

With Java’s six-month release cycle, maintaining backward compatibility while adopting modern features like Records (Java 16) or Virtual Threads (Java 21) is a common challenge.

@EnabledOnJre & @EnabledForJreRange

Instead of wrapping your test logic in if (javaVersion > 11) blocks, use declarative annotations.

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.*;

class JreConditionalTest {

    @Test
    @EnabledOnJre(JRE.JAVA_8)
    void testLegacyCompatibility() {
        System.out.println("Running on legacy Java 8 environment.");
    }

    @Test
    @EnabledForJreRange(min = JRE.JAVA_17, max = JRE.JAVA_21)
    void testLtsFeatureSet() {
        System.out.println("Running on a modern LTS version.");
    }

    @Test
    @DisabledOnJre(JRE.OTHER)
    void hideFromExperimentalVersions() {
        System.out.println("Running on a stable, recognized JRE.");
    }
}

Execution Output (Running on Java 21):

• testLegacyCompatibility: Skipped (Reason: Disabled on JRE version: 21)
• testLtsFeatureSet: Passed (Output: Running on a modern LTS version.)
• hideFromExperimentalVersions: Passed

3. System Property Conditions: JVM Level Control

System properties (passed via -Dname=value) are perfect for toggling “Heavy” or “Experimental” tests without altering the source code.

@EnabledIfSystemProperty

This annotation is incredibly flexible because it supports Regular Expressions in the matches attribute.

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;

class SystemPropertyTest {

    @Test
    @EnabledIfSystemProperty(named = "test.severity", matches = "critical|high")
    void runOnlyHighSeverityTests() {
        System.out.println("Running a high-priority test case.");
    }

    @Test
    @EnabledIfSystemProperty(named = "user.language", matches = "en")
    void testEnglishLocalization() {
        System.out.println("Testing English locale specific logic.");
    }
}

Execution Output (Command: mvn test -Dtest.severity=high -Duser.language=fr):

• runOnlyHighSeverityTests: Passed (Output: Running a high-priority test case.)
• testEnglishLocalization: Skipped (Reason: System property [user.language] with value [fr] does not match regular expression [en])

4. Environment Variables: The CI/CD Standard

In modern cloud-native development, environment variables are the standard for configuration. Whether you are using Docker, Kubernetes, or GitHub Actions, variables like STAGE, DB_URL, or CI are readily available.

@EnabledIfEnvironmentVariable

This is the most common way to separate “Local Dev” tests from “CI Pipeline” tests.

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;

class PipelineTest {

    @Test
    @EnabledIfEnvironmentVariable(named = "CI", matches = "true")
    void performanceBenchmark() {
        System.out.println("Benchmark running on dedicated CI worker.");
    }

    @Test
    @EnabledIfEnvironmentVariable(named = "ENV", matches = "STAGING")
    void integrationWithExternalAPI() {
        System.out.println("Connecting to Staging API...");
    }
}

Execution Output (Running Locally where CI is unset and ENV=DEV):

• performanceBenchmark: Skipped (Reason: Environment variable [CI] does not exist)
• integrationWithExternalAPI: Skipped (Reason: Environment variable [ENV] with value [DEV] does not match [STAGING])

5. Beyond the Basics: Custom Conditions

If the built-in annotations don’t meet your needs, JUnit 5 allows you to create your own logic by implementing the ExecutionCondition interface.

Advanced: Creating a “Day of Week” Condition

import org.junit.jupiter.api.extension.*;
import java.time.DayOfWeek;
import java.time.LocalDate;

public class WeekendCondition implements ExecutionCondition {
    @Override
    public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) {
        DayOfWeek today = LocalDate.now().getDayOfWeek();
        if (today == DayOfWeek.SATURDAY || today == DayOfWeek.SUNDAY) {
            return ConditionEvaluationResult.enabled("It is the weekend!");
        }
        return ConditionEvaluationResult.disabled("Skipping: Today is " + today);
    }
}

// Usage in your test class
class CustomConditionTest {
    @Test
    @ExtendWith(WeekendCondition.class)
    void weeklyBackupStabilityTest() {
        System.out.println("Running heavy weekend-only backup test.");
    }
}

Execution Output (Running on a Wednesday):

• weeklyBackupStabilityTest: Skipped (Reason: Skipping: Today is WEDNESDAY)

6. Assumptions vs. Conditions: Which to use?

While @EnabledIf... annotations are static (determined before the test starts), sometimes you need to check a condition dynamically inside the test method. For this, use Assumptions.

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.*;

class AssumptionTest {
    @Test
    void testDatabaseConnection() {
        boolean isDbUp = false; // Mocking a down database
        assumeTrue(isDbUp, "Aborting: Database is not reachable.");
        
        System.out.println("This will not print because the assumption fails.");
    }
}

Execution Output:

• testDatabaseConnection: Aborted (Reason: Assumption failed: Aborting: Database is not reachable.)

Why This Matters?

1. Lower False Positives: Developers stop ignoring “red” builds because failures are actually relevant.
2. Resource Optimization: Don’t waste cloud compute minutes running Mac-specific UI tests on a Linux container.
3. Scalable Documentation: Your code becomes self-documenting. A newcomer can see @EnabledOnOs(OS.LINUX) and instantly know the test’s intent.

Summary of Key Annotations

By mastering these tools, you transform your test suite from a static script into a dynamic, intelligent guardian of your code quality.