How do you assert in JUnit 5 that a piece of code throws a particular exception, and how do you then verify details of that exception such as its message or cause?

## The assertion `org.junit.jupiter.api.Assertions.assertThrows` has the signature: ```java static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable) ``` `Executable` is a functional interface whose single method may throw any `Throwable`, which is why you can pass a lambda that calls a checked-exception-throwing method without adding `throws` to the test. Overloads add a `String` message or a `Supplier<String>` message for extra failure context. ### What it does, step by step 1. Runs the executable. 2. **Nothing thrown** → fails: `Expected java.lang.IllegalArgumentException to be thrown, but nothing was thrown.` 3. **Something thrown that is an instance of the expected type** (including a subclass) → the assertion succeeds and *returns* that throwable, already typed as `T` so no cast is needed. 4. **Something thrown of a different type** → fails with `Unexpected exception type thrown, expected: <X> but was: <Y>`, and — importantly — the unexpected exception is attached as the cause of the `AssertionFailedError`, so the original stack trace survives into the report. Certain unrecoverable errors, notably `OutOfMemoryError`, are rethrown as-is rather than being converted into an assertion failure. ## Inspecting the returned exception The returned object is the entire value of the pattern. An exception type alone is a weak assertion — plenty of code paths throw `IllegalArgumentException`. Strengthen it: - **Message.** `assertTrue(ex.getMessage().contains("accountId"))` or, when the message is a stable contract, `assertEquals`. Prefer `contains` or a regex for messages that embed variable data. - **Typed fields.** Domain exceptions should carry structured data — an error code, an entity id, a validation field name. Asserting `ex.errorCode()` is far more robust than parsing prose, and it survives copy changes and internationalisation. - **Cause chain.** Frameworks wrap: a JDBC failure surfaces as a `DataAccessException` whose cause is a `SQLException`; reflective invocation wraps in `InvocationTargetException`; a `Future` wraps in `ExecutionException`. Assert `ex.getCause()` — often `assertInstanceOf(SQLException.class, ex.getCause())` — when the wrapping is part of the contract, and `assertSame(original, ex.getCause())` when the requirement is that the *original* instance is propagated. - **Suppressed exceptions.** For try-with-resources scenarios, `ex.getSuppressed()` can be asserted too. `assertInstanceOf(Type.class, value)` (JUnit 5.8+) is the idiomatic way to check a cause's type, because it also returns the value narrowed to that type for further assertions. ## Scoping the lambda Only the call whose failure you are asserting belongs inside the executable: ```java // weak: any of three calls could produce the exception assertThrows(IllegalStateException.class, () -> { var account = repo.load(id); account.freeze(); account.withdraw(10); }); // strong var account = repo.load(id); account.freeze(); assertThrows(IllegalStateException.class, () -> account.withdraw(10)); ``` The first version passes if `repo.load` throws — a setup failure masquerading as verified behaviour. Keep arrangement outside; keep the lambda to a single statement whenever you can. ## Why not try/catch/fail Before lambdas, the idiom was: ```java try { account.withdraw(500); fail("expected InsufficientFunds"); } catch (InsufficientFunds expected) { assertEquals(..., expected.getMessage()); } ``` This works but is verbose, easy to get wrong (forgetting `fail`, or catching so broadly that the `fail` call's own `AssertionError` is swallowed by the catch block), and hides the intent. `assertThrows` is the modern replacement and should be used unconditionally in new code. JUnit 4's `@Test(expected = X.class)` had a worse problem than verbosity: it matched an exception thrown *anywhere* in the test method, including setup, and gave no handle on the exception object. JUnit 5 removed it deliberately — there is no `expected` attribute on Jupiter's `@Test`. ## Common failure modes - **Asserting a supertype.** `assertThrows(Exception.class, ...)` or `RuntimeException.class` passes for a `NullPointerException` caused by a typo. Name the narrowest type that expresses the behaviour, and consider `assertThrowsExactly` when a subtype would be a genuine defect. - **Nothing to throw.** A lambda that merely creates a stream or a builder without a terminal call executes nothing lazily; the assertion then fails with "nothing was thrown" even though the code is broken in the expected way. Make sure the lambda actually triggers evaluation. - **Swallowing inside the lambda.** If the code under test catches and logs, no exception escapes and the assertion fails — which is correct, but candidates often blame the assertion. ## Kotlin and other JVM languages The same API applies; in Kotlin the lambda is a trailing block and the returned exception is a normal value, so `val ex = assertThrows<InsufficientFunds> { account.withdraw(500) }` reads naturally.