doc / ch.tutteli.atrium.api.fluent.en_GB / feature

feature

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.

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

expect(person)
    .feature(Person::name) // subject is now String
    .toStartWith("John")
    .toEndWith("Smith")

fails {
    expect(person)
        .feature(Person::name)
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kprop) { ... }` if you want that all assertions are evaluated
}

Return
The newly created Expect for the given property.

Since
0.9.0

fun <T, R> Expect<T>.feature(property: KProperty1<in T, R>, assertionCreator: Expect<R>.() -> Unit): Expect<T> (source)

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

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

expect(person)
    .feature(Person::name) { // subject within this block is of type String
        toStartWith("John")
        toEndWith("Smith")
    } // subject here is back to type Person

fails {
    expect(person)
        .feature(Person::name) {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated, use `.feature(kprop).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

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

Extracts the value which is returned when calling 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.

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

fun f(person: Person) = person.name

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

fails {
    expect(person)
        .feature(::f)
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kfun) { ... }` if you want that all assertions are evaluated
}

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

Since
0.9.0

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

Extracts the value which is returned when calling f on the current subject of this expectation, creates a new Expect for it, applies an assertion group based on the given assertionCreator for the feature and returns the initial Expect with the current subject.

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

fun f(person: Person) = person.name

expect(person)
    .feature(::f) { // subject is now String, after function [f] is applied
        toStartWith("John")
        toEndWith("Smith")
    } // subject here is back type Person

fails {
    expect(person)
        .feature(::f) {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated, use `.feature(kfun).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

fun <T, A1, R> Expect<T>.feature(f: KFunction2<T, A1, R>, a1: A1): FeatureExpect<T, R> (source)

Extracts the value which is returned when calling f with argument a1 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.

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

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

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

fails {
    expect(person)
        .feature(::f, "Dr.")
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kfun, arg1) { ... }` if you want that all assertions are evaluated
}

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

Since
0.9.0

fun <T, A1, R> Expect<T>.feature(f: KFunction2<T, A1, R>, a1: A1, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

Extracts the value which is returned when calling f with argument a1 on the current subject of this expectation, creates a new Expect for it, applies an assertion group based on the given assertionCreator for the feature and returns the initial Expect with the current subject.

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

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

expect(person)
    .feature(
        ::f,
        "Dr."
    ) {// subject within this block is of type String (actually the return value of calling `f` with the given argument)
        toStartWith("Dr. John")
        toEndWith("Smith")
    } // subject here is back type Person

fails {
    expect(person)
        .feature(::f, "Dr.") {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated even though `toStartWith` already fails
            //                      use `.feature(kfun, arg1).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

fun <T, A1, A2, R> Expect<T>.feature(f: KFunction3<T, A1, A2, R>, a1: A1, a2: A2): FeatureExpect<T, R> (source)

Extracts the value which is returned when calling f with arguments a1, a2 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.

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

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

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

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP")
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kfun, arg1, arg2) { ... }` if you want that all assertions are evaluated
}

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

Since
0.9.0

fun <T, A1, A2, R> Expect<T>.feature(f: KFunction3<T, A1, A2, R>, a1: A1, a2: A2, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

Extracts the value which is returned when calling f with argument a1, a2 on the current subject of this expectation, creates a new Expect for it, applies an assertion group based on the given assertionCreator for the feature and returns the initial Expect with the current subject.

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

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

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP"
    ) { // subject within this block is of type String (actually the return value of calling `f` with the given two arguments)
        toStartWith("Dr. John")
        toEndWith("Smith, PMP")
    } // subject here is back type Person

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP") {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated even though `toStartWith` already fails
            //                      use `.feature(kfun, arg1, arg2).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

fun <T, A1, A2, A3, R> Expect<T>.feature(f: KFunction4<T, A1, A2, A3, R>, a1: A1, a2: A2, a3: A3): FeatureExpect<T, R>

(source)

