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.