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

feature

fun <T, R> feature(extractor: T.() -> R, assertionCreator: Expect<R>.() -> Unit): ExtractorWithCreator<T, R>(source)

Helper function to create an ExtractorWithCreator

infix fun <T, R> Expect<T>.feature(property: KProperty1<in T, R>): FeatureExpect<T, R>(source)

Extracts the property out of the current subject of this expectation, creates a new Expect for it and returns it so that subsequent calls are based on the feature.

Return

The newly created Expect for the given property.

Since

0.12.0

Samples

val person = Person(name = "John Smith", age = 25)

expect(person) feature Person::name toStartWith "John" toEndWith "Smith"
//              |              |                | subject is still of type String (value = John Smith)
//              |              | subject is still of type String (value = John Smith)
//              | subject is now String (value = John Smith)

fails {
    expect(person) feature Person::name toStartWith "Kevin" toEndWith "Bacon"
    //              |              |                | not reported because `toStartWith` fails
    //              |              | fails
    //              | subject is now String (value = 25)
}

infix fun <T, R> Expect<T>.feature(f: (T) -> R): FeatureExpect<T, R>(source)

Extracts the value which is returned when calling the method f on the current subject of this expectation, creates a new Expect for it and returns it so that subsequent calls are based on the feature.

Use feature of(...) in case the method requires parameters or in case you want to define an expectation-group for it.

Return

The newly created Expect for the return value of calling the method f on the current subject of this expectation.

Since

0.12.0

Samples

val person = Person(name = "John Smith", age = 25)

fun f(person: Person) = person.name

expect(person) feature ::f toStartWith "John" toEndWith "Smith"
//              |              |                | subject is still of type String (value = John Smith)
//              |              | subject is still of type String (value = John Smith)
//              | subject is now String (value = John Smith)

fails {
    expect(person) feature ::f toStartWith "Kevin" toEndWith "Bacon"
    //              |              |                | not reported because `toStartWith` fails
    //              |              | fails
    //              | subject is now String (value = John Smith)
}

infix fun <T, R> Expect<T>.feature(of: Feature<T, R>): FeatureExpect<T, R>(source)

Extracts a feature out of the current subject of this expectation using the given Feature.extractor, creates a new Expect for it and returns it so that subsequent calls are based on the feature.

Use of(K..., ...) to create a Feature where the first argument is the extractor in form of a KProperty1 or a KFunctionX and potentially the required arguments for a KFunctionX where X 1.

Note, Feature will be made invariant once Kotlin 1.4 is out and Atrium depends on it (most likely with 1.0.0)

Return

The newly created Expect for the extracted feature.

Since

0.12.0

Parameters

Use of(K..., ...) to create a Feature where the first argument is the extractor in form of a KProperty1 or a KFunctionX and potentially the required arguments for a KFunctionX where X 1.

Samples

val person = Person(name = "John Smith", age = 25)

fun f(person: Person, title: String) = "$title ${person.name}"

expect(person) feature of(
    ::f, "Dr."
) toStartWith "Dr. John" toEndWith "Smith"
// subject is now String (actually the return value of calling `f` with the given argument)

fails {
    expect(person) feature of(
        ::f, "Dr."
    ) toStartWith "Kevin" toEndWith "Bacon"
    // fails, not evaluated/reported because `toStartWith` already fails
}

infix fun <T, R> Expect<T>.feature(of: FeatureWithCreator<T, R>): Expect<T>(source)

Extracts a feature out of the current subject of this expectation using the given FeatureWithCreator.extractor, creates a new Expect for it, applies an expectation-group based on the given FeatureWithCreator.assertionCreator for the feature and returns the initial Expect with the current subject.

Use of(K..., ...) { ... } to create a FeatureWithCreator where the first argument is the extractor in form of a KProperty1 or a KFunctionX, the last an assertionCreator-lambda and the remaining arguments in-between the required arguments in case of a KFunctionX where X 1.

Note, FeatureWithCreator will be made invariant once Kotlin 1.4 is out and Atrium depends on it (most likely with 1.0.0)

Return

an Expect for the subject of this expectation.

Since

0.12.0

Parameters

Samples

ch.tutteli.atrium.api.infix.en_GB.samples.FeatureExtractorSamples.featureFromFunction

infix fun <T, R> Expect<T>.feature(provider: MetaFeatureOption<T>.(T) -> MetaFeature<R>): FeatureExpect<T, R>(source)

Extracts a feature out of the current subject of this expectation, based on the given provider, creates a new Expect for it and returns it so that subsequent calls are based on the feature.

Return

The newly created Expect for the extracted feature.

Since

0.12.0

Parameters

provider

Creates a MetaFeature where the subject of this expectation is available via implicit parameter it. Usually you use f to create a MetaFeature, e.g. feature { f(it::size) }

Samples

val person = Person(name = "John Smith", age = 25)

expect(person) feature { f(it::age) } toBeGreaterThan 20 toBeLessThan 30
// `it` refers to `person`, resulting subject is of type Int (actually 25)

fails {
    expect(person) feature { f(it::age) } toBeGreaterThan 30 toBeLessThan 20
    //              |                       |                | not reported because `toBeGreaterThan` fails
    //              |                       | fails
    //              | subject is now Int (value = 25)
}

infix fun <T, R> Expect<T>.feature(of: MetaFeatureOptionWithCreator<T, R>): Expect<T>(source)

Extracts a feature out of the current subject of this expectation, based on the given MetaFeatureOptionWithCreator creates a new Expect for it, applies an expectation-group based on the given MetaFeatureOptionWithCreator.assertionCreator for the feature and returns the initial Expect with the current subject.

Note that you need to enable the new type inference of Kotlin (or use Kotlin 1.4 and above) in order that Kotlin is able to infer the types. As workaround, you can use the overload which expects MetaFeatureOption<T>.(T) -> MetaFeature<R> and use it after the call (import from the package workaround). For instance:

// use
import ch.tutteli.atrium.api.infix.en_GB.workaround.it
expect(person) feature { f(it::age) } it { this toEqual 20 }

// instead of (which causes problems with Kotlin < 1.4)
expect(person) feature of({ f(it::age) }) { this toEqual 20 }

Return

an Expect for the subject of this expectation.

Since

0.12.0

Parameters

Use the function of({ ... }) { ... } to create the MetaFeatureOptionWithCreator where the first argument is a lambda with a MetaFeatureOption as receiver which has to create a MetaFeature where the subject of this expectation is available via implicit parameter it. Usually you use f to create a MetaFeature, e.g. feature of({ f(it::size) }) { it toEqual 3 }

Samples

val person = Person(name = "John Smith", age = 25)

expect(person) feature of({ f(it::age) }) { // `it` refers to `person`, subject within this expectation-group is of type Int (actually 25)
    it toBeGreaterThan 20
    it toBeLessThan 30
} // subject here is back to Person

fails {
    // all expectations are evaluated inside an expectation-group block; for more details:
    // https://github.com/robstoll/atrium#define-single-expectations-or-an-expectation-group

    expect(person) feature of({ f(it::age) }) {
        it toBeGreaterThan 30 // fails
        it toBeLessThan 20 // still evaluated, use `feature { ... } ...` if you want fail fast behaviour
    }
}