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

This rule does not perform any special magic to make execution continue as if the exception had not been thrown. So it is nearly always a mistake for a test method to have statements after the one that is expected to throw the exception.

Instead of specifying the exception's type you can characterize the expected exception based on other criteria, 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?");
     }

It is recommended to set the `order` of the `ExpectedException` to `Integer.MAX_VALUE` if it is used together with another rule that handles exceptions, e.g. `ErrorCollector`. Otherwise failing tests may be successful.

     @Rule(order = Integer.MAX_VALUE)
     public ExpectedException thrown = ExpectedException.none();

### 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
`Statement` `apply(Statement base, Description description)` Modifies the method-running `Statement` to implement this test-running rule.
`void` `expect(Class<? extends Throwable> type)` Verify that your code throws an exception that is an instance of specific `type`.
`void` `expect(Matcher<?> matcher)` Verify that your code throws an exception that is matched by a Hamcrest matcher.
`void` `expectCause(Matcher<?> expectedCause)` Verify that your code throws an exception whose cause is matched by a Hamcrest matcher.
`void` `expectMessage(Matcher<String> matcher)` Verify that your code throws an exception whose message is matched by a Hamcrest matcher.
`void` `expectMessage(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.
`boolean` `isAnyExceptionExpected()` Check if any Exception is expected.
`static ExpectedException` `none()` Deprecated. Since 4.13 `Assert.assertThrows` can be used to verify that your code throws a specific exception.
`ExpectedException` `reportMissingExceptionWithMessage(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

    @Deprecated
    public static ExpectedException none()

  Deprecated. Since 4.13 `Assert.assertThrows` can be used to verify that your code throws a specific exception.

  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(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(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(Class<? extends 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(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(Matcher<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(Matcher<?> 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);
       }

### isAnyExceptionExpected

    public final boolean isAnyExceptionExpected()

  Check if any Exception is expected.

  Since:
    4.13

Copyright © 2002–2020 JUnit. All rights reserved.