Checking exception message in JUnit - Deep Dive

Overview - Checking exception message

What is it?

Checking exception message means verifying that when a piece of code throws an error, the error message is exactly what we expect. This helps ensure the program fails in the right way and gives useful information. In JUnit, a popular Java testing tool, we can write tests that expect exceptions and check their messages. This makes tests more precise and trustworthy.

Why it matters

Without checking exception messages, tests might only know that an error happened but not if it was the correct error or why. This can hide bugs or cause confusion when fixing problems. By verifying the message, developers get clear feedback about what went wrong, making debugging faster and software more reliable.

Where it fits

Before learning this, you should understand basic JUnit tests and how to expect exceptions. After this, you can learn advanced error handling tests, custom exception creation, and integration testing where error messages guide user feedback.

Mental Model

Core Idea

Checking exception messages confirms not just that an error occurred, but that it was the exact error with the right explanation.

Think of it like...

It's like checking not only that a fire alarm went off, but also reading the alarm's message to know if it’s a kitchen fire or a smoke test, so you respond correctly.

┌─────────────────────────────┐
│       Test Method           │
│  ┌───────────────────────┐  │
│  │ Run code that throws   │  │
│  │ an exception           │  │
│  └──────────┬────────────┘  │
│             │               │
│   Exception thrown          │
│             │               │
│  ┌──────────▼────────────┐  │
│  │ Check exception type   │  │
│  │ and message text       │  │
│  └──────────┬────────────┘  │
│             │               │
│  Pass if type and message   │
│  match expected             │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding exceptions in Java

Concept: Learn what exceptions are and how Java uses them to signal errors.

In Java, an exception is an event that disrupts normal program flow. For example, dividing by zero throws an ArithmeticException. Exceptions have types and messages that describe the error. Handling exceptions properly helps programs avoid crashing unexpectedly.

Result

You understand that exceptions are objects carrying error information, including a message.

Knowing exceptions carry messages is key to testing not just that an error happened, but why.

2

Foundation

Basic JUnit exception testing

Concept: Learn how to write JUnit tests that expect exceptions to be thrown.

JUnit allows tests to expect exceptions using assertThrows. For example: @Test void testDivideByZero() { assertThrows(ArithmeticException.class, () -> { int result = 1 / 0; }); } This test passes if ArithmeticException is thrown.

Result

You can write tests that confirm code throws the right type of exception.

Expecting exceptions prevents tests from failing unexpectedly and documents error cases.

3

Intermediate

Checking exception messages with assertThrows

🤔Before reading on: do you think assertThrows alone checks the exception message? Commit to yes or no.

Concept: Learn to capture the thrown exception and check its message text explicitly.

assertThrows returns the exception object, so you can check its message: @Test void testExceptionMessage() { Exception e = assertThrows(IllegalArgumentException.class, () -> { throw new IllegalArgumentException("Invalid input"); }); assertEquals("Invalid input", e.getMessage()); } This verifies both type and message.

Result

Tests confirm the exact error message, making them more precise.

Capturing the exception lets you verify details beyond just the type, improving test quality.

4

Intermediate

Using message matchers for flexible checks

🤔Before reading on: Is it better to check exact messages or allow partial matches? Commit to your answer.

Concept: Sometimes exact messages change; using matchers lets tests check parts or patterns in messages.

JUnit combined with Hamcrest matchers can check if messages contain text: @Test void testMessageContains() { Exception e = assertThrows(IllegalStateException.class, () -> { throw new IllegalStateException("State error: invalid state"); }); assertThat(e.getMessage(), containsString("invalid state")); } This test passes if the message contains the substring.

Result

Tests become more robust to minor message changes while still verifying meaning.

Flexible message checks reduce brittle tests that break on small wording changes.

5

Advanced

Testing nested exception messages

🤔Before reading on: Do you think assertThrows checks nested causes automatically? Commit to yes or no.

Concept: Learn to check messages of exceptions wrapped inside others (causes).

Sometimes exceptions wrap others. To check nested messages: @Test void testNestedExceptionMessage() { Exception e = assertThrows(RuntimeException.class, () -> { throw new RuntimeException("Wrapper", new IllegalArgumentException("Cause message")); }); Throwable cause = e.getCause(); assertNotNull(cause); assertEquals("Cause message", cause.getMessage()); } This verifies inner exception messages.

Result

You can test complex error chains, ensuring full error context is correct.

Understanding nested exceptions helps catch subtle bugs hidden in wrapped errors.

6

Expert

Avoiding brittle tests with message constants

🤔Before reading on: Is hardcoding message strings in tests a good practice? Commit to yes or no.

Concept: Learn why using constants or enums for messages improves test maintainability.

Hardcoding messages in tests causes failures if messages change. Instead: public class ErrorMessages { public static final String INVALID_INPUT = "Invalid input"; } @Test void testMessageConstant() { Exception e = assertThrows(IllegalArgumentException.class, () -> { throw new IllegalArgumentException(ErrorMessages.INVALID_INPUT); }); assertEquals(ErrorMessages.INVALID_INPUT, e.getMessage()); } This keeps tests and code in sync.

Result

Tests become easier to maintain and less fragile to message text changes.

Using shared constants prevents wasted time fixing tests after harmless message edits.

Under the Hood

