atrium-api-fluent/ch.tutteli.atrium.api.fluent.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>() // 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
}

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> {
        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 an expectation-group...
    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
    }
}