No exception and a time limit

Two promises are the mirror of the previous lesson: a call that must return without throwing, and a call that must finish in time. assertDoesNotThrow states the first, assertTimeout the second. Neither needs a special runner; both are ordinary assertions with a lambda.

The class and two tests

Slow.java adds the numbers from 1 to n. It is not actually slow, which makes it a safe example for a time limit: the test has plenty of room, and the limit shows where it belongs.

public class Slow { static int sum(int n) { int total = 0; for (int i = 1; i <= n; i++) { total += i; } return total; } }

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertTimeout; import java.time.Duration; import org.junit.jupiter.api.Test; public class SlowTest { @Test void doesNotThrow() { assertDoesNotThrow(() -> Slow.sum(3)); } @Test void finishesInTime() { int result = assertTimeout(Duration.ofMillis(200), () -> Slow.sum(3)); assertEquals(6, result); } }

assertDoesNotThrow

The assertion runs the lambda and passes if it returns normally. If it throws, the test fails with the thrown exception, which is the report a normal method call would produce. The assertion is useful when the test is about the absence of an exception and the return value is not interesting, as in a smoke test of a constructor.

It is not a way to hide an exception: the failure still names the type and the stack. The difference from calling the method directly is the message and the shape of the report, not the verdict.

assertTimeout

assertTimeout(Duration.ofMillis(200), lambda) runs the lambda on the test thread and measures how long it takes. If it takes longer, the test fails after the lambda has finished, and the report says how long it took. The call is not interrupted, so a lambda with a side effect still completes the side effect.

The limit is wall-clock time, not CPU time, and it includes the time the thread waits. A loaded machine can fail a correct test, so the limit should be generous enough to survive a slow CI machine and tight enough to catch the regression it is about. A limit of 200 ms for a loop of three additions has that room.

The returned value

Both assertions return what the lambda returned, so the test can assert on it after the time check. The lambda must be a ThrowingSupplier: a function that returns a value and may throw. A lambda that returns nothing uses the Executable overload, and the assertion returns nothing.

The report

javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out Slow.java SlowTest.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 ✔
│  └─ SlowTest ✔
│     ├─ doesNotThrow() ✔
│     └─ finishesInTime() ✔
└─ JUnit Vintage ✔

Test run finished after 290 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         ]
[         0 tests aborted         ]
[         2 tests successful      ]
[         0 tests failed          ]

Exercises

  1. Lower the limit to Duration.ofNanos(1) and run. What does the failure line say, and was the lambda interrupted?
  2. Make sum throw for a negative n and call it with -1 inside assertDoesNotThrow. What does the report print?
  3. Add a System.out.println inside the timed lambda and run. Is the line printed before the failure with a tiny limit?
  4. Change the timed assertion to assertTimeoutPreemptively and compare the two reports.

Questions

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

  1. What does assertDoesNotThrow check?

    Answer

    The lambda returns without throwing

    The assertion passes when the call returns normally and fails with the exception otherwise.

  2. When does assertTimeout fail?

    Answer

    When the lambda takes longer than the limit, after it finishes

    The non-preemptive form measures the call and fails after it returns, without interrupting it.

  3. What does assertTimeout return?

    Answer

    The value the lambda returned

    The result is passed through, so the test can assert on it after the time check.

  4. What does this program print? public class Q1 { public static void main(String[] args) { int total = 0; for (int i = 1; i != 4; i++) { total += i; } System.out.println(total); } }

    Answer

    6

    The loop adds 1, 2 and 3, and stops when i is 4.

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

    Answer

    200

    The duration was built from 200 milliseconds, and toMillis returns 200.

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

    Answer

    6

    The formula for 1 + 2 + 3 gives 6.

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

    Answer

    4

    The word has four letters.

  8. Why should a time limit be generous?

    Answer

    A loaded machine can make a correct test slower than the limit

    Wall-clock time includes scheduling and load, so a tight limit is a flaky test.

  9. What does a non-preemptive timeout do to a side effect in the lambda?

    Answer

    The lambda finishes it, because it is not interrupted

    The assertion waits for the call and only then reports the failure.

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

    Answer

    6

    The integers are added from left to right, and the sum is 6.

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