doc / ch.tutteli.atrium.api.fluent.en_GB.kotlin_1_3 / toBeAFailure

toBeAFailure

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

Expects that the subject of this expectation (a Result) is a failure (Result.isFailure) and that it encapsulates an exception of type TExpected.

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

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


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

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

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

Return
An Expect with the new type TExpected

Since
0.17.0

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

Expects that the subject of this expectation (a Result) is a failure (Result.isFailure) , that it encapsulates an exception of type TExpected and that the exception holds all assertions the given assertionCreator creates.

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

expect(failure).toBeAFailure<ArithmeticException> {  // subject within this block is of type ArithmeticException
    messageToContain("parameter")
} // subject here is back to type Result<Int>

fails { // because sub-expectation fails
    expect(failure).toBeAFailure<IllegalArgumentException> {
        messageToContain("parameter") // fails
        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 a block...
    expect(failure).toBeAFailure<ArithmeticException> {
        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> {
        messageToContain("parameter") // ...reporting mentions that subject's message was expected `to contain: "parameter"``
        //                               use `.toBeAFailure.` if you want a fail fast behaviour
    }
}

Return
An Expect with the new type TExpected

Since
0.17.0