Assertions & Assumptions

assertEquals compares with equals() — value equality. assertSame compares with == — the same object in memory. Use assertSame only when identity is the contract you are testing: caches, interned or flyweight instances, singletons, or a method that returns this.

Call assertThrows(ExpectedType.class, () -> codeUnderTest()). It fails if nothing is thrown or if the thrown type does not match, and on success it returns the thrown exception, typed, so you can go on asserting its message, cause or custom fields.

assertAll takes lambdas, runs every one of them even after some fail, then reports all failures together in one aggregated error. Use it for independent checks on the same object so a single run shows every problem instead of only the first.

Use Assertions.assertTimeout(Duration.ofMillis(500), () -> code). It runs the block on the test thread, then fails if it took longer, reporting the expected budget and how much it overran. A supplier form returns the block's value.

Arrays inherit Object.equals, which is reference identity, so assertEquals on two distinct arrays fails even with identical contents. Use assertArrayEquals for element-wise, recursive array comparison, and assertIterableEquals to compare any two Iterables element-wise without requiring the same collection type.

Binary floating point cannot represent most decimals exactly, so arithmetic results drift by tiny amounts — 0.1 + 0.2 is not 0.3. The delta is the tolerance: the assertion passes when the absolute difference is at most delta. Pick it from the magnitudes and the number of operations, not by habit.

A String message is built every time the assertion runs, including when it passes. A Supplier<String> is only invoked when the assertion fails, so use it whenever building the message costs something — concatenation in a loop, serializing an object, formatting collections.

assertTimeout runs the block on the test thread, lets it finish, then fails if it overran. assertTimeoutPreemptively runs it on a separate thread and aborts at the deadline, so it can catch hangs — but the code loses the test thread's thread-local state.

JUnit 4 put the message first; JUnit 5 puts it last. With three Strings the call still compiles, so JUnit 5 compares the message text against the expected name and treats the actual name as the message — hence the confusing output.

It is org.opentest4j.TestAbortedException, which Jupiter maps to aborted rather than failed. Thrown from @BeforeEach it aborts that single test; thrown from @BeforeAll it aborts the whole container, so every test in the class is reported as skipped.

assumeTrue aborts the whole test when the condition is false. assumingThat never aborts: it runs the supplied lambda only when the condition holds, and the rest of the test method continues either way — so it gates a section, not the whole test.

All of them are null-safe: both arguments null passes, one null fails with a message naming which side was null — no NullPointerException. Still prefer assertNull and assertNotNull for null checks, because they state intent and avoid overload-resolution problems with a bare null literal.

assertDoesNotThrow runs a block and fails with a clear message if it throws anything. One form takes a void Executable; the other takes a ThrowingSupplier and returns the produced value. Its real value is scoping intent and swallowing checked exceptions so the test signature stays clean — not raw pass/fail, which you get anyway.

assertThrows passes for the named type or any subclass of it; assertThrowsExactly passes only when the thrown object's class is exactly the named one. Use the exact form when a subclass would signal a different failure — for example when IllegalArgumentException is required but NumberFormatException would be wrong.

Besides Executable varargs, assertAll accepts a Collection<Executable> and a Stream<Executable>, each with an optional leading heading String. The lambdas implement org.junit.jupiter.api.function.Executable — void execute() throws Throwable — so they may call methods that throw checked exceptions.

Two or more failures are aggregated into org.opentest4j.MultipleFailuresError, whose message shows the heading plus the failure count and lists each failure (they are also attached as suppressed exceptions). If exactly one executable fails, that original throwable is rethrown unchanged.

fail() unconditionally throws AssertionFailedError, failing the test immediately. Overloads take a String message, a Supplier<String>, a Throwable cause, or a message plus cause. Its return type is generic so it can be used where a value is required, for example return fail("unreachable").

An assumption probes at runtime inside the test or its setup, so it can perform real checks like opening a socket, but the class is instantiated first and the skip is only visible in the report. A declarative condition is evaluated before instantiation, is visible on the signature, and suits statically knowable facts such as an OS or an environment variable.

Put only the call under test inside the assertion lambda and keep arrangement above it; expect the narrowest exception type that expresses the behaviour; and always assert something identifying on the returned exception — an error code, a typed field, or a message fragment — rather than accepting any exception of that type.

Every lambda in a group always runs, so preconditions cannot live beside the checks that depend on them. Assert the precondition fail-fast before the group, or nest an inner assertAll inside a lambda that first asserts the precondition — the inner group only runs if it survives.

Messages earn their place when the default output is uninformative — assertTrue, assertNotNull — or when the same assertion runs many times and you need to know which input failed. They hurt when they restate the assertion, or when they go stale and describe intent the code no longer has.

Wall-clock budgets measure the machine as much as the code. Check whether CI is slower, noisier or colder (JIT, GC, shared runners, cold caches). Keep timeout assertions only as order-of-magnitude regression guards with generous budgets; move real latency checks to a benchmark or production SLO.

Preemptive timeouts run the block on a separate thread, so ThreadLocal state — Spring's transaction and persistence context, the security context, MDC — is not visible there, and cancellation is only an interrupt, so uninterruptible work keeps running. Fix: use plain assertTimeout, or propagate context explicitly.

assertLinesMatch compares text line by line, but each expected line may be a literal, a regular expression matching the whole line, or a fast-forward marker like >> 3 >> or >> anything >> that skips lines. That lets you assert stable parts of multi-line output while tolerating timestamps, ids and unbounded filler.

Make skips visible and bounded: require a specific reason on every assumption, track aborted counts per build, fail the build when a category that should run is skipped or when executed-test counts drop, and periodically decide to either provide the missing environment or delete the test.

Separate two concerns: hang protection is policy — one global JUnit timeout plus per-test overrides, enforced declaratively — while performance verification belongs in benchmarks and production SLOs. Keep only a few coarse timeout assertions as regression guards, and never retry or auto-widen them.