Extracts the value which is returned when calling f with arguments a1, a2, a3 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.

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

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

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP",
        "Native"
    ) // subject is now String (actually the return value of calling `f` with the given three arguments)
    .toStartWith("Dr. John Smith")
    .toContain("PMP")
    .toEndWith("English level: Native")

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP", "Native")
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kfun, a1, a2, a3) { ... }` if you want that all assertions are evaluated
}

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

Since
0.9.0

fun <T, A1, A2, A3, R> Expect<T>.feature(f: KFunction4<T, A1, A2, A3, R>, a1: A1, a2: A2, a3: A3, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

Extracts the value which is returned when calling f with argument a1, a2, a3 on the current subject of this expectation, creates a new Expect for it, applies an assertion group based on the given assertionCreator for the feature and returns the initial Expect with the current subject.

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

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

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP",
        "Native"
    ) { // subject within this block is of type String (actually the return value of calling `f` with the given three arguments)
        toStartWith("Dr. John Smith")
        toContain("PMP")
        toEndWith("English level: Native")
    } // subject here is back type Person

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP", "Native") {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated even though `toStartWith` already fails
            //                      use `.feature(kfun, a1, a2, a3).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

fun <T, A1, A2, A3, A4, R> Expect<T>.feature(f: KFunction5<T, A1, A2, A3, A4, R>, a1: A1, a2: A2, a3: A3, a4: A4): FeatureExpect<T, R>

(source)

Extracts the value which is returned when calling f with arguments a1, a2, a3, a4 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.

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

fun f(person: Person, title: String, suffix: String, english: String, german: String) =
    "$title ${person.name}, $suffix. English level: $english, German level: $german"

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP",
        "Native",
        "C1"
    ) // subject is now String (actually the return value of calling `f` with the given four arguments)
    .toStartWith("Dr. John Smith")
    .toContain("PMP")
    .toContain("English level: Native")
    .toEndWith("German level: C1")

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP", "Native", "C1")
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kfun, a1, a2, a3, a4) { ... }` if you want that all assertions are evaluated
}

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

Since
0.9.0

fun <T, A1, A2, A3, A4, R> Expect<T>.feature(f: KFunction5<T, A1, A2, A3, A4, R>, a1: A1, a2: A2, a3: A3, a4: A4, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

Extracts the value which is returned when calling f with argument a1, a2, a3, a4 on the current subject of this expectation, creates a new Expect for it, applies an assertion group based on the given assertionCreator for the feature and returns the initial Expect with the current subject.

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

fun f(person: Person, title: String, suffix: String, english: String, german: String) =
    "$title ${person.name}, $suffix. English level: $english, German level: $german"

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP",
        "Native",
        "C1"
    ) { // subject within this block is of type String (actually the return value of calling `f` with the given four arguments)
        toStartWith("Dr. John Smith")
        toContain("PMP")
        toContain("English level: Native")
        toEndWith("German level: C1")
    } // subject here is back type Person

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP", "Native", "C1") {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated even though `toStartWith` already fails
            //                      use `.feature(kfun, a1, a2, a3, a4).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

fun <T, A1, A2, A3, A4, A5, R> Expect<T>.feature(f: KFunction6<T, A1, A2, A3, A4, A5, R>, a1: A1, a2: A2, a3: A3, a4: A4, a5: A5): FeatureExpect<T, R>

(source)

Extracts the value which is returned when calling f with arguments a1, a2, a3, a4, a5 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.

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

fun f(person: Person, title: String, suffix: String, english: String, german: String, spanish: String) =
    "$title ${person.name}, $suffix. English level: $english, German level: $german, Spanish level: $spanish"

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP",
        "Native",
        "C1",
        "B2"
    ) // subject is now String (actually the return value of calling `f` with the given five arguments)
    .toStartWith("Dr. John Smith")
    .toContain("PMP")
    .toContain("English level: Native")
    .toContain("German level: C1")
    .toEndWith("Spanish level: B2")

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP", "Native", "C1", "B2")
        .toStartWith("Kevin") // fails
        .toEndWith("Bacon")   // not evaluated/reported because `toStartWith` already fails
    //                           use `.feature(kfun, a1, a2, a3, a4, a5) { ... }` if you want that all assertions are evaluated
}

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

Since
0.9.0

