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

  1. Change the condition to true and run. Which counts change, and what is the status?
  2. Replace the assumption with assertTrue and run. How does the tree line differ?
  3. Give the assumption no reason and read the tree line. What is missing?
  4. 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.

  1. 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.

  2. Which count grows when a test is aborted?

    Answer

    tests started and tests aborted

    The test started and then aborted, so both counters move.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. Where do the assumption methods live?

    Answer

    org.junit.jupiter.api.Assumptions

    Assumptions is a separate class from Assertions, with assumeTrue, assumeFalse and assumingThat.

  10. 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