Package org.junit.rules

Class ExpectedException

  • All Implemented Interfaces:
    TestRule
    public class ExpectedException
extends java.lang.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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Statement apply​(Statement base, Description description)
      Modifies the method-running Statement to implement this test-running rule.
      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<? extends java.lang.Throwable> expectedCause)
      Adds matcher to the list of requirements for the cause of 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
      void expectMessage​(org.hamcrest.Matcher<java.lang.String> matcher)
      Adds matcher to the list of requirements for the message returned from any thrown exception.
      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)

      • 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​(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<? extends java.lang.Throwable> expectedCause)
        Adds matcher to the list of requirements for the cause of any thrown exception.