JUnit Conditional Test Execution (JUnit 5 → 6)

The short answer. Nothing you wrote with @EnabledOnOs, @EnabledOnJre, @EnabledIfSystemProperty, @EnabledIfEnvironmentVariable or a custom ExecutionCondition needs to change for JUnit 6. Compared with the last JUnit 5 release, the public API of that package is identical except that the JRE enum gains JAVA_27 and JAVA_28. What does change is the floor: JUnit 6’s class files are Java 17, so a JUnit 6 test can never run on Java 8, and the 2025 article’s @EnabledOnJre(JRE.JAVA_8) example now marks a test that cannot be enabled. For the assumptions half of this topic, see JUnit 6 Assumptions and Conditional Test Execution Guide.

Versions, and honest limits. JUnit Jupiter 6.1.3, junit-platform-launcher 6.1.3, AssertJ 3.27.7, Maven Surefire 3.6.0, JDK 25.0.4.1 (Temurin), on Linux amd64. The code is the conditional module of asmhatre/JUnit_Tutorials, and every console block is quoted from a file under conditional/output/. Limits. I could only observe one machine: Linux on amd64 with Java 25. When the article says what happens on Windows, macOS or another Java version, it is reasoning from the annotations, not from a run, and it says so. The run that shows the weekend condition depends on the day it ran. Each test is started through the JUnit Platform launcher so the skip reason can be read; a normal mvn test prints the same decisions in its own format.

What a skipped test looks like, and where the decision happens

Why not just @Disabled?

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

This machine: os.name=Linux, os.arch=amd64, java.version=25.0.4.1
  OS.current()=LINUX, JRE.currentVersion()=JAVA_25

OsConditionalTest
  runEverywhereButSolaris() : PASSED
  testUnixSocketBehavior() : PASSED
  testWindowsRegistryAccess() : SKIPPED  (Disabled on operating system: Linux)

    @Test
    @EnabledOnOs(value = OS.LINUX, architectures = "aarch64")
    void onlyArmLinux() {
    }

    @Test
    @EnabledOnOs(value = OS.LINUX, architectures = {"x86_64", "amd64"})
    void onlyIntelLinux() {
    }

    @Test
    @DisabledOnOs(architectures = "aarch64")
    void anythingButArm() {
    }

ArchitectureConditionalTest
  anythingButArm() : PASSED
  onlyArmLinux() : SKIPPED  (Disabled on operating system: Linux (amd64))
  onlyIntelLinux() : PASSED

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

JreConditionalTest
  hideFromExperimentalVersions() : PASSED
  testLegacyCompatibility() : SKIPPED  (Disabled on JRE version: 25.0.4.1)
  testLtsFeatureSet() : SKIPPED  (Disabled on JRE version: 25.0.4.1)

class file major version of EnabledOnOs in 5.14.4: 52  (52 = Java 8, 61 = Java 17)
class file major version of EnabledOnOs in 6.1.3: 61  (52 = Java 8, 61 = Java 17)

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

SystemPropertyTest in a fresh JVM, three times.

No -D flags:
  runOnlyHighSeverityTests() : SKIPPED  (System property [test.severity] does not exist)
  testEnglishLocalization() : PASSED

-Dtest.severity=high -Duser.language=fr  (the command line from the 2025 article):
  runOnlyHighSeverityTests() : PASSED
  testEnglishLocalization() : SKIPPED  (System property [user.language] with value [fr] does not match regular expression [en])

-Dtest.severity=low -Duser.language=en:
  runOnlyHighSeverityTests() : SKIPPED  (System property [test.severity] with value [low] does not match regular expression [critical|high])
  testEnglishLocalization() : PASSED

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

PipelineTest in a fresh JVM, three times, with the environment set by the test.

CI unset, ENV=DEV (a developer laptop):
  integrationWithExternalAPI() : SKIPPED  (Environment variable [ENV] with value [DEV] does not match regular expression [STAGING])
  performanceBenchmark() : SKIPPED  (Environment variable [CI] does not exist)

CI=true, ENV=STAGING (a pipeline):
  integrationWithExternalAPI() : PASSED
  performanceBenchmark() : PASSED

CI=false, ENV unset:
  integrationWithExternalAPI() : SKIPPED  (Environment variable [ENV] does not exist)
  performanceBenchmark() : SKIPPED  (Environment variable [CI] with value [false] does not match regular expression [true])

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

WeekendCondition: DOES NOT COMPILE
    src/old/WeekendCondition.java:19: error: cannot find symbol
      symbol:   class Test
      location: class CustomConditionTest
    1 error

The WeekendCondition from the 2025 article, run today (2026-10-11, a SUNDAY):
  weeklyBackupStabilityTest() : PASSED

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(DayOfWeekCondition.class)
public @interface EnabledOnDays {
    DayOfWeek[] value();
}

public class DayOfWeekCondition implements ExecutionCondition {

    @Override
    public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) {
        var annotation = context.getElement().flatMap(e -> AnnotationSupport.findAnnotation(e, EnabledOnDays.class));
        if (annotation.isEmpty()) {
            return ConditionEvaluationResult.enabled("@EnabledOnDays is not present");
        }
        DayOfWeek today = context.getConfigurationParameter("demo.today")
                .map(DayOfWeek::valueOf)
                .orElseGet(() -> LocalDate.now().getDayOfWeek());
        DayOfWeek[] days = annotation.get().value();
        return Arrays.asList(days).contains(today)
                ? ConditionEvaluationResult.enabled("Today is " + today)
                : ConditionEvaluationResult.disabled("Today is " + today + ", test runs on " + Arrays.toString(days));
    }
}

