org.hamcrest.junit

Class ExpectedException

java.lang.Object

org.hamcrest.junit.ExpectedException

All Implemented Interfaces:

org.junit.rules.TestRule

public class ExpectedException
extends java.lang.Object
implements org.junit.rules.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

Methods

Modifier and Type	Method and Description
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)
void	expect(java.lang.Class<? extends java.lang.Throwable> type) Adds to the list of requirements for any thrown exception that it should be an instance of type
void	expect(org.hamcrest.Matcher<?> matcher) Adds matcher to the list of requirements for any thrown exception.
void	expectCause(org.hamcrest.Matcher<? super java.lang.Throwable> expectedCause) Adds matcher to the list of requirements for the cause of any thrown exception.
void	expectMessage(org.hamcrest.Matcher<java.lang.String> matcher) Adds matcher to the list of requirements for the message returned from any thrown exception.
void	expectMessage(java.lang.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 org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base,
                                      org.junit.runner.Description description)

Specified by:

apply in interface org.junit.rules.TestRule

expect

public void expect(org.hamcrest.Matcher<?> matcher)

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

expect

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

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

expectMessage

public void expectMessage(java.lang.String substring)

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

expectMessage

public void expectMessage(org.hamcrest.Matcher<java.lang.String> matcher)

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

expectCause

public void expectCause(org.hamcrest.Matcher<? super java.lang.Throwable> expectedCause)

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