JUnit: Possible to 'expect' a wrapped exception?

Question

I know that one can define an 'expected' exception in JUnit, doing:

@Test(expect=MyException.class)
public void someMethod() { ... }

But what if there is always same exception thrown, but with different 'nested' causes.

Any suggestions?

Moser

unimportant side-note: it is "expected=...", not "expect=..." – Lifeboat

I can't believe JUnit 5 apparently hasn't augmented its annotation syntax to include this. – Glister

Answer 1

You could wrap the testing code in a try / catch block, catch the thrown exception, check the internal cause, log / assert / whatever, and then rethrow the exception (if desired).

Disjoined

This answer is now outdated. Use @Rowan's answer – Wiburg

Answer 2

As of JUnit 4.11 you can use the ExpectedException rule's expectCause() method:

import static org.hamcrest.CoreMatchers.*;

// ...

@Rule
public ExpectedException expectedException = ExpectedException.none();

@Test
public void throwsNestedException() throws Exception {
    expectedException.expectCause(isA(SomeNestedException.class));

    throw new ParentException("foo", new SomeNestedException("bar"));
}

Bolshevik

because of the hamcrest generics hell, line 6 has to look like this: expectedException.expectCause(is(IsInstanceOf.<Throwable>instanceOf(SomeNestedException.class))); but other than that, it's an elegant solution. – Antidisestablishmentarianism

@thrau's solution works for me without the additional is: expectedException.expectCause(IsInstanceOf.<Throwable>instanceOf(SomeNestedE‌​xception.class)); – Leopard

@Leopard Yes, that's right - is() is just syntactic sugar that passes through to the nested matcher. See the docs here: hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/core/… – Bolshevik

Same docs tell there's a matcher isA as a shorthand for is(instanceOf(clazz)), so this would suffice: expectedException.expectCause(isA(SomeNestedException.class)); – Aldo

The method should be called org.hamcrest.CoreMatchers.isA. Not in Matchers class. – Mallon

For me this is passing, regardless of what i put in the isA() method. – Pneumatophore

Is there a way to traverse down the CausedBy stack? Or test the expectCause message? – Hindenburg

This is nowadays replaced by Assert.assertThrows. – Paganism

Answer 3

If you're using the latest version of JUnit you can extend the default test runner to handle this for you (without having to wrap each of your methods in a try/catch block)

ExtendedTestRunner.java - New test runner:

public class ExtendedTestRunner extends BlockJUnit4ClassRunner
{
    public ExtendedTestRunner( Class<?> clazz )
        throws InitializationError
    {
        super( clazz );
    }

    @Override
    protected Statement possiblyExpectingExceptions( FrameworkMethod method,
                                                     Object test,
                                                     Statement next )
    {
        ExtendedTest annotation = method.getAnnotation( ExtendedTest.class );
        return expectsCauseException( annotation ) ?
                new ExpectCauseException( next, getExpectedCauseException( annotation ) ) :
                super.possiblyExpectingExceptions( method, test, next );
    }

    @Override
    protected List<FrameworkMethod> computeTestMethods()
    {
        Set<FrameworkMethod> testMethods = new HashSet<FrameworkMethod>( super.computeTestMethods() );
        testMethods.addAll( getTestClass().getAnnotatedMethods( ExtendedTest.class ) );
        return testMethods;
    }

    @Override
    protected void validateTestMethods( List<Throwable> errors )
    {
        super.validateTestMethods( errors );
        validatePublicVoidNoArgMethods( ExtendedTest.class, false, errors );
    }

    private Class<? extends Throwable> getExpectedCauseException( ExtendedTest annotation )
    {
        if (annotation == null || annotation.expectedCause() == ExtendedTest.None.class)
            return null;
        else
            return annotation.expectedCause();
    }

    private boolean expectsCauseException( ExtendedTest annotation) {
        return getExpectedCauseException(annotation) != null;
    }

}

ExtendedTest.java - annotation to mark test methods with:

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface ExtendedTest
{

    /**
     * Default empty exception
     */
    static class None extends Throwable {
        private static final long serialVersionUID= 1L;
        private None() {
        }
    }

    Class<? extends Throwable> expectedCause() default None.class;
}

ExpectCauseException.java - new JUnit Statement:

public class ExpectCauseException extends Statement
{
    private Statement fNext;
    private final Class<? extends Throwable> fExpected;