When assertThrows runs, it executes the code block expecting an exception. If thrown, it catches the exception object and returns it to the test. The test can then call getMessage() on this object to retrieve the error message string. This message is stored inside the exception when it is created, usually passed to the constructor. The test compares this string to the expected value to decide pass or fail.

Why designed this way?

JUnit's assertThrows was designed to improve over older methods that only checked exception types. Returning the exception object allows detailed inspection, like message checking, without extra boilerplate. This design balances simplicity and power, making tests clearer and more expressive.

┌───────────────┐
│ Test Method   │
│ calls assertThrows ──────────────┐
└───────────────┘                 │
                                  ▼
                      ┌─────────────────────┐
                      │ Executes code block  │
                      │  expecting exception │
                      └──────────┬──────────┘
                                 │
                      Exception thrown or test fails
                                 │
                      ┌──────────▼──────────┐
                      │ Catches exception    │
                      │ Returns exception obj│
                      └──────────┬──────────┘
                                 │
                      ┌──────────▼──────────┐
                      │ Test inspects message│
                      │ via getMessage()     │
                      └─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does assertThrows automatically check the exception message? Commit to yes or no.

Common Belief: assertThrows alone verifies both exception type and message automatically.

Reality: assertThrows only checks the exception type; you must manually check the message by capturing the exception object.

Why it matters: Assuming assertThrows checks messages leads to false confidence in tests that miss verifying important error details.

Quick: Should you hardcode exact exception messages in tests? Commit to yes or no.

Common Belief: Hardcoding exact messages in tests is best to ensure precise checks.

Reality: Hardcoding messages makes tests fragile; small wording changes break tests unnecessarily.

Why it matters: Fragile tests increase maintenance cost and slow down development due to frequent test failures on harmless changes.

Quick: Does checking exception messages guarantee your program handles errors correctly? Commit to yes or no.

Common Belief: If the exception message is correct, the program handles errors properly.

Reality: Correct messages do not guarantee correct error handling logic; messages can be right but handling flawed.

Why it matters: Relying only on messages can miss bugs in error recovery or side effects.

Quick: Does assertThrows check nested exception messages automatically? Commit to yes or no.

Common Belief: assertThrows verifies messages of nested (cause) exceptions automatically.

Reality: assertThrows only checks the top-level exception; nested causes must be checked manually.

Why it matters: Ignoring nested exceptions can miss important error context and lead to incomplete tests.

Expert Zone

1

Exception messages can be localized; tests must consider language settings to avoid false failures.

2

Some exceptions generate dynamic messages with variable data; using regex or partial matchers is better than exact strings.

3

Stack traces and suppressed exceptions are not checked by assertThrows but can hold critical debugging info.

When NOT to use

Checking exception messages is not suitable when messages are user-facing and subject to change or localization. Instead, test error codes, exception types, or error handling behavior. For UI tests, verify user notifications rather than raw messages.

Production Patterns

In production, teams often centralize error messages as constants or enums to keep tests and code aligned. Tests use assertThrows combined with message matchers for flexible validation. Nested exception checks are common in layered architectures to ensure full error context is preserved.

Connections

Error Handling

builds-on

Understanding how to check exception messages deepens knowledge of error handling by verifying not just failure but the reason behind it.

Behavior Driven Development (BDD)

builds-on

Checking exception messages aligns with BDD's focus on specifying exact expected behavior, including error details, improving communication between developers and stakeholders.

Medical Diagnostics

analogy in process

Just as doctors diagnose by not only detecting symptoms but interpreting their exact nature, checking exception messages helps developers diagnose software problems precisely.

Common Pitfalls

#1 Assuming assertThrows checks exception messages automatically.

Wrong approach:

@Test
void testError() {
assertThrows(IllegalArgumentException.class, () -> {
throw new IllegalArgumentException("Wrong input");
});
// No message check here
}

Correct approach:

@Test
void testError() {
Exception e = assertThrows(IllegalArgumentException.class, () -> {
throw new IllegalArgumentException("Wrong input");
});
assertEquals("Wrong input", e.getMessage());
}

Root cause:

Misunderstanding that assertThrows only checks type, not message.

#2 Hardcoding exact messages causing brittle tests.

Wrong approach:

assertEquals("Invalid input at line 5", e.getMessage());

Correct approach:

assertThat(e.getMessage(), containsString("Invalid input"));

Root cause:

Not anticipating minor message changes or dynamic content in messages.

#3 Ignoring nested exception messages.

Wrong approach:

Exception e = assertThrows(RuntimeException.class, () -> {
throw new RuntimeException("Wrapper", new IllegalArgumentException("Cause message"));
});
assertEquals("Wrapper", e.getMessage());

Correct approach:

Exception e = assertThrows(RuntimeException.class, () -> {
throw new RuntimeException("Wrapper", new IllegalArgumentException("Cause message"));
});
Throwable cause = e.getCause();
assertNotNull(cause);
assertEquals("Cause message", cause.getMessage());

Root cause:

Not realizing nested exceptions hold important error details.

Key Takeaways

Checking exception messages in tests ensures errors are not only caught but understood precisely.

JUnit's assertThrows returns the exception object, enabling detailed message verification.

Using flexible matchers for messages makes tests robust against minor wording changes.

Nested exceptions require manual checks to verify full error context.

Avoid hardcoding messages in tests; use constants or partial matches to reduce maintenance.