ExceptionMatchers (Atlassian Unit-Test Toolkit 2.3.0 API)

java.lang.Object
- com.atlassian.utt.matchers.ExceptionMatchers

```
public class ExceptionMatchers
extends Object
```
Convenient assertions related to exceptions and the tests that throw them.

Since:

v2.2.0

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ExceptionMatchers.CatchResult` Holder for the exception thrown by a `ExceptionMatchers.ThrowingRunnable`.
`static interface`	`ExceptionMatchers.ThrowingRunnable` Like `Runnable`, but permits checked exceptions to be thrown.

Constructor Summary

Constructors
Constructor and Description

ExceptionMatchers()

Constructors
Constructor and Description
`ExceptionMatchers()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`assertThrows(Class<? extends Throwable> expected, ExceptionMatchers.ThrowingRunnable runnable)` Convenience method for `assertThrows(String, Class, ThrowingRunnable)` with `null` for the `message`.
`static void`	`assertThrows(org.hamcrest.Matcher<Throwable> matcher, ExceptionMatchers.ThrowingRunnable runnable)` Convenience method for `assertThrows(String, Matcher, ThrowingRunnable)` with `null` for the `message`.
`static void`	`assertThrows(String message, Class<? extends Throwable> expected, ExceptionMatchers.ThrowingRunnable runnable)` Convenience method for `assertThrows(String, Matcher, ThrowingRunnable)` with `instanceOf(expected)` for the `matcher`.
`static void`	`assertThrows(String message, org.hamcrest.Matcher<Throwable> matcher, ExceptionMatchers.ThrowingRunnable runnable)` This is similar to using the `expected` parameter on a `@Test` annotation or the `ExpectedException` `@Rule`, except that it can be used conveniently within the test flow.
`static ExceptionMatchers.CatchResult`	`catching(ExceptionMatchers.ThrowingRunnable runnable)` Runs the `ExceptionMatchers.ThrowingRunnable`, catches any exception that it throws, and returns it wrapped up as a `CatchResult` that can be asserted against with `caught(Matcher)` or `caughtNothing()`.
`static org.hamcrest.Matcher<ExceptionMatchers.CatchResult>`	`caught(Class<? extends Throwable> expected)` A matcher for use with `catching(ThrowingRunnable)` which asserts that it throws an exception of the specified type.
`static org.hamcrest.Matcher<ExceptionMatchers.CatchResult>`	`caught(org.hamcrest.Matcher<Throwable> matcher)` A matcher for use with `catching(ThrowingRunnable)` which asserts that it throws an exception that matches the given condition.
`static org.hamcrest.Matcher<ExceptionMatchers.CatchResult>`	`caughtNothing()` A matcher for use with `catching(ThrowingRunnable)` which asserts that no exception occurred.
`static NamedFeature<Throwable,Throwable>`	`cause()` Extracts an exception's cause for matching against.
`static org.hamcrest.Matcher<Throwable>`	`cause(Class<? extends Throwable> expectedClass)` Convenient shorthand for `cause().that(instanceOf(expectedClass))`.
`static org.hamcrest.Matcher<Throwable>`	`cause(org.hamcrest.Matcher<Throwable> matcher)` Convenient shorthand for `cause().that(matcher)`.
`static NamedFeature<Throwable,String>`	`message()` Extracts an exception's message for matching against.
`static org.hamcrest.Matcher<Throwable>`	`message(org.hamcrest.Matcher<String> matcher)` Convenient shorthand for `message().that(matcher)`.
`static org.hamcrest.Matcher<Throwable>`	`message(String message)` Convenient shorthand for `message().NamedFeature.thatIs(Object) thatIs}(message)`.
`static org.hamcrest.Matcher<Throwable>`	`messageContains(String... orderedSubstrings)` Convenient shorthand for `message().that(orderedSubstrings(orderedSubstrings))`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ExceptionMatchers
```
public ExceptionMatchers()
```
- Method Detail
  - assertThrows
```
public static void assertThrows(Class<? extends Throwable> expected,
                                ExceptionMatchers.ThrowingRunnable runnable)
```
    Convenience method for assertThrows(String, Class, ThrowingRunnable) with null for the message.
    
    Parameters:
    
    expected - as for assertThrows(String, Class, ThrowingRunnable)
    
    runnable - as for assertThrows(String, Matcher, ThrowingRunnable)
  - assertThrows
```
public static void assertThrows(String message,
                                Class<? extends Throwable> expected,
                                ExceptionMatchers.ThrowingRunnable runnable)
```
    Convenience method for assertThrows(String, Matcher, ThrowingRunnable) with instanceOf(expected) for the matcher.
    
    Parameters:
    
    expected - as for assertThrows(String, Class, ThrowingRunnable)
    
    runnable - as for assertThrows(String, Matcher, ThrowingRunnable)
  - assertThrows
```
public static void assertThrows(org.hamcrest.Matcher<Throwable> matcher,
                                ExceptionMatchers.ThrowingRunnable runnable)
```
    Convenience method for assertThrows(String, Matcher, ThrowingRunnable) with null for the message.
    
    Parameters:
    
    matcher - as for assertThrows(String, Matcher, ThrowingRunnable)
    
    runnable - as for assertThrows(String, Matcher, ThrowingRunnable)
  - assertThrows
```
public static void assertThrows(@Nullable
                                String message,
                                @Nonnull
                                org.hamcrest.Matcher<Throwable> matcher,
                                @Nonnull
                                ExceptionMatchers.ThrowingRunnable runnable)
```
    This is similar to using the expected parameter on a @Test annotation or the ExpectedException @Rule, except that it can be used conveniently within the test flow.
    Without assertThrows:
```
     @Test
     public void shouldThrowExceptionForBadInput() {
         WidgetFactory widgetFactory = new WidgetFactory();
         try {
             widgetFactory.lookup("foo");
             fail("Did not expect 'foo' to be a valid widget");
         } catch (IllegalArgumentException e) {
             assertThat(e, message(containsString("foo")));
             assertThat(widgetFactory.stats().lookupCount(), is(1));
         }
     }
 
```
    With assertThrows:
```
     @Test
     public void shouldThrowExceptionForBadInput() {
         WidgetFactory widgetFactory = new WidgetFactory();
         assertThrows(allOf(instanceOf(IllegalArgumentException.class), message(containsString("foo"))),
                 () -> widgetFactory.lookup("foo"));
         assertThat(widgetFactory.stats().lookupCount(), is(1));
     }
 
```
    Parameters:
    
    message - an optional message clarifying why the exception was expected
    
    matcher - a matcher to verify that the exception meets expectations
    
    runnable - the code that is expected to throw an exception
  - message
```
public static NamedFeature<Throwable,String> message()
```
    Extracts an exception's message for matching against.
    This is the same thing as calling Throwable.getMessage() and matching against that directly, except that it is a NamedFeature, so failures report more detailed information about mismatches, including what the exception class was.
    
    Returns:
    
    a named feature representing an exception's message
  - message
```
public static org.hamcrest.Matcher<Throwable> message(String message)
```
    Convenient shorthand for message().NamedFeature.thatIs(Object) thatIs}(message).
    
    Parameters:
    
    message - the full text of the exception's expected message
    
    Returns:
    
    a matcher for an exception that will verify its message
  - message
```
public static org.hamcrest.Matcher<Throwable> message(org.hamcrest.Matcher<String> matcher)
```
    Convenient shorthand for message().that(matcher).
    
    Parameters:
    
    matcher - the matcher to apply to the exception's message
    
    Returns:
    
    a matcher for an exception that will verify its message
  - messageContains
```
public static org.hamcrest.Matcher<Throwable> messageContains(String... orderedSubstrings)
```
    Convenient shorthand for message().that(orderedSubstrings(orderedSubstrings)).
    
    Parameters:
    
    orderedSubstrings - one or more substrings expected to be found in the exception's message, in the order in which they must be found
    
    Returns:
    
    a matcher for an exception that will verify its message
  - cause
```
public static NamedFeature<Throwable,Throwable> cause()
```
    Extracts an exception's cause for matching against.
    This is the same thing as calling Throwable.getCause() and matching against that directly, except that it is a NamedFeature, so failures report more detailed information about mismatches, including what the original exception was.
    
    Returns:
    
    a named feature representing an exception's cause
  - cause
```
public static org.hamcrest.Matcher<Throwable> cause(Class<? extends Throwable> expectedClass)
```
    Convenient shorthand for cause().that(instanceOf(expectedClass)).
    
    Parameters:
    
    expectedClass - the expected type of the exception's cause
    
    Returns:
    
    a matcher for an exception that will verify its cause's class
  - cause
```
public static org.hamcrest.Matcher<Throwable> cause(org.hamcrest.Matcher<Throwable> matcher)
```
    Convenient shorthand for cause().that(matcher).
    
    Parameters:
    
    matcher - the matcher to apply to the exception's cause
    
    Returns:
    
    a matcher for an exception that will verify its cause
  - catching
```
public static ExceptionMatchers.CatchResult catching(ExceptionMatchers.ThrowingRunnable runnable)
```
    Runs the ExceptionMatchers.ThrowingRunnable, catches any exception that it throws, and returns it wrapped up as a CatchResult that can be asserted against with caught(Matcher) or caughtNothing().
    
    Parameters:
    
    runnable - the runnable code that might throw an exception
    
    Returns:
    
    the exception, or empty()
  - caughtNothing
```
public static org.hamcrest.Matcher<ExceptionMatchers.CatchResult> caughtNothing()
```
    A matcher for use with catching(ThrowingRunnable) which asserts that no exception occurred.
    Of course, you could just let the exception escape instead, but there may be cases where this makes a test more convenient to write, so it is included for completeness.
```
     assertThat(catching(Thread::yield), caughtNothing());
 
```
    Returns:
    
    a matcher for a CatchResult where nothing was thrown
  - caught
```
public static org.hamcrest.Matcher<ExceptionMatchers.CatchResult> caught(@Nonnull
                                                                         Class<? extends Throwable> expected)
```
    A matcher for use with catching(ThrowingRunnable) which asserts that it throws an exception of the specified type.
    
    Parameters:
    
    expected - the type of exception that is expected to be thrown
    
    Returns:
    
    a matcher for having caught an exception of that type
  - caught
```
public static org.hamcrest.Matcher<ExceptionMatchers.CatchResult> caught(@Nonnull
                                                                         org.hamcrest.Matcher<Throwable> matcher)
```
    A matcher for use with catching(ThrowingRunnable) which asserts that it throws an exception that matches the given condition.
    
    Parameters:
    
    matcher - the matcher that the thrown exception is expected to satisfy
    
    Returns:
    
    a matcher for having caught an exception meeting those expectations

Class ExceptionMatchers

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ExceptionMatchers

Method Detail

assertThrows

assertThrows

assertThrows

assertThrows

message

message

message

messageContains

cause

cause

cause

catching

caughtNothing

caught

caught