    public ExpectCauseException( Statement next, Class<? extends Throwable> expected )
    {
        fNext= next;
        fExpected= expected;
    }

    @Override
    public void evaluate() throws Exception
    {
        boolean complete = false;
        try {
            fNext.evaluate();
            complete = true;
        } catch (Throwable e) {
            if ( e.getCause() == null || !fExpected.isAssignableFrom( e.getCause().getClass() ) )
            {
                String message = "Unexpected exception cause, expected<"
                            + fExpected.getName() + "> but was<"
                            + ( e.getCause() == null ? "none" : e.getCause().getClass().getName() ) + ">";
                throw new Exception(message, e);
            }
        }
        if (complete)
            throw new AssertionError( "Expected exception cause: "
                    + fExpected.getName());
    }
}

Usage:

@RunWith( ExtendedTestRunner.class )
public class MyTests
{
    @ExtendedTest( expectedCause = MyException.class )
    public void someMethod()
    {
        throw new RuntimeException( new MyException() );
    }
}

Towboat

I love this solution! However, sadly I'm having trouble getting it to compile in conjunction with Groovy JUnit 4 testing. – Paedogenesis

That's the cleanest solution. Couple of edits though: ExtendedTestRunner needs to extend SpringJUnit4ClassRunner to properly support Spring context. Also computeTestMethods has incompatible return type (should be ArrayList). – Poler

Answer 4

You could always do it manually:

