In TestNG's org.testng.Assert, what is the difference between assertThrows and expectThrows, and how do you check the thrown exception's message?
answer
- one hands something back
- a lambda that may throw
- subclasses satisfy the check
- the message parameter leads
basics
~20 sBoth run a lambda and fail if it throws nothing or an exception that is not an instance of the expected class. assertThrows returns void; expectThrows returns the caught exception, so you can then assert on its message or cause.
solid answer
~40 s`Assert.assertThrows(Class<T>, ThrowingRunnable)` and `Assert.expectThrows(Class<T>, ThrowingRunnable)` both run the lambda and throw an `AssertionError` if nothing is thrown or the thrown object is not an instance of the expected class; subclasses count, so an `IllegalStateException` satisfies `RuntimeException.class`. `assertThrows` returns `void`; `expectThrows` returns the exception, which is how you check details: capture it, then `assertEquals(ex.getMessage(), "account id must be numeric: 12x")`. On a type mismatch, the exception that was actually thrown is attached as the `AssertionError`'s cause. In TestNG 7.12 both also take a custom message, and it goes **first**, as in `assertThrows("rejects blank id", IllegalArgumentException.class, () -> parse(""))`, unlike `assertEquals`, where it trails. Scoping the check to one lambda is also what makes it more precise than a whole-method expected exception.
code
java · 33 linesimport static org.testng.Assert.assertEquals;
import static org.testng.Assert.assertThrows;
import static org.testng.Assert.expectThrows;
import org.testng.annotations.Test;
public class AccountIdTest {
@Test
public void rejectsBlankId() {
assertThrows("blank id must be rejected",
IllegalArgumentException.class, () -> AccountId.parse(""));
}
@Test
public void explainsWhyIdIsInvalid() {
IllegalArgumentException ex =
expectThrows(IllegalArgumentException.class, () -> AccountId.parse("12x"));
assertEquals(ex.getMessage(), "account id must be numeric: 12x");
}
static final class AccountId {
static AccountId parse(String raw) {
if (raw.isBlank()) {
throw new IllegalArgumentException("account id must not be blank");
}
if (!raw.chars().allMatch(Character::isDigit)) {
throw new IllegalArgumentException("account id must be numeric: " + raw);
}
return new AccountId();
}
}
}go deeper
Recall that both methods take an exception class and a lambda, and that expectThrows is the one that returns the exception.
Explain subtype matching, the cause attached on a mismatch, and why the custom message comes first in these two methods but last in assertEquals.
Argue for lambda-scoped exception checks over a method-wide expected exception, and handle exception checks inside a test that otherwise uses SoftAssert.
Decide whether a team standard should prefer expectThrows for every exception test, so messages and causes are specified rather than left to the type alone.
## What the two methods do `org.testng.Assert` offers two methods for checking that code throws. Both take the **expected exception class** and a **`ThrowingRunnable`**, a functional interface whose single method is `void run() throws Throwable`. Because `run()` declares `Throwable`, a lambda passed to either method may call code that throws checked exceptions without wrapping them. Each method runs the lambda once and then decides: 1. If the lambda throws an object that is an instance of the expected class, the check passes. 2. If it throws something else, the check fails with an `AssertionError` that describes the mismatch. 3. If it throws nothing, the check fails with an `AssertionError` saying nothing was thrown. ## The real difference: the return value | Method | Returns | Use it when | |---|---|---| | `assertThrows(ThrowingRunnable)` | `void` | Any exception at all is acceptable (the class defaults to `Throwable`) | | `assertThrows(Class<T>, ThrowingRunnable)` | `void` | Only the type matters | | `expectThrows(Class<T>, ThrowingRunnable)` | `T`, the caught exception | You also need to check its message, cause or a field | In TestNG's source, `assertThrows` simply delegates to `expectThrows` and discards the result, so the two are the same check with different return types. Pick `expectThrows` whenever the exception's content is part of what you are specifying. ## How a type is matched - Matching uses `isInstance`, so **subclasses satisfy the check**: expecting `RuntimeException.class` passes for an `IllegalArgumentException`. If the exact type matters, capture the exception with `expectThrows` and assert on `ex.getClass()` yourself. - On a **mismatch**, the default message reads `Expected IllegalArgumentException to be thrown, but NullPointerException was thrown`, and the exception that was actually thrown is attached as the `AssertionError`'s **cause**, so its stack trace still reaches the report. - When **nothing** is thrown, the default message reads `Expected IllegalArgumentException to be thrown, but nothing was thrown`. ## Checking the message and the cause ```java IllegalArgumentException ex = expectThrows(IllegalArgumentException.class, () -> AccountId.parse("12x")); assertEquals(ex.getMessage(), "account id must be numeric: 12x"); assertNull(ex.getCause()); ``` Note the follow-up checks use TestNG's usual order, actual first: `ex.getMessage()` is the value under test. ## Where the custom message goes TestNG 7.7.0 added overloads that take a custom failure message, and in 7.12 they are: - `assertThrows(String message, Class<T> throwableClass, ThrowingRunnable runnable)` - `expectThrows(String message, Class<T> throwableClass, ThrowingRunnable runnable)` The message is the **first** parameter here, the opposite of `assertEquals`, `assertTrue` and the other checks, where it comes last. When given, it replaces the default mismatch or nothing-thrown text, but the actual exception is still attached as the cause on a mismatch. ## Why the scope of the lambda matters The lambda draws a tight boundary around the one call that should throw. Setup lines, fixture creation and other calls in the test method sit outside it, so an exception thrown there is not mistaken for the behaviour under test; it simply fails the test with that exception. That is the main argument for these methods over a method-wide declaration of an expected exception on the `@Test` annotation, which is satisfied by a matching exception from any line in the method. ## Mistakes that weaken the check - **Putting setup inside the lambda.** `() -> { var svc = newService(); svc.parse("12x"); }` reintroduces the problem the lambda was meant to solve: an exception from `newService()` would satisfy the check. Build fixtures before the call and keep the lambda to the single statement under test. - **Expecting too broad a class.** `assertThrows(Exception.class, ...)` or the one-argument form passes for almost any failure, including a `NullPointerException` from a bug. Name the most specific type the contract promises. - **Stopping at the type.** Two code paths can throw the same exception class for different reasons; checking the message or a field through `expectThrows` is what tells them apart. - **Asserting inside the lambda.** A hard `Assert` call inside the lambda that fails throws an `AssertionError`, which `expectThrows` treats like any other thrown object, so the outcome depends on the expected class rather than on your intent. ## Not available on SoftAssert `org.testng.asserts.SoftAssert` has neither `assertThrows` nor `expectThrows`. An exception check in a test that otherwise uses soft asserts stays on the static `Assert` class and fails the method immediately. When the exception's details are one of several independent checks, keep the `expectThrows` call hard and record the details softly, for example `softly.assertEquals(ex.getMessage(), ...)`.
- What does the failure look like when the lambda throws a different exception type than expected?An AssertionError whose default message reads 'Expected IllegalArgumentException to be thrown, but NullPointerException was thrown', with the thrown exception attached as its cause, so the real stack trace still appears in the report. A custom message replaces that default text, but the cause is attached either way.
- Can you make an exception check soft by calling it on a SoftAssert?No. SoftAssert has no assertThrows or expectThrows, so exception checks stay on the static Assert class and fail the method at once. If the exception's details are one of several independent checks, keep expectThrows hard and record the details on the SoftAssert, such as softly.assertEquals(ex.getMessage(), ...).
- assertThrows returns the caught exception, so you can inspect its message.
- expectThrows only passes for the exact class, never for a subclass.
- The custom message goes last in assertThrows, the same as in assertEquals.
- A wrong exception type is reported without the actual exception attached.
- SoftAssert has a soft assertThrows that defers the failure to assertAll().
Assumes TestNG 7.12; the custom-message overloads of assertThrows and expectThrows, with the message as the first parameter, arrived in 7.7.0.