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

extractSubject

infix fun <T> Expect<T>.extractSubject(assertionCreator: Expect<T>.(T) -> Unit): Expect<T>(source)

Extracts the subject of this Expect in case it is defined and passes it to the given assertionCreator or adds a failing assertion to this Expect in case the subject is absent (e.g. due to a previous extraction failure).

Use the overload which expects an FailureDescriptionWithCreator if you want to use a custom failure description in case the subject extraction is not possible as it is absent.

Return

an Expect for the subject of this expectation.

Since

1.2.0

Parameters

assertionCreator

The assertion-creator lambda which is responsible to create and append at least 1 assertion to this Expect.

Samples

val persons = dataGenerator.getRandomPersonsWithChildren()
expect(persons) toHaveElementsAndAll {
    extractSubject { person ->
        feature { f(it::children) } notToHaveElementsOrAll {
            because("person should at least be 16 years older than its children") {
                feature { f(it::age) } toBeLessThan person.age - 16
            }
        }
    }
}
infix fun <T> Expect<T>.extractSubject(withFailureDescription: FailureDescriptionWithCreator<T>): Expect<T>(source)

Extracts the subject of this Expect in case it is defined and passes it to the given FailureDescriptionWithCreator.assertionCreator or adds a failing assertion to this Expect in case the subject is absent (e.g. due to a previous extraction failure) using the given FailureDescriptionWithCreator.failureDescription.

Use the function withFailureDescription(String) { ... } to create an FailureDescriptionWithCreator.

Return

an Expect for the subject of this expectation.

Since

1.2.0

Parameters

withFailureDescription

The parameter object which contains the FailureDescriptionWithCreator.failureDescription and FailureDescriptionWithCreator.assertionCreator. Use the function withFailureDescription(String) { ... } to create an FailureDescriptionWithCreator.

Samples

// imagine the data generator should not return an empty list
val persons = dataGenerator.getRandomPersonsHasABugReturnsEmptyList()
fails { // because persons is empty
    expect(persons) toHaveElementsAndAll { // fails
        // hence the sub-expectations within extractSubject cannot be evaluated
        // and instead we show the custom failure description
        withFailureDescription<Person2>("no person defined, cannot extract subject") {
            extractSubject { person ->
                feature { f(it::children) } notToHaveElementsOrAll {
                    because("person should at least be 16 years older than its children") {
                        feature { f(it::age) } toBeLessThan person.age - 16
                    }
                }
            }
        }
    }
}