@Test
public void someMethod() {
    try{
        ... all your code
    } catch (Exception e){
        // check your nested clauses
        if(e.getCause() instanceof FooException){
            // pass
        } else {
            Assert.fail("unexpected exception");
        }
    }

Gillan

Answer 5

You could create a Matcher for exceptions. This works even when you are using another test runner like Arquillian's @RunWith(Arquillian.class) so you can't use the @RunWith(ExtendedTestRunner.class) approach suggested above.

Here's a simple example:

public class ExceptionMatcher extends BaseMatcher<Object> {
    private Class<? extends Throwable>[] classes;

    // @SafeVarargs // <-- Suppress warning in Java 7. This usage is safe.
    public ExceptionMatcher(Class<? extends Throwable>... classes) {
        this.classes = classes;
    }

    @Override
    public boolean matches(Object item) {
        for (Class<? extends Throwable> klass : classes) {
            if (! klass.isInstance(item)) {
                return false;
            }   

            item = ((Throwable) item).getCause();
        }   

        return true;
    }   

    @Override
    public void describeTo(Description descr) {
        descr.appendText("unexpected exception");
    }
}

Then use it with @Rule and ExpectedException like this:

@Rule
public ExpectedException thrown = ExpectedException.none();

@Test
public void testSomething() {
    thrown.expect(new ExceptionMatcher(IllegalArgumentException.class, IllegalStateException.class));

    throw new IllegalArgumentException("foo", new IllegalStateException("bar"));
}

Added by Craig Ringer in 2012 edit: An enhanced and more reliable version:

• Basic usage unchanged from above
• Can pass optional 1st argument boolean rethrow to throw unmatched exception. That preserves the stack trace of the nested exceptions for easier debugging.
• Uses Apache Commons Lang ExceptionUtils to handle cause loops and to handle non-standard exception nesting used by some common exception classes.
• Self-describe includes accepted exceptions
• Self-describe on failure includes a the cause stack of the exception encountered
• Handle Java 7 warning. Remove the @SaveVarargs on older versions.

Full code:

import org.apache.commons.lang3.exception.ExceptionUtils;
import org.hamcrest.BaseMatcher;
import org.hamcrest.Description;


public class ExceptionMatcher extends BaseMatcher<Object> {
    private Class<? extends Throwable>[] acceptedClasses;

    private Throwable[] nestedExceptions;
    private final boolean rethrow;

    @SafeVarargs
    public ExceptionMatcher(Class<? extends Throwable>... classes) {
        this(false, classes);
    }

    @SafeVarargs
    public ExceptionMatcher(boolean rethrow, Class<? extends Throwable>... classes) {
        this.rethrow = rethrow;
        this.acceptedClasses = classes;
    }

    @Override
    public boolean matches(Object item) {
        nestedExceptions = ExceptionUtils.getThrowables((Throwable)item);
        for (Class<? extends Throwable> acceptedClass : acceptedClasses) {
            for (Throwable nestedException : nestedExceptions) {
                if (acceptedClass.isInstance(nestedException)) {
                    return true;
                }
            }
        }
        if (rethrow) {
            throw new AssertionError(buildDescription(), (Throwable)item);
        }
        return false;
    }

    private String buildDescription() {
        StringBuilder sb = new StringBuilder();
        sb.append("Unexpected exception. Acceptable (possibly nested) exceptions are:");
        for (Class<? extends Throwable> klass : acceptedClasses) {
            sb.append("\n  ");
            sb.append(klass.toString());
        }
        if (nestedExceptions != null) {
            sb.append("\nNested exceptions found were:");
            for (Throwable nestedException : nestedExceptions) {
                sb.append("\n  ");
                sb.append(nestedException.getClass().toString());
            }
        }
        return sb.toString();
    }

    @Override
    public void describeTo(Description description) {
        description.appendText(buildDescription());
    }

}

Typical output:

java.lang.AssertionError:  Expected: Unexpected exception. Acceptable (possibly nested) exceptions are:
   class some.application.Exception
Nested exceptions found were:
   class javax.ejb.EJBTransactionRolledbackException
   class javax.persistence.NoResultException
     got: <javax.ejb.EJBTransactionRolledbackException: getSingleResult() did not retrieve any entities.>

Apostolate

Excellent and very helpful answer - thanks. This approach is a lifesaver when working with Arquillian to test EJBs, since they like to wrap every unchecked exception in an EJBException. – Nicks

I've extended the example in the answer into something more complete. – Nicks

Answer 6

I wrote a little JUnit extension for that purpose. A static helper function takes a function body and an array of expected exceptions:

import static org.junit.Assert.assertTrue;
import static org.junit.Assert.fail;

import java.util.Arrays;

public class AssertExt {
    public static interface Runnable {
        void run() throws Exception;
    }

    public static void assertExpectedExceptionCause( Runnable runnable, @SuppressWarnings("unchecked") Class[] expectedExceptions ) {
        boolean thrown = false;
        try {
            runnable.run();
        } catch( Throwable throwable ) {
            final Throwable cause = throwable.getCause();
            if( null != cause ) {
                assertTrue( Arrays.asList( expectedExceptions ).contains( cause.getClass() ) );
                thrown = true;
            }
        }
        if( !thrown ) {
            fail( "Expected exception not thrown or thrown exception had no cause!" );
        }
    }
}

You can now check for expected nested exceptions like so:

import static AssertExt.assertExpectedExceptionCause;

import org.junit.Test;

public class TestExample {
    @Test
    public void testExpectedExceptionCauses() {
        assertExpectedExceptionCause( new AssertExt.Runnable(){
            public void run() throws Exception {
                throw new Exception( new NullPointerException() );
            }
        }, new Class[]{ NullPointerException.class } );
    }
}

This saves you writing the same boiler plate code again and again.

Valerivaleria

That would be nice, if java had closures! As is, try/catch/getCause() is probably less boiler plate code than crafting anonymous classes! – Paedogenesis

Answer 7

In JUnit5 you can use assertThrows method which apart of asserting the thrown exception it also returns it so that you can perform additional assertions on it.

@Test
void test() {
    // Assert that parent exception is thrown and retrieve it
    ParentException parentException = assertThrows(ParentException.class, () -> methodThatThrowsException());
    // Perform assertions on the cause
    Throwable cause = parentException.getCause();
    assertThat(cause, ...);
}

void methodThatThrowsException() {
    throw new ParentException("foo", new SomeNestedException("bar"));
}

Castellany

Answer 8

The most concise syntax is provided by catch-exception:

import static com.googlecode.catchexception.CatchException.*;

catchException(myObj).doSomethingNasty();
assertTrue(caughtException().getCause() instanceof MyException);

Rosaceous

Answer 9

We have asserThatThownBy in assertj for all these type of assertions.

assertThatThrownBy(() -> blah()) .isInstanceOf(BlahException.class) .hasCauseExactlyInstanceOf(BlahNestedException.class) .hasRootCauseMessage("some message");

Tiepolo

Not clear why this was down voted but it would be good to have some explanation in the comments before down voting an answer. – Tiepolo