About Rafal Borowiec

Rafal is an IT specialist with about 8 years of commercial experience, specializing in software testing and quality assurance, software development, project management and team leadership.

3 ways of handling exceptions in JUnit. Which one to choose?

In JUnit there are 3 popular ways of handling exceptions in your test code:

  • try-catch idiom
  • With JUnit rule
  • With annotation

Which one should we use and when?

try-catch idiom

This idiom is one of the most popular one, because it was used already in JUnit 3.

    public void throwsExceptionWhenNegativeNumbersAreGiven() {
        try {
            fail("Should throw an exception if one or more of given numbers are negative");
        } catch (Exception e) {
                    .hasMessage("negatives not allowed: [-1, -2]");

The above approach is a common pattern. The test will fail when no exception is thrown and the exception itself is verified in a catch clause (in the above example I used the FEST Fluent Assertions) and although it is perfectly fine I prefer the approach with
ExpectedException rule.

With JUnit rule

The same example can be created using
ExceptedException rule. The rule must be a public field marked with @Rule annotation. Please note that the “thrown” rule may be reused in many tests.

    public ExpectedException thrown = ExpectedException.none();

    public void throwsExceptionWhenNegativeNumbersAreGiven() {
        // arrange
        thrown.expectMessage(equalTo("negatives not allowed: [-1, -2]"));
        // act

In general, I find the above code more readable hence I use this approach in my projects.

When the exception isn’t thrown you will get the following message: java.lang.AssertionError: Expected test to throw (an instance of java.lang.IllegalArgumentException and exception with message “negatives not allowed: [-1, -2]”). Pretty nice.

But not all exceptions I check with the above approach. Sometimes I need to check only the type of the exception thrown and then I use @Test annotation.

With annotation

@Test (expected = IllegalArgumentException.class)
    public void throwsExceptionWhenNegativeNumbersAreGiven() {
        // act

When the exception wasn’t thrown you will get the following message: java.lang.AssertionError: Expected exception: java.lang.IllegalArgumentException

With this approach you need to be careful though. Sometimes it is tempting to expect general Exception, RuntimeException or even a Throwable. And this is considered as a bad practice, because your code may throw exception in other place than you actually expected and your test will still pass!

To sum up, in my code I use two approaches: with JUnit rule and with annotation. The advantages are:

  • Error messages when the code does not throw an exception are automagically handled
  • The readability is improved
  • There is less code to be created

And what is your preference?

Edit – the 4th way

I have heard of the 4th way of handling the exception (one of my colleagues suggested it after reading this post) – use custom annotation.

Actually the solution seems nice at first glance, but it requires your own JUnit runner hence it has disadvantage: you cannot use this annotation with e.g. Mockito runner.

As a coding practice I have created such an annotation, so maybe someone finds it useful

The usage

public class StringCalculatorTest {
    @ExpectsException(type = IllegalArgumentException.class, message = "negatives not allowed: [-1]")
    public void throwsExceptionWhenNegativeNumbersAreGiven() throws Exception {
        // act


The above test will fail with a message: java.lang.Exception: Unexpected exception message, expected

but was

An annotation

public @interface ExpectsException {
    Class type();

    String message() default "";

A runner with some copy & paste code

public class ExpectsExceptionRunner extends BlockJUnit4ClassRunner {
    public ExpectsExceptionRunner(Class klass) throws InitializationError {

    protected Statement possiblyExpectingExceptions(FrameworkMethod method, Object test, Statement next) {
        ExpectsException annotation = method.getAnnotation(ExpectsException.class);
        if (annotation == null) {
            return next;
        return new ExpectExceptionWithMessage(next, annotation.type(), annotation.message());

    class ExpectExceptionWithMessage extends Statement {

        private final Statement next;
        private final Class expected;
        private final String expectedMessage;

        public ExpectExceptionWithMessage(Statement next, Class expected, String expectedMessage) {
            this.next = next;
            this.expected = expected;
            this.expectedMessage = expectedMessage;

        public void evaluate() throws Exception {
            boolean complete = false;
            try {
                complete = true;
            } catch (AssumptionViolatedException e) {
                throw e;
            } catch (Throwable e) {
                if (!expected.isAssignableFrom(e.getClass())) {
                    String message = "Unexpected exception, expected<"
                            + expected.getName() + "> but was <"
                            + e.getClass().getName() + ">";
                    throw new Exception(message, e);

                if (isNotNull(expectedMessage) && !expectedMessage.equals(e.getMessage())) {
                    String message = "Unexpected exception message, expected<"
                            + expectedMessage + "> but was<"
                            + e.getMessage() + ">";
                    throw new Exception(message, e);
            if (complete) {
                throw new AssertionError("Expected exception: "
                        + expected.getName());

        private boolean isNotNull(String s) {
            return s != null && !s.isEmpty();



Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

2 Responses to "3 ways of handling exceptions in JUnit. Which one to choose?"

  1. Blazej L. says:

    I would recommend you the 5th way – the catch-exception library. It’s biggest advantage is that it allows you to catch exception only on a concrete method invocation. So, if you want to assert that NullPointerException is being thrown on a tested method, and not on the one of “arange” methods, catch-exception is the only way to do that. You can read more on that on the project’s page: https://code.google.com/p/catch-exception/

  2. IBYoung says:

    With annotation way

Leave a Reply

+ seven = 14

Java Code Geeks and all content copyright © 2010-2015, Exelixis Media Ltd | Terms of Use | Privacy Policy | Contact
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

Get ready to Rock!
To download the books, please verify your email address by following the instructions found on the email we just sent you.