Class ExpectedException
- All Implemented Interfaces:
TestRule
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 AssumptionViolatedExceptions 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 AssertionErrors 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
-
Nested Class Summary
Nested Classes -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionapply(Statement base, Description description) Modifies the method-runningStatementto implement this test-running rule.voidVerify that your code throws an exception that is an instance of specifictype.voidexpect(org.hamcrest.Matcher<?> matcher) Verify that your code throws an exception that is matched by a Hamcrest matcher.voidexpectCause(org.hamcrest.Matcher<?> expectedCause) Verify that your code throws an exception whose cause is matched by a Hamcrest matcher.voidexpectMessage(String substring) Verify that your code throws an exception whose message contains a specific text.voidexpectMessage(org.hamcrest.Matcher<String> matcher) Verify that your code throws an exception whose message is matched by a Hamcrest matcher.private voidDeprecated.AssertionErrors are handled by default since JUnit 4.12.Deprecated.AssumptionViolatedExceptions are handled by default since JUnit 4.12.private voidfinal booleanCheck if any Exception is expected.private Stringstatic ExpectedExceptionnone()Deprecated.Since 4.13Assert.assertThrowscan be used to verify that your code throws a specific exception.reportMissingExceptionWithMessage(String message) Specifies the failure message for tests that are expected to throw an exception but do not throw any.
-
Field Details
-
matcherBuilder
-
missingExceptionMessage
-
-
Constructor Details
-
ExpectedException
private ExpectedException()
-
-
Method Details
-
none
Deprecated.Since 4.13Assert.assertThrowscan 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.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.AssumptionViolatedExceptions are handled by default since JUnit 4.12. Just like in JUnit <= 4.10.This method does nothing. Don't use it. -
reportMissingExceptionWithMessage
Specifies the failure message for tests that are expected to throw an exception but do not throw any. You can use a%splaceholder 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
Description copied from interface:TestRuleModifies the method-runningStatementto implement this test-running rule.- Specified by:
applyin interfaceTestRule- Parameters:
base- TheStatementto be modifieddescription- ADescriptionof the test implemented inbase- Returns:
- a new statement, which may be the same as
base, a wrapper aroundbase, 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
Verify that your code throws an exception that is an instance of specifictype.@Test public void throwsExceptionWithSpecificType() { thrown.expect(NullPointerException.class); throw new NullPointerException(); } -
expectMessage
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
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<?> 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
-
handleException
- Throws:
Throwable
-
failDueToMissingException
- Throws:
AssertionError
-
missingExceptionMessage
-