fun <T, A1, A2, A3, A4, A5, R> Expect<T>.feature(f: KFunction6<T, A1, A2, A3, A4, A5, R>, a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

Extracts the value which is returned when calling f with argument a1, a2, a3, a4, a5 on the current subject of this expectation, creates a new Expect for it, applies an assertion group based on the given assertionCreator for the feature and returns the initial Expect with the current subject.

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

fun f(person: Person, title: String, suffix: String, english: String, german: String, spanish: String) =
    "$title ${person.name}, $suffix. English level: $english, German level: $german, Spanish level: $spanish"

expect(person)
    .feature(
        ::f,
        "Dr.",
        "PMP",
        "Native",
        "C1",
        "B2"
    ) { // subject within this block is of type String (actually the return value of calling `f` with the given five arguments)
        toStartWith("Dr. John Smith")
        toContain("PMP")
        toContain("English level: Native")
        toContain("German level: C1")
        toEndWith("Spanish level: B2")
    } // subject here is back type Person

fails {
    expect(person)
        .feature(::f, "Dr.", "PMP", "Native", "C1", "B2") {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toStartWith("Kevin") // fails
            toEndWith("Bacon")   // still evaluated even though `toStartWith` already fails
            //                      use `.feature(kfun, a1, a2, a3, a4, a5).` if you want fail fast behaviour
        }
}

Return
an Expect for the subject of this expectation.

Since
0.9.0

fun <T, R> Expect<T>.feature(description: String, provider: T.() -> R): FeatureExpect<T, R> (source)

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

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

expect(person)
    .feature("Actual age", Person::age) // subject is now Int (actually 25)
    .toBeLessThan(30)
    .toBeGreaterThan(20)

fails {
    // Reporting will include the description:
    // expected that subject: Person(name=John Smith, age=25)
    //   * Actual age:        25
    //     - to be less than: 30
    expect(person)
        .feature("Actual age", Person::age)
        .toBeLessThan(20)    // fails
        .toBeGreaterThan(30) // not evaluated/reported because `toBeLessThan` already fails
    //                          use `.feature(descr, kprop) { ... }` if you want that all assertions are evaluated
}

Parameters

provider - Extracts the feature where the subject of this expectation is available via implicit parameter it.

Return
The newly created Expect for the extracted feature.

Since
0.9.0

fun <T, R> Expect<T>.feature(description: String, provider: T.() -> R, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

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

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

expect(person)
    .feature("Actual age", Person::age) { // subject within this block is now of type Int (actually 25)
        toBeLessThan(30)
        toBeGreaterThan(20)
    } // subject here is back type Person

fails {
    // Reporting will include the description:
    // expected that subject: Person(name=John Smith, age=25)
    //   * Actual age:           25
    //     - to be less than:    30
    //     - to be greater than: 30

    expect(person)
        .feature("Actual age", Person::age) {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toBeLessThan(20)    // fails
            toBeGreaterThan(30) // still evaluated even though `toBeLessThan` already fails
            //                     use `.feature(descr, kprop).` if you want fail fast behaviour
        }
}

Parameters

provider - Extracts the feature where the subject of this expectation is available via implicit parameter it.

Return
an Expect for the subject of this expectation.

Since
0.9.0

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.

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

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

fails {
    expect(person)
        .feature { f(it::age) }
        .toBeGreaterThan(30) // fails
        .toBeLessThan(20)    // not evaluated/reported because `toBeGreaterThan` already fails
    //                          use `.feature({ extractor }) { ... }` if you want that all assertions are evaluated
}

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

Return
The newly created Expect for the extracted feature.

Since
0.9.0

fun <T, R> Expect<T>.feature(provider: MetaFeatureOption<T>.(T) -> MetaFeature<R>, assertionCreator: Expect<R>.() -> Unit): Expect<T>

(source)

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

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

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

fails {
    expect(person)
        .feature({ f(it::age) }) {
            // introduces an expectation group block
            // all expectations are evaluated inside an expectation group block; for more details:
            // https://github.com/robstoll/atrium#define-single-expectations-or-expectation-groups

            toBeGreaterThan(30) // fails
            toBeLessThan(20)    // still evaluated even though `toBeLessThan` already fails
            //                     use `.feature({ extractor }).` if you want fail fast behaviour
        }
}

Parameters

provider - You need to create a MetaFeature where the subject of this expectation is available via implicit parameter it. Usually you use MetaFeatureOption.f to create a MetaFeature, e.g. f(it::size)

Return
an Expect for the subject of this expectation.

Since
0.9.0