JUnit EnabledIf DisabledIf Conditional Test Execution Guide
Run JUnit tests only when a condition holds: EnabledOnOs, EnabledForJreRange, EnabledIfEnvironmentVariable, EnabledIf and custom ExecutionCondition.

Some tests need a Linux filesystem, a specific JDK, a cloud credential or a service that exists only in CI. Running them elsewhere produces failures that mean nothing, and developers learn to ignore red builds. JUnit conditions skip such tests cleanly and print the reason. This guide covers the built-in conditions, method-based conditions, a custom condition and the one habit that stops skipped tests from hiding a broken suite. Examples use JUnit 5.13 and apply to JUnit 6.
Operating system and Java version
@Test
@EnabledOnOs(OS.LINUX)
void readsProcFilesystem() { /* ... */ }
@Test
@DisabledOnOs(OS.WINDOWS)
void usesPosixPermissions() { /* ... */ }
@Test
@EnabledForJreRange(min = JRE.JAVA_21)
void usesVirtualThreads() { /* ... */ }@EnabledOnJre takes specific versions, and @EnabledForJreRange takes a range, which suits code that exercises features of newer JDKs. The ranges track the enum constants in your JUnit version, so a very new JDK may need JRE.OTHER or a newer JUnit before the annotation recognises it. Prefer the OS and JRE annotations to hand-written System.getProperty checks, because the report states the reason for the skip.
System properties and environment variables
@Test
@EnabledIfSystemProperty(named = "os.arch", matches = ".*aarch64.*")
void armOnlyBehaviour() { /* ... */ }
@Test
@EnabledIfEnvironmentVariable(named = "CI", matches = "true")
void runsOnlyInCi() { /* ... */ }
@Test
@DisabledIfEnvironmentVariable(named = "OFFLINE", matches = "1")
void callsTheRealApi() { /* ... */ }matches is a regular expression applied to the whole value. When the variable is unset, the Enabled form disables the test, because there is nothing to match. This is how a test that needs a cloud credential stays quiet on a laptop and runs in the pipeline that sets the variable. Keep the variable names in one constants class if several tests use them, so the contract with the CI configuration is in one place.
Let a method decide
@Test
@EnabledIf("dockerAvailable")
void talksToPostgres() { /* ... */ }
static boolean dockerAvailable() {
try {
return new ProcessBuilder("docker", "info").start().waitFor() == 0;
} catch (Exception e) {
return false;
}
}The named method must return boolean and take no parameters. It is an instance method, or static if the class uses the default per-method lifecycle, and "com.acme.Env#dockerAvailable" points at a method in another class. This is how tests that need Testcontainers avoid failing on a machine without Docker; the failure they replace is described in Docker environment not found. Make the check cheap and total: it runs before the test, and an exception from it fails the test instead of skipping it.
A custom condition
@Target({TYPE, METHOD})
@Retention(RUNTIME)
@ExtendWith(RequiresDatabaseCondition.class)
public @interface RequiresDatabase { }
class RequiresDatabaseCondition implements ExecutionCondition {
@Override
public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext ctx) {
return Db.reachable()
? ConditionEvaluationResult.enabled("database reachable")
: ConditionEvaluationResult.disabled("no database on this machine");
}
}When several tests share a rule, a composed annotation reads better than the same @EnabledIf repeated, and the reason string appears in the report. An ExecutionCondition is evaluated before the test instance is created, which is the right moment to decide, and the extension model behind it is described in writing a JUnit extension.
Skipped is not passed
JUnit marks the test as skipped and prints the reason, and many pipelines count skipped tests as green. That is how an entire integration suite can silently stop running: someone renames the environment variable, every test becomes disabled and the build stays green for a month. Protect against it. Fail the stage when the skipped count for a tag is unexpectedly high, or run the conditional suite only on agents where the condition is guaranteed, and assert in the pipeline that the number of executed tests is above a floor. Selecting by tags makes that easy.
Assumptions
For a decision that can only be made while the test runs, use an assumption.
@Test
void usesTheCache() {
assumeTrue(cache.isWarm(), "cache not warm");
// the rest runs only if the assumption held
}An assumption that fails aborts the test instead of failing it, which is the imperative form of the same idea. Use it sparingly, since a test that aborts halfway is harder to reason about than one that never starts.
Conditions in a build matrix
A matrix of JDK versions in CI is the natural partner of these annotations. The same test class runs on 21 and 25, and @EnabledForJreRange or @DisabledOnJre removes the tests that cannot run on one of them. The alternative, excluding classes in the build file, hides the reason from the person reading the test, and the exclusion drifts from the code over time. Keep the rule next to the test it affects.
Combine conditions with care. Stacking @EnabledOnOs and @EnabledIfEnvironmentVariable on one method requires all of them to hold, since each annotation contributes a condition and a test runs only if none disables it. That is usually what you want, and it is worth a comment when the combination is not obvious.
Reporting skips usefully
The reason string is the only thing a reader sees in the CI summary, so write it for them. "Disabled on Windows" is better than nothing, and "no Docker daemon reachable at /var/run/docker.sock" tells the next person how to fix it. Surefire and Gradle both print skipped counts per class. If you use a dashboard, tag the integration tests so it can show how many ran and how many were skipped, not only how many failed.
Testing the condition itself
A custom condition is code, and it deserves a test. Call evaluateExecutionCondition with a stub ExtensionContext for the enabled and the disabled case, or use the JUnit Platform Test Kit to run a small test class and assert that its tests were skipped with the expected reason. Without such a test, the condition can start returning "enabled" for the wrong environment and nobody notices until the suite hits a machine that lacks the dependency.
Conditions and parameterised tests
Conditions apply to parameterised and repeated tests as well. Put the annotation on the method and the whole set of invocations is skipped together. To skip a single argument, filter inside the source or use an assumption in the body, because the condition annotations decide before any invocation starts.
Documenting why a test is conditional
A condition without a comment becomes a mystery within a year. Put the reason next to the annotation, with the issue or the environment constraint, and remove the condition when the constraint ends. A short list of the conditional suites in the project README, with how to enable each locally, spares new developers from wondering why half the tests never run on their machine.
When a condition is the wrong tool
@Disabled switches a test off with a reason, and belongs only to a bug you are fixing right now; never leave one without an issue link and an owner. A condition that is almost always true is dead code. And for environment checks in the build itself, such as the JDK, configure the build, as in the Maven compiler setup. The reference is the user guide on conditional test execution, the [Assumptions Javadoc](https://docs.junit.org/current/api/org.junit.jupiter.api/org/junit/jupiter/api/Assumptions.html) covers runtime checks, and lifecycle describes when conditions are evaluated.


