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

toBeAFailure

inline fun <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.

Return

An Expect with the new type TExpected

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 <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.

Return

An Expect with the new type TExpected

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
    }
}