ExpectedException (JUnit API)
Date: 2018-08-04

org.junit.rules

## Class ExpectedException

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

- All Implemented Interfaces:
    TestRule

      public class ExpectedException
      extends java.lang.Object
      implements TestRule

  The `ExpectedException` rule allows you to verify that your code throws a specific exception.

  ### Usage

       public class SimpleExpectedExceptionTest {
           @Rule
           public ExpectedException thrown= ExpectedException.none();

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

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

  You have to add the `ExpectedException` rule to your test. This doesn't affect your existing tests (see `throwsNothing()`). After specifiying the type of the expected exception your test is successful when such an exception is thrown and it fails if a different or no exception is thrown.

  Instead of specifying the exception's type you can characterize the expected exception based on other criterias, too:

  - The exception's message contains a specific text: `expectMessage(String)`
  - The exception's message complies with a Hamcrest matcher: `expectMessage(Matcher)`
  - The exception's cause complies with a Hamcrest matcher: `expectCause(Matcher)`
  - The exception itself complies with a Hamcrest matcher: `expect(Matcher)`

  You can combine any of the presented expect-methods. The test is successful if all specifications are met.

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

  ### AssumptionViolatedExceptions

  JUnit uses `AssumptionViolatedException`s for indicating that a test provides no useful information. (See `Assume` for more information.) You have to call `assume` methods before you set expectations of the `ExpectedException` rule. In this case the rule will not handle consume the exceptions and it can be handled by the framework. E.g. the following test is ignored by JUnit's default runner.

       @Test
       public void ignoredBecauseOfFailedAssumption() {
           assumeTrue(false); // throws AssumptionViolatedException
           thrown.expect(NullPointerException.class);
       }

  ### AssertionErrors

  JUnit uses `AssertionError`s for indicating that a test is failing. You have to call `assert` methods before you set expectations of the `ExpectedException` rule, if they should be handled by the framework. E.g. the following test fails because of the `assertTrue` statement.

       @Test
       public void throwsUnhandled() {
           assertTrue(false); // throws AssertionError
           thrown.expect(NullPointerException.class);
       }

  ### Missing Exceptions

  By default missing exceptions are reported with an error message like "Expected test to throw an instance of foo". You can configure a different message by means of `reportMissingExceptionWithMessage(String)`. You can use a `%s` placeholder for the description of the expected exception. E.g. "Test doesn't throw %s." will fail with the error message "Test doesn't throw an instance of foo.".

  Since:
    4.7

- - ### Method Summary

    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(java.lang.Class<? extends java.lang.Throwable> type)` Verify that your code throws an exception that is an instance of specific `type`.
    `void` | `expect(org.hamcrest.Matcher<?> matcher)` Verify that your code throws an exception that is matched by a Hamcrest matcher.
    `void` | `expectCause(org.hamcrest.Matcher<? extends java.lang.Throwable> expectedCause)` Verify that your code throws an exception whose cause is matched by a Hamcrest matcher.
    `void` | `expectMessage(org.hamcrest.Matcher<java.lang.String> matcher)` Verify that your code throws an exception whose message is matched by a Hamcrest matcher.
    `void` | `expectMessage(java.lang.String substring)` Verify that your code throws an exception whose message contains a specific text.
    `ExpectedException` | `handleAssertionErrors()` Deprecated. AssertionErrors are handled by default since JUnit 4.12. Just like in JUnit <= 4.10.
    `ExpectedException` | `handleAssumptionViolatedExceptions()` Deprecated. AssumptionViolatedExceptions are handled by default since JUnit 4.12. Just like in JUnit <= 4.10.
    `static ExpectedException` | `none()` Returns a rule that expects no exception to be thrown (identical to behavior without this rule).
    `ExpectedException` | `reportMissingExceptionWithMessage(java.lang.String message)` Specifies the failure message for tests that are expected to throw an exception but do not throw any.

    - ### 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

          @Deprecated
          public ExpectedException handleAssertionErrors()

      Deprecated. AssertionErrors are handled by default since JUnit 4.12. Just like in JUnit <= 4.10.
      This method does nothing. Don't use it.

    - #### handleAssumptionViolatedExceptions

          @Deprecated
          public ExpectedException handleAssumptionViolatedExceptions()

      Deprecated. AssumptionViolatedExceptions are handled by default since JUnit 4.12. Just like in JUnit <= 4.10.
      This method does nothing. Don't use it.

    - #### reportMissingExceptionWithMessage

          public ExpectedException reportMissingExceptionWithMessage(java.lang.String message)

      Specifies the failure message for tests that are expected to throw an exception but do not throw any. You can use a `%s` placeholder for the description of the expected exception. E.g. "Test doesn't throw %s." will fail with the error message "Test doesn't throw an instance of foo.".
      Parameters:
        `message` - exception detail message
      Returns:
        the rule itself

    - #### 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)

      Verify that your code throws an exception that is matched by a Hamcrest matcher.

           @Test
           public void throwsExceptionThatCompliesWithMatcher() {
               NullPointerException e = new NullPointerException();
               thrown.expect(is(e));
               throw e;
           }

    - #### expect

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

      Verify that your code throws an exception that is an instance of specific `type`.

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

    - #### expectMessage

          public void expectMessage(java.lang.String substring)

      Verify that your code throws an exception whose message contains a specific text.

           @Test
           public void throwsExceptionWhoseMessageContainsSpecificText() {
               thrown.expectMessage("happened");
               throw new NullPointerException("What happened?");
           }

    - #### expectMessage

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

      Verify that your code throws an exception whose message is matched by a Hamcrest matcher.

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

    - #### expectCause

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

      Verify that your code throws an exception whose cause is matched by a Hamcrest matcher.

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