demo.today=SATURDAY
  noAnnotationRunsAlways() : PASSED
  wednesdayOnly() : SKIPPED  (Today is SATURDAY, test runs on [WEDNESDAY])
  weekendOnly() : PASSED

demo.today=WEDNESDAY
  noAnnotationRunsAlways() : PASSED
  wednesdayOnly() : PASSED
  weekendOnly() : SKIPPED  (Today is WEDNESDAY, test runs on [SATURDAY, SUNDAY])

demo.today=FRIDAY
  noAnnotationRunsAlways() : PASSED
  wednesdayOnly() : SKIPPED  (Today is FRIDAY, test runs on [WEDNESDAY])
  weekendOnly() : SKIPPED  (Today is FRIDAY, test runs on [SATURDAY, SUNDAY])

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

Results
  a_runs() : PASSED
  b_skippedByAnnotation() : SKIPPED  (Disabled on operating system: Linux)
  c_abortedByAssumption() : ABORTED  (Assumption failed: database is down)

Every callback and test body that ran, in order
  @BeforeEach  a_runs
  body         a_runs
  @AfterEach   a_runs
  @BeforeEach  c_abortedByAssumption
  @AfterEach   c_abortedByAssumption

The AssumptionTest from the 2025 article, unchanged
  testDatabaseConnection() : ABORTED  (Assumption failed: Aborting: Database is not reachable.)

What the 2025 article left out: reasons, stacking, class level and an off switch

    @Test
    @EnabledOnOs(OS.WINDOWS)
    @EnabledIfSystemProperty(named = "never.set", matches = ".*")
    void bothConditionsFalse() {
    }

    /** The first is true on Linux, so the second one decides. */
    @Test
    @EnabledOnOs(OS.LINUX)
    @EnabledIfSystemProperty(named = "never.set", matches = ".*")
    void onlySecondConditionFalse() {
    }

  bothConditionsFalse() : SKIPPED  (Disabled on operating system: Linux)
  onlySecondConditionFalse() : SKIPPED  (System property [never.set] does not exist)

  methodConditionDefaultReason() : SKIPPED  (@EnabledIf("alwaysFalse") evaluated to false)
  methodConditionOwnReason() : SKIPPED  (feature flag is off)
  withOwnReason() : SKIPPED  (Disabled on operating system: Linux ==> Needs the Windows registry)

ClassLevelConditionalTest (@EnabledOnOs(WINDOWS) on the class, two test methods)
  ClassLevelConditionalTest : CONTAINER SKIPPED  (Disabled on operating system: Linux)

OsConditionalTest again, with the configuration parameter
  junit.jupiter.conditions.deactivate=org.junit.jupiter.api.condition.*
  runEverywhereButSolaris() : PASSED
  testUnixSocketBehavior() : PASSED
  testWindowsRegistryAccess() : PASSED

JUnit 5 to 6: what actually changed for conditions

# org/junit/jupiter/api/condition in junit-jupiter-api 5.14.4 (last JUnit 5 release on Maven Central) and 6.1.3

class file major version of EnabledOnOs in 5.14.4: 52  (52 = Java 8, 61 = Java 17)
class file major version of EnabledOnOs in 6.1.3: 61  (52 = Java 8, 61 = Java 17)

classes in the package: 39 in 5.14.4, 40 in 6.1.3
classes only in 6.1.3: org/junit/jupiter/api/condition/package-info.class 
classes only in 5.14.4: 

classes with an identical public and protected signature (javap): 37
classes whose signature differs: org.junit.jupiter.api.condition.AbstractJreRangeCondition org.junit.jupiter.api.condition.JRE

diff of javap org.junit.jupiter.api.condition.AbstractJreRangeCondition (5.14.4 -> 6.1.3):
    4a5
    >   static {};

diff of javap org.junit.jupiter.api.condition.JRE (5.14.4 -> 6.1.3):
    22a23,24
    >   public static final org.junit.jupiter.api.condition.JRE JAVA_27;
    >   public static final org.junit.jupiter.api.condition.JRE JAVA_28;

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

Should you even do this?

A fair answer. Use conditions for facts about where the test runs that you cannot change, such as the operating system or a native library. Do not use them to hide a test that is broken or flaky, and do not put the same skip on many tests: then the environment is deciding what your suite means. This is advice, not something the module measures, but there is one measured warning in it: a skipped test is not a failed test, and all the outputs above show builds that stay green while tests silently do not run. Write a disabledReason every time, look at the skipped count in your reports, and have at least one environment in which the important conditional tests are enabled. When a whole group of tests belongs to a stage of the build rather than to an environment, a test tag selected by the build is the clearer tool.

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

Further reading

• The code for this article: asmhatre/JUnit_Tutorials, in the conditional module, with the transcripts under conditional/output/ and its README.
• JUnit 6 Assumptions and Conditional Test Execution Guide — assumptions, and conditions from the other side.
• JUnit 6 tutorial
• JUnit 6 assertions
• JUnit 6 index
• JUnit User Guide (6.1.3), the section on conditional test execution.