atrium-api-infix/ch.tutteli.atrium.api.infix.en_GB/toBeAFailure

toBeAFailure

inline fun <ExpectedThrowableT : Throwable> Expect<out Result<*>>.toBeAFailure(): Expect<ExpectedThrowableT>(source)

Expects that the subject of this expectation (a Result) is a failure (Result.isFailure) and that it encapsulates a Throwable of type ExpectedThrowableT or a subtype thereof.

Return

An Expect with the new type ExpectedThrowableT

Since

1.1.0 (was in kotlin_1_3 extension since 0.17.0)

Samples

val message = "wrong argument"
val failure = Result.failure<Int>(IllegalArgumentException(message))

expect(failure)
    .toBeAFailure<IllegalArgumentException>() messageToContain "argument"
//      | subject is now of type IllegalArgumentException


fails { // because sub-expectation fails
    expect(failure).toBeAFailure<IllegalArgumentException>() messageToContain "parameter"
}

fails { // because wrong Expectation type expected
    expect(failure)
        .toBeAFailure<ArithmeticException>() messageToContain "parameter"
    //     |                                  | not evaluated/reported because toBeAFailure already fails
    //     |                                  | use `toBeAFailure<...> { ... }` if you want that all expectations are evaluated
    //     | fails
}

fails { // because it was a Success
    expect(Result.success(10))
        .toBeAFailure<IllegalArgumentException>() messageToContain "parameter"
    //       |                                      | not evaluated/reported because toBeAFailure already fails
    //       |                                      | use `toBeAFailure<...> { ... }` if you want that all expectations are evaluated
    //       | fails
}

infix inline fun <ExpectedThrowableT : Throwable> Expect<out Result<*>>.toBeAFailure(noinline assertionCreator: Expect<ExpectedThrowableT>.() -> Unit): Expect<ExpectedThrowableT>(source)

Expects that the subject of this expectation (a Result) is a failure (Result.isFailure) , that it encapsulates a Throwable of type ExpectedThrowableT or a subtype thereof and that the ExpectedThrowableT holds all assertions the given assertionCreator creates

Return

An Expect with the new type ExpectedThrowableT

Since

1.1.0 (was in kotlin_1_3 extension since 0.17.0)

Samples

val errorMessage = "can not divide by zero"
val failure = Result.failure<Int>(ArithmeticException(errorMessage))

expect(failure).toBeAFailure<ArithmeticException> {  // subject within this expectation-group is of type ArithmeticException
    messageToContain("by zero")
} // subject here is back to type Result<Int>

fails { // because sub-expectation fails
    expect(failure).toBeAFailure<IllegalArgumentException> {
        its messageToContain "parameter" // fails
        its.message toStartWith "wrong"  // still evaluated even though messageToContain already fails
        //                                  use `.toBeAFailure.` if you want a fail fast behaviour
    }
}

fails { // because wrong Expectation type expected, but since we use an expectation-group...
    expect(failure).toBeAFailure<ArithmeticException> {
        its messageToContain "parameter" // ...reporting mentions that subject's message was expected `to contain: "parameter"``
        //                                  use `.toBeAFailure.` if you want a fail fast behaviour
    }
}

fails { // because it was a Success, but since we use a block
    expect(Result.success(10)).toBeAFailure<IllegalArgumentException> {
        its messageToContain "parameter" // ...reporting mentions that subject's message was expected `to contain: "parameter"``
        //                                  use `.toBeAFailure.` if you want a fail fast behaviour
    }
}