A test that is interrupted

The previous lesson waited for a slow call and then reported that it was slow. assertTimeoutPreemptively does not wait: it runs the call on another thread and interrupts it at the deadline. The report is red, and the test stops instead of holding the suite for the whole call. This lesson runs a test that sleeps three times longer than its limit.

A test that sleeps too long

Sleeper.java has one method that sleeps for a given number of milliseconds. SleeperTest.java gives it 300 ms and a limit of 100 ms, so the test must be stopped by the deadline.

public class Sleeper { static void rest(long millis) throws InterruptedException { Thread.sleep(millis); } }

import static org.junit.jupiter.api.Assertions.assertTimeoutPreemptively; import java.time.Duration; import org.junit.jupiter.api.Test; public class SleeperTest { @Test void mustFinishQuickly() { assertTimeoutPreemptively(Duration.ofMillis(100), () -> Sleeper.rest(300)); } }

assertTimeoutPreemptively

The assertion starts the lambda in a separate thread, waits at most the duration, and interrupts the thread when the time is up. If the lambda finishes first, the assertion returns its value. If not, the test fails with execution timed out after 100 ms and an ExecutionTimeoutException as the cause.

The interruption is cooperative: a method that ignores the interrupt flag can keep running after the test has failed. Thread.sleep and most blocking I/O respect it, which is why the sleeper stops; a tight loop that never checks the flag would not. The assertion stops waiting, not necessarily the work.

The red report

javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out Sleeper.java SleeperTest.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 ✔
│  └─ SleeperTest ✔
│     └─ mustFinishQuickly() ✘ execution timed out after 100 ms
└─ JUnit Vintage ✔

Failures (1):
  JUnit Jupiter:SleeperTest:mustFinishQuickly()
    MethodSource [className = 'SleeperTest', methodName = 'mustFinishQuickly', methodParameterTypes = '']
    => org.opentest4j.AssertionFailedError: execution timed out after 100 ms
       org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:152)
       org.junit.jupiter.api.AssertTimeoutPreemptively.createAssertionFailure(AssertTimeoutPreemptively.java:132)
       org.junit.jupiter.api.AssertTimeoutPreemptively.resolveFutureAndHandleException(AssertTimeoutPreemptively.java:116)
       org.junit.jupiter.api.AssertTimeoutPreemptively.assertTimeoutPreemptively(AssertTimeoutPreemptively.java:82)
       org.junit.jupiter.api.AssertTimeoutPreemptively.assertTimeoutPreemptively(AssertTimeoutPreemptively.java:65)
       [...]
     Caused by: org.junit.jupiter.api.AssertTimeoutPreemptively$ExecutionTimeoutException: Execution timed out in thread junit-timeout-thread-1
       java.base/java.lang.Thread.sleep0(Native Method)
       java.base/java.lang.Thread.sleep(Thread.java:509)
       Sleeper.rest(Sleeper.java:3)
       SleeperTest.lambda$mustFinishQuickly$0(SleeperTest.java:10)
       java.base/java.util.concurrent.FutureTask.run(FutureTask.java:317)
       [...]

Test run finished after 377 ms
[         4 containers found      ]
[         0 containers skipped    ]
[         4 containers started    ]
[         0 containers aborted    ]
[         4 containers successful ]
[         0 containers failed     ]
[         1 tests found           ]
[         0 tests skipped         ]
[         1 tests started         ]
[         0 tests aborted         ]
[         0 tests successful      ]
[         1 tests failed          ]

The interruption

The cause names the thread the lambda ran on: Execution timed out in thread junit-timeout-thread-1. The thread number is the launcher's, not part of the contract, and it changes when several timed tests run. The stack below shows where the thread was interrupted: inside Thread.sleep, called by Sleeper.rest.

The elapsed time in this report is 377 ms, not 100 ms, because the launcher waits for the interrupted thread to finish before it prints. The 300 ms sleep started immediately, the interrupt arrived at 100 ms, and the thread returned from sleep soon after.

Against the plain timeout

assertTimeout is the safer default: it does not create a thread, it does not interrupt, and it sees the thread-local state the test changed. Its failure is slower, because it waits for the call. assertTimeoutPreemptively is for a call that must be stopped: a network read with no timeout of its own, a loop that may not terminate.

The preemptive form has a cost: the lambda runs on another thread, so a ThreadLocal set by the test is not visible, and an interrupt can leave the shared state of the class half changed. Use it when the alternative is a hang, and keep the lambda small.

Exercises

  1. Raise the limit to 400 ms and run. Does the test pass, and how long does the run take?
  2. Change the sleeper to a loop that ignores interruption and run. Does the launcher still return at 100 ms?
  3. Add a second timed test with the same limit and compare the thread names in the two failures.
  4. Replace the preemptive assertion with assertTimeout. Which lines of the report change?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does assertTimeoutPreemptively do at the deadline?

    Answer

    It interrupts the thread that runs the lambda

    The preemptive form runs the lambda on another thread and interrupts it at the limit.

  2. What is the cause of the failure in the report?

    Answer

    AssertTimeoutPreemptively$ExecutionTimeoutException

    The ExecutionTimeoutException names the thread and is attached as the cause.

  3. When is the preemptive form the right choice?

    Answer

    When a call may hang and must be stopped

    It is for code that cannot be allowed to block the suite; the plain form is safer otherwise.

  4. What does this program print? public class Q1 { public static void main(String[] args) { System.out.println(300 - 100); } }

    Answer

    200

    The subtraction gives 200, and println prints it.

  5. What does this program print? public class Q2 { public static void main(String[] args) { System.out.println(java.time.Duration.ofMillis(100).toMillis()); } }

    Answer

    100

    The duration was built from 100 milliseconds.

  6. What does this program print? public class Q3 { public static void main(String[] args) { int n = 5; System.out.println(n / 2); } }

    Answer

    2

    Integer division truncates, so 5 divided by 2 is 2.

  7. What does this program print? public class Q4 { public static void main(String[] args) { String text = "timeout"; System.out.println(text.startsWith("time")); } }

    Answer

    true

    timeout begins with time, so startsWith is true.

  8. Why can a preemptive timeout leave shared state half changed?

    Answer

    The lambda runs on another thread and is interrupted where it stands

    An interrupt stops the work at an arbitrary point, so a side effect may not be finished.

  9. What does this program print? public class Q5 { public static void main(String[] args) { System.out.println(1 + 2); } }

    Answer

    3

    The two integers are added, and the sum is 3.

  10. Which form waits for the lambda before it reports the failure?

    Answer

    assertTimeout

    The plain timeout measures the finished call; the preemptive one interrupts at the limit.

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

Banner image