Expecting exceptions

To assert that some code does or does not throw an exception use the expectCatching function that accepts a lambda () -> Any? that performs the operation that may throw an exception, along with the isSuccess() or isFailure() assertion functions. For example:

expectCatching { identifyHotdog("hamburger") }
  .isFailure()
  .isA<NotHotdogException>()

The expectCatching function returns Assertion.Builder<Try<T>> with the assertion's subject being a wrapper for either the value the lambda returns, or the exception it throws.

Asserting failure

The failed() assertion function returns an Assertion.Builder<Throwable> so you can chain assertions about the exception itself after it. For example, combining it with the isA<T>() assertion allows testing for specific exception types.

The failed() assertion will fail if the lambda does not throw an exception.

If you just need to test that any exception was thrown you can just use the failed() assertion by itself. For example:

expectCatching { identifyHotdog("hamburger") }
  .isFailure()

With block assertions

catching is also supported inside of block assertions. The catching function returns a Assertion.Builder<Try<T>> mentioned above.

expect {
  catching { identifyHotdog("hamburger") }
    .isFailure()
    .isA<NotHotdogException>()

  catching { identifyHotdog("hotdog") }
    .isSuccess()
}
expectCatching { identifyHotdog("hotdog") }
  .isSuccess()

Shorthand form

You can also use the expectThrows<E>(A) function which is simply a shorthand for the expectCatching / failed / isA<E> combination. For example:

expectThrows<NotHotdogException> {
  identifyHotdog("hamburger")
}

Asserting success

You can also assert that an exception is not thrown by the expectCatching lambda using the isSuccess() assertion function.

The isSuccess() function returns an Assertion.Builder<T> where the type of the chained assertion subject is inferred from the value the lambda returns. This allows you to chain further assertions about the returned value.