Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 29 ยท JUnit advanced

Testing Exceptions, Timeouts and Async Code

Test exceptions with assertThrows, compare assertTimeout and assertTimeoutPreemptively, and test CompletableFuture code in JUnit without flaky Thread.sleep calls.

Happy-path tests are the easy ones. The bugs that hurt in production live in the unhappy paths: the withdrawal that must be refused, the call that must give up after two seconds, the background task that must report its failure to somebody. Testing those paths needs three skills: asserting that the right exception is thrown, asserting that code finishes fast enough, and testing code that finishes later, on another thread, without sprinkling Thread.sleep through your suite.

All examples run on the real JUnit library on our Java runner. The assertions were introduced in JUnit Assertions in Depth, and @Timeout in Conditions, Tags and Selecting Tests; this lesson goes deeper on how they behave and where they bite.

Three unhappy paths

Exceptions Did it fail the right way?
Timeouts Did it finish in time?
Async code Did the result arrive?

Each has a trap that makes tests flaky.

1 / 3

assertThrows in detail

assertThrows(Class<T>, Executable) runs the lambda and passes only if it throws an exception that is an instance of the given type. It also returns that exception, so you can check its message, fields and cause. Details worth knowing:

  • Subtypes pass. assertThrows(RuntimeException.class, ...) is satisfied by an IllegalArgumentException. If you need the exact class, use assertThrowsExactly.
  • No exception is a failure, and so is the wrong type; the failure message names both what was expected and what happened.
  • Keep the lambda tiny. Put only the one call that must throw inside it. If the setup also throws, the test passes for the wrong reason.
  • Check the exception, not only its class. A test that accepts any IllegalStateException will not notice that the message changed from "account closed" to "database offline".
  • assertDoesNotThrow is the opposite assertion, and it returns the value of a ThrowingSupplier when you want to continue with the result.
Java assertThrows: type, message, cause and misuse

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The two notes at the end show the real failure messages JUnit produces for a wrong exception type and for no exception at all. Learn to recognize them: "Unexpected exception type thrown" and "Expected ... to be thrown, but nothing was thrown" cover most red assertThrows runs.

assertTimeout versus assertTimeoutPreemptively

Both check that a block of code finishes within a time limit, but they work very differently.

  • assertTimeout runs your code on the test thread, waits for it to finish, and only then compares the elapsed time with the limit. A slow block is not stopped: a ten-minute loop with a one-second limit makes your test take ten minutes and then fail.
  • assertTimeoutPreemptively runs your code on a different thread and, when the limit passes, interrupts it and fails right away. The test stops waiting, but it only stops the code if that code responds to interruption (as Thread.sleep and blocking I/O do; a tight while(true) loop does not).

The price of the preemptive version is the other thread. Anything bound to the test thread, such as ThreadLocal values, the security context, or a database transaction that a Spring test opened, is not visible in the block. That surprises people more often than the timing does. The @Timeout annotation is thread-mode aware too: by default it runs on the same thread, and threadMode = SEPARATE_THREAD gives the preemptive behavior.

Java Same thread or another thread?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Both timeout assertions fail as designed (the tests assert that failure). The difference is in the notes: with assertTimeout the slow work finished on the test thread, so the test sat through all 400 ms; with the preemptive version the work ran elsewhere and was interrupted before finishing.

Async code: wait for signals, not for time

Code that returns a CompletableFuture, takes a callback, or posts to another thread cannot be checked with a plain assertEquals right after the call; the result may not exist yet. The tempting fix is Thread.sleep(500), and it is the single biggest source of flaky tests: on a fast laptop it wastes half a second, and on a loaded CI server it is sometimes too short. These are better, in order of preference:

  1. Make the code deterministic in tests. Let the code accept an Executor. In production pass a thread pool; in the test pass Runnable::run, which runs each task immediately on the calling thread. Then there is nothing to wait for.
  2. Wait on the real signal. future.get(2, SECONDS) blocks until the result arrives or throws TimeoutException; a CountDownLatch does the same for callbacks (assertTrue(latch.await(2, SECONDS))). A generous timeout costs nothing when the code is fast, because the wait ends as soon as the signal arrives.
  3. Poll with a deadline when no signal exists: check a condition every few milliseconds until it holds or the time is up. Libraries such as Awaitility package this, but it is a ten-line helper.

Failures inside the future are wrapped. get() throws ExecutionException whose cause is the real exception; join() throws CompletionException. Assert on the cause.

Java Testing CompletableFuture without sleeping

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Test a needs no waiting at all, because the inline executor finishes the work before priceOf returns. Tests b, d and e use real threads but wait for a signal with a generous limit of two seconds; they finish in a few milliseconds, and a slow machine cannot make them flaky. Test f shows the failure side: get with a short timeout throws TimeoutException when a future never completes. A small deliberate timeout is fine there, because the test is about the timeout itself.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Your lambda inside assertThrows calls a helper that creates the test data and then the method under test. The helper throws the expected exception by mistake. What is the problem?

    assertThrows accepts any matching exception thrown anywhere inside the lambda. Keep the lambda to the single call that should throw and build the data outside it.
  2. 2. A one-second assertTimeout wraps a block that takes ten seconds. What happens?

    assertTimeout cannot stop the code. It waits for completion on the same thread and then compares the elapsed time. Use assertTimeoutPreemptively (or @Timeout with a separate thread) to cut it off.
  3. 3. What is the main hidden risk of assertTimeoutPreemptively?

    Because the code runs on a separate thread, anything bound to the test thread is invisible there. That can cause confusing failures that have nothing to do with timing.
  4. 4. Which is the most reliable way to check that an asynchronous callback was called?

    A latch ends the wait the moment the signal arrives, so it is fast on good days and still safe on slow ones. A fixed sleep is either wasteful or too short.
  5. 5. future.get() on a future that failed with an IllegalStateException throws which exception?

    Future.get wraps the real failure in an ExecutionException. (CompletableFuture.join wraps it in a CompletionException instead.) Assert on getCause().

Summary

  • assertThrows accepts subtypes, returns the exception for further checks, and should wrap only the single call that must throw. assertThrowsExactly demands the exact class.
  • Check messages, custom fields and causes, not only the class, and use assertDoesNotThrow for the opposite promise.
  • assertTimeout waits on the test thread and cannot stop slow code; assertTimeoutPreemptively runs elsewhere and interrupts, but loses thread-bound state.
  • Make async code testable by injecting an Executor; otherwise wait on a signal (get(timeout), CountDownLatch) or poll with a deadline. Avoid fixed sleeps.
  • Futures wrap failures: ExecutionException from get, CompletionException from join; assert on the cause.

Next: TestNG Annotations and Lifecycle.