Assumptions
Not every test applies to every machine. A test of a Linux-only path, a feature of a newer JDK or a service that is not running should say so instead of failing. An assumption is that statement: when it is false, the test is aborted, the run stays green, and the table counts an aborted test rather than a failed one.
An assumption
assumeTrue(condition) checks a condition at the start of a test. If it is true, the test continues; if it is false, Jupiter throws an AbortedException and the launcher records an aborted test. A second argument is the reason, which the report prints. assumeFalse is the same with the opposite condition.
One test that needs a newer JDK
OsTest.java has one test that needs a JDK newer than 99 and one that always runs. The first assumption is false on Java 21, so the test aborts; the second runs and passes.
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assumptions.assumeTrue;
import org.junit.jupiter.api.Test;
public class OsTest {
@Test
void onlyOnLinux() {
assumeTrue(Runtime.version().feature() > 99, "needs a future JDK");
assertEquals(4, 2 + 2);
}
@Test
void alwaysRuns() {
assertEquals(4, 2 + 2);
}
}
The method name still says onlyOnLinux from an earlier draft; the condition is now about the JDK version. Rename it when the condition changes, because the name is the first thing a reader trusts.
The report
javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out OsTest.java
junit execute --class-path out --scan-classpath --disable-ansi-colors
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ OsTest ✔
│ ├─ onlyOnLinux() ■ Assumption failed: needs a future JDK
│ └─ alwaysRuns() ✔
└─ JUnit Vintage ✔
Test run finished after 268 ms
[ 4 containers found ]
[ 0 containers skipped ]
[ 4 containers started ]
[ 0 containers aborted ]
[ 4 containers successful ]
[ 0 containers failed ]
[ 2 tests found ]
[ 0 tests skipped ]
[ 2 tests started ]
[ 1 tests aborted ]
[ 1 tests successful ]
[ 0 tests failed ]
Aborted, not failed
The tree prints a small square and the reason, and the table has one aborted test and one successful one. The run returns 0, because an aborted test is not a failure. The four words are distinct: skipped was disabled before the run, aborted started and decided the case did not apply, failed ran and was wrong, successful ran and was right.
An assumption that is false for everyone is a disabled test written the long way. The difference is that an assumption is evaluated on each machine, so the same test can run on one JDK and abort on another; that is the case it is for.
assumingThat
assumingThat(condition, lambda) runs only the part inside the lambda when the condition is true and skips that part when it is false. The test itself still runs and can pass; it is the conditional section that disappears. Use it for an optional check inside a test that has a mandatory part, not for the whole test.
The assumptions live in org.junit.jupiter.api.Assumptions, a different class from Assertions. The import is worth checking when a test compiles but the names look wrong.
Exercises
- Change the condition to true and run. Which counts change, and what is the status?
- Replace the assumption with assertTrue and run. How does the tree line differ?
- Give the assumption no reason and read the tree line. What is missing?
- Add an assumingThat around a second assertion that is false and explain why the test still passes.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What happens when an assumption is false?
Answer
The test is aborted and the run stays green
An assumption marks the case as not applicable; the launcher counts it as aborted, not failed.
-
Which count grows when a test is aborted?
Answer
tests started and tests aborted
The test started and then aborted, so both counters move.
-
What is the difference between skipped and aborted?
Answer
Skipped was disabled before the run; aborted started and found the case did not apply
Disabled tests are skipped; assumptions are evaluated at run time and abort the test.
-
What does this program print?
public class Q1 { public static void main(String[] args) { System.out.println(2 + 2 == 4); } }Answer
true
The sum is 4 and the comparison is true.
-
What does this program print?
public class Q2 { public static void main(String[] args) { boolean linux = false; System.out.println(linux); } }Answer
false
The variable holds false, and println prints the word false.
-
What does this program print?
public class Q3 { public static void main(String[] args) { int feature = 21; System.out.println(feature > 99); } }Answer
false
21 is not greater than 99, so the comparison is false.
-
What does this program print?
public class Q4 { public static void main(String[] args) { String reason = "needs a future JDK"; System.out.println(reason.length()); } }Answer
18
The sentence has 18 characters, spaces included.
-
What does
assumingThat(false, lambda)do?Answer
Skips the lambda and lets the test continue
assumingThat guards only its own block; the rest of the test still runs and can pass.
-
Where do the assumption methods live?
Answer
org.junit.jupiter.api.Assumptions
Assumptions is a separate class from Assertions, with assumeTrue, assumeFalse and assumingThat.
-
What does this program print?
public class Q5 { public static void main(String[] args) { System.out.println(2 + 2); } }Answer
4
The two integers are added, and println prints 4.
The code on this page was built with OpenJDK 21.0.13 (javac) and run with JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container.
Article author: Arthur Isaev