org.junit.rules
Class ExpectedException

java.lang.Object
  org.junit.rules.ExpectedException

All Implemented Interfaces:

TestRule

public class ExpectedException
extends Object
implements TestRule

The ExpectedException rule allows in-test specification of expected exception types and messages:

 // These tests all pass.
 public static class HasExpectedException {
        @Rule
        public ExpectedException thrown= ExpectedException.none();

        @Test
        public void throwsNothing() {
                // no exception expected, none thrown: passes.
     }

        @Test
        public void throwsNullPointerException() {
                thrown.expect(NullPointerException.class);
                throw new NullPointerException();
     }

        @Test
        public void throwsNullPointerExceptionWithMessage() {
                thrown.expect(NullPointerException.class);
                thrown.expectMessage("happened?");
                thrown.expectMessage(startsWith("What"));
                throw new NullPointerException("What happened?");
     }

        @Test
        public void throwsIllegalArgumentExceptionWithMessageAndCause() {
                NullPointerException expectedCause = new NullPointerException();
                thrown.expect(IllegalArgumentException.class);
                thrown.expectMessage("What");
                thrown.expectCause(is(expectedCause));
                throw new IllegalArgumentException("What happened?", cause);
     }
 }
 

By default ExpectedException rule doesn't handle AssertionErrors and AssumptionViolatedExceptions, because such exceptions are used by JUnit. If you want to handle such exceptions you have to call @link handleAssertionErrors() or @link handleAssumptionViolatedExceptions().

 // These tests all pass.
 public static class HasExpectedException {
        @Rule
        public ExpectedException thrown= ExpectedException.none();

        @Test
        public void throwExpectedAssertionError() {
                thrown.handleAssertionErrors();
                thrown.expect(AssertionError.class);
                throw new AssertionError();
     }

  @Test
  public void throwExpectAssumptionViolatedException() {
      thrown.handleAssumptionViolatedExceptions();
      thrown.expect(AssumptionViolatedException.class);
      throw new AssumptionViolatedException("");
     }
 }
 

Since:

4.7

Method Summary

Statement	apply(Statement base, Description description) Modifies the method-running Statement to implement this test-running rule.
void	expect(Class<? extends Throwable> type) Adds to the list of requirements for any thrown exception that it should be an instance of type
void	expect(Matcher<?> matcher) Adds matcher to the list of requirements for any thrown exception.
void	expectCause(Matcher<? extends Throwable> expectedCause) Adds matcher to the list of requirements for the cause of any thrown exception.
void	expectMessage(Matcher<String> matcher) Adds matcher to the list of requirements for the message returned from any thrown exception.
void	expectMessage(String substring) Adds to the list of requirements for any thrown exception that it should contain string substring
ExpectedException	handleAssertionErrors()
ExpectedException	handleAssumptionViolatedExceptions()
static ExpectedException	none()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

none

public static ExpectedException none()

Returns:

a Rule that expects no exception to be thrown (identical to behavior without this Rule)

handleAssertionErrors

public ExpectedException handleAssertionErrors()

handleAssumptionViolatedExceptions

public ExpectedException handleAssumptionViolatedExceptions()

apply

public Statement apply(Statement base,
                       Description description)

Description copied from interface: TestRule

Modifies the method-running Statement to implement this test-running rule.

Specified by:

apply in interface TestRule

Parameters:

base - The Statement to be modified

description - A Description of the test implemented in base

Returns:

a new statement, which may be the same as base, a wrapper around base, or a completely new Statement.

expect

public void expect(Matcher<?> matcher)

Adds matcher to the list of requirements for any thrown exception.

expect

public void expect(Class<? extends Throwable> type)

Adds to the list of requirements for any thrown exception that it should be an instance of type

expectMessage

public void expectMessage(String substring)

Adds to the list of requirements for any thrown exception that it should contain string substring

expectMessage

public void expectMessage(Matcher<String> matcher)

Adds matcher to the list of requirements for the message returned from any thrown exception.

expectCause

public void expectCause(Matcher<? extends Throwable> expectedCause)

Adds matcher to the list of requirements for the cause of any thrown exception.