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.

JUnit ExpectedException rule: beyond basics

There are different ways of handling exceptions in JUnit tests. As I wrote in one of my previous posts, my preferable way is using org.junit.rules.ExpectedException rule. Basically, rules are used as an alternative (or an addition) to methods annotated with org.junit.Before, org.junit.After, org.junit.BeforeClass, or org.junit.AfterClass, but they are more powerful, and more easily shared between projects and classes. In this post I will show more advanced usage of org.junit.rules.ExpectedException rule.

Verify the exception message

Standard JUnit’s org.junit.Test annotation offers expected attribute that allows you specifying the a Throwable to cause a test method to succeed if an exception of the specified class is thrown by the method. In many cases this seems enough, but if you want to verify an exception message – you must find other way. With ExpectedException is pretty straightforward:

public class ExpectedExceptionsTest {
 
    @Rule
    public ExpectedException thrown = ExpectedException.none();
     
    @Test
    public void verifiesTypeAndMessage() {
 
        thrown.expect(RuntimeException.class);
        thrown.expectMessage("Runtime exception occurred");
         
        throw new RuntimeException("Runtime exception occurred");
    }
}

In the above snippet, we expect that a message contains a given substring. Comparing to type check only, it is much safer. Why? Let’s assume that we have an ExceptionThrower that looks like follows:

class ExceptionsThrower {
    void throwRuntimeException(int i) {
        if (i <= 0) {
            throw new RuntimeException("Illegal argument: i must be <= 0");
        }
        throw new RuntimeException("Runtime exception occurred");
    }
}

As you can see both exceptions thrown by a method are RuntimeExceptions, so in case we do not check the message, we are not 100% sure which exception will be thrown by a method. The following tests will pass:

@Test
public void runtimeExceptionOccurs() {
    thrown.expect(RuntimeException.class);
    // opposite to expected
    exceptionsThrower.throwRuntimeException(0);
}
 
@Test
public void illegalArgumentExceptionOccurs() {
    thrown.expect(RuntimeException.class);
    // opposite to expected
    exceptionsThrower.throwRuntimeException(1);
}

Checking for the message in an exception will solve the problem and make sure you are verifying a wanted exception. This is already an advantage over expected attribute of @Test annotated methods.

But what if, you need to verify an exception message in a more sophisticated way? ExpectedException allows you that by providing a Hamcrest matcher to expectMessage method (instead of a String). Let's look at the example below:

@Test
public void verifiesMessageStartsWith() {
    thrown.expect(RuntimeException.class);
    thrown.expectMessage(startsWith("Illegal argument:"));
 
    throw new RuntimeException("Illegal argument: i must be <= 0");
}

As you can expect, you can provide your own matchers, to verify the message. Let's look at the example.

@Test
public void verifiesMessageMatchesPattern() {
    thrown.expect(RuntimeException.class);
    thrown.expectMessage(new MatchesPattern("[Ii]llegal .*"));
 
    throw new RuntimeException("Illegal argument: i must be <= 0");
}
 
class MatchesPattern extends TypeSafeMatcher<String> {
    private String pattern;
 
    public MatchesPattern(String pattern) {
        this.pattern = pattern;
    }
 
    @Override
    protected boolean matchesSafely(String item) {
        return item.matches(pattern);
    }
 
    @Override
    public void describeTo(Description description) {
        description.appendText("matches pattern ")
            .appendValue(pattern);
    }
 
    @Override
    protected void describeMismatchSafely(String item, Description mismatchDescription) {
        mismatchDescription.appendText("does not match");
    }
}

Verify the exception object

Matching messages may not be enough in certain scenarios. You may have an exception with custom methods and you want to verify them too. No problem at all. ExpectedException allows that with expect method that takes matcher.

@Test
public void verifiesCustomException() {
    thrown.expect(RuntimeException.class);
    thrown.expect(new ExceptionCodeMatches(1));
 
    throw new CustomException(1);
}
 
class CustomException extends RuntimeException {
    private final int code;
 
    public CustomException(int code) {
        this.code = code;
    }
 
    public int getCode() {
        return code;
    }
}
 
class ExceptionCodeMatches extends TypeSafeMatcher<CustomException> {
    private int code;
 
    public ExceptionCodeMatches(int code) {
        this.code = code;
    }
 
    @Override
    protected boolean matchesSafely(CustomException item) {
        return item.getCode() == code;
    }
 
    @Override
    public void describeTo(Description description) {
        description.appendText("expects code ")
                .appendValue(code);
    }
 
    @Override
    protected void describeMismatchSafely(CustomException item, Description mismatchDescription) {
        mismatchDescription.appendText("was ")
                .appendValue(item.getCode());
    }
}

Please note, that I implemented both describeTo and describeMismatchSafely methods of TypeSafeMatcher. I need them to produce nicely looking error messages when the test fails. Have a look at an example below:

java.lang.AssertionError: 
Expected: (an instance of java.lang.RuntimeException and expects code <1>)
     but: expects code <1> was <2>

Checking a cause

One additional thing you can do with ExpectedException is to verify the cause of a thrown exception. This also can be done with custom matchers:

@Test
public void verifiesCauseTypeAndAMessage() {
    thrown.expect(RuntimeException.class);
    thrown.expectCause(new CauseMatcher(IllegalStateException.class, "Illegal state"));
 
    throw new RuntimeException("Runtime exception occurred",
            new IllegalStateException("Illegal state"));
}
 
private static class CauseMatcher extends TypeSafeMatcher<Throwable> {
 
    private final Class<? extends Throwable> type;
    private final String expectedMessage;
 
    public CauseMatcher(Class<? extends Throwable> type, String expectedMessage) {
        this.type = type;
        this.expectedMessage = expectedMessage;
    }
 
    @Override
    protected boolean matchesSafely(Throwable item) {
        return item.getClass().isAssignableFrom(type)
                && item.getMessage().contains(expectedMessage);
    }
 
    @Override
    public void describeTo(Description description) {
        description.appendText("expects type ")
                .appendValue(type)
                .appendText(" and a message ")
                .appendValue(expectedMessage);
    }
}

Summary

ExpectedException rule is a powerful feature. With an addition of Hamcrest matchers you are able to easily create robust and reusable code for you exceptions tests.

 

Reference: JUnit ExpectedException rule: beyond basics from our JCG partner Rafal Borowiec at the Codeleak.pl blog.
Related Whitepaper:

Bulletproof Java Code: A Practical Strategy for Developing Functional, Reliable, and Secure Java Code

Use Java? If you do, you know that Java software can be used to drive application logic of Web services or Web applications. Perhaps you use it for desktop applications? Or, embedded devices? Whatever your use of Java code, functional errors are the enemy!

To combat this enemy, your team might already perform functional testing. Even so, you're taking significant risks if you have not yet implemented a comprehensive team-wide quality management strategy. Such a strategy alleviates reliability, security, and performance problems to ensure that your code is free of functionality errors.Read this article to learn about this simple four-step strategy that is proven to make Java code more reliable, more secure, and easier to maintain.

Get it Now!  

Leave a Reply


six − 5 =



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
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.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books