ExpectedException (JUnit API)
Date: 2016-08-24

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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.