In JUnit 5, assumptions let you run a test only when certain conditions are true. If an assumption fails, the test is skipped/aborted, not failed.
They are useful when a test depends on things like:
- operating system
- environment variables
- external services
- database availability
- specific Java version
- local developer setup
JUnit assumptions are available from:
import static org.junit.jupiter.api.Assumptions.*;
Basic Example
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
import static org.junit.jupiter.api.Assertions.assertEquals;
class EnvironmentTest {
@Test
void testOnlyRunsOnCiServer() {
assumeTrue("true".equals(System.getenv("CI")));
int result = 2 + 3;
assertEquals(5, result);
}
}
If the environment variable CI is not set to "true", this test is skipped.
It does not fail.
Using assumeTrue()
assumeTrue() allows the test to continue only if the condition is true.
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
import static org.junit.jupiter.api.Assertions.assertTrue;
class OperatingSystemTest {
@Test
void testOnlyOnLinux() {
assumeTrue(System.getProperty("os.name").toLowerCase().contains("linux"));
assertTrue(true);
}
}
This test only runs on Linux.
Using assumeFalse()
assumeFalse() is the opposite. The test continues only if the condition is false.
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.assumeFalse;
import static org.junit.jupiter.api.Assertions.assertEquals;
class LocalEnvironmentTest {
@Test
void testDoesNotRunInProduction() {
assumeFalse("prod".equals(System.getenv("APP_ENV")));
assertEquals(4, 2 + 2);
}
}
If APP_ENV is "prod", the test is skipped.
Adding a Message
You can add a message to explain why the test was skipped.
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
import static org.junit.jupiter.api.Assertions.assertEquals;
class JavaVersionTest {
@Test
void testOnlyOnSpecificJavaVersion() {
assumeTrue(
System.getProperty("java.version").startsWith("25"),
"This test only runs on Java 25"
);
assertEquals(10, 5 + 5);
}
}
The message helps explain the skipped test in the test report.
Using assumingThat()
assumingThat() lets you run only part of a test conditionally.
Unlike assumeTrue(), it does not skip the whole test. It only skips the block of code inside it.
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.assumingThat;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
class ConditionalBlockTest {
@Test
void testWithConditionalSection() {
assertEquals(4, 2 + 2);
assumingThat(
"dev".equals(System.getenv("APP_ENV")),
() -> {
assertTrue(true);
System.out.println("Extra checks for development environment");
}
);
assertEquals(6, 3 + 3);
}
}
In this example:
- the first assertion always runs
- the conditional block runs only when
APP_ENVis"dev" - the last assertion always runs
Difference Between Assertions and Assumptions
| Feature | Assertion | Assumption |
|---|---|---|
| Purpose | Verify expected behavior | Check whether test should run |
| If condition fails | Test fails | Test is skipped |
| Common methods | assertEquals(), assertTrue() |
assumeTrue(), assumeFalse() |
| Used for | Validating code correctness | Checking test prerequisites |
Example: Skipping Test If Database Is Not Available
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
import static org.junit.jupiter.api.Assertions.assertEquals;
class DatabaseTest {
@Test
void testDatabaseQuery() {
assumeTrue(isDatabaseAvailable(), "Database is not available");
String result = "John";
assertEquals("John", result);
}
private boolean isDatabaseAvailable() {
// In a real test, you might check a connection here.
return false;
}
}
Since isDatabaseAvailable() returns false, the test is skipped.
Common Assumption Methods
JUnit 5 provides these commonly used methods:
assumeTrue(condition);
assumeTrue(condition, message);
assumeFalse(condition);
assumeFalse(condition, message);
assumingThat(condition, executable);
When Should You Use Assumptions?
Use assumptions when the test depends on something outside the code being tested.
Good examples:
assumeTrue(System.getenv("CI") != null);
assumeTrue(System.getProperty("os.name").contains("Linux"));
assumeFalse("prod".equals(System.getenv("APP_ENV")));
Avoid using assumptions to hide broken tests. If the code is wrong, use assertions and let the test fail.
Summary
Assumptions in JUnit are used to skip tests when required conditions are not met.
Use:
assumeTrue(condition);
when a test should continue only if a condition is true.
Use:
assumeFalse(condition);
when a test should continue only if a condition is false.
Use:
assumingThat(condition, () -> {
// conditional checks
});
when only part of a test should run conditionally.