@serenity-js/assertions 3.0.0-rc.8 → 3.0.0

package/src/Ensure.ts

@@ -1,4 +1,5 @@
 import {
+    Activity,
     Answerable,
     AnswersQuestions,
     AssertionError,
@@ -7,192 +8,165 @@ import {
     Expectation,
     ExpectationMet,
     ExpectationNotMet,
-    ExpectationOutcome,
     f,
     Interaction,
     LogicError,
+    RaiseErrors,
     RuntimeError,
     UsesAbilities,
 } from '@serenity-js/core';
-import { inspected } from '@serenity-js/core/lib/io/inspected';
-import { Artifact, AssertionReport, Name } from '@serenity-js/core/lib/model';
-import { match } from 'tiny-types';
+import { FileSystemLocation } from '@serenity-js/core/lib/io';
+
+import { EnsureEventually } from './EnsureEventually';
 
 /**
- * @desc
- *  Used to perform verification of the system under test.
- *
- *  Resolves any `Answerable` describing the actual
- *  state and ensures that its value meets the {@link @serenity-js/core/lib/screenplay/questions~Expectation}s provided.
+ * The {@apilink Interaction|interaction} to `Ensure`
+ * verifies if the resolved value of the provided {@apilink Answerable}
+ * meets the specified {@apilink Expectation}.
+ * If not, it throws an {@apilink AssertionError}.
  *
- * @example <caption>Usage with static values</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * Use `Ensure` to verify the state of the system under test.
  *
- *  const actor = actorCalled('Erica');
+ * ## Basic usage with static values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- *  actor.attemptsTo(
- *    Ensure.that('Hello world!', equals('Hello world!'))
- *  );
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', equals('Hello world!'))
+ * )
+ * ```
  *
- * @example <caption>Composing expectations with `and`</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions';
+ * ## Composing expectations with `and`
  *
- *  const actor = actorCalled('Erica');
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
  *
- *  actor.attemptsTo(
- *    Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
- *  );
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
+ * )
+ * ```
  *
- * @example <caption>Overriding the type of Error thrown upon assertion failure</caption>
- *  import { actorCalled, TestCompromisedError } from '@serenity-js/core';
- *  import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions';
- *  import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest';
+ * ## Overriding the type of Error thrown upon assertion failure
  *
- *  const actor = actorCalled('Erica')
- *      .whoCan(CallAnApi.at('https://example.com'));
+ * ```ts
+ * import { actorCalled, TestCompromisedError } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
  *
- *  actor.attemptsTo(
- *    Send.a(GetRequest.to('/api/health')),
- *    Ensure.that(LastResponse.status(), equals(200))
- *      .otherwiseFailWith(TestCompromisedError, 'The server is down, please cheer it up!')
- *  );
+ * await actorCalled('Erica')
+ *   .whoCan(CallAnApi.at('https://example.com'))
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/api/health')),
+ *     Ensure.that(LastResponse.status(), equals(200))
+ *       .otherwiseFailWith(TestCompromisedError, 'The server is down, please cheer it up!')
+ *   )
+ * ```
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * @group Activities
  */
 export class Ensure<Actual> extends Interaction {
+
     /**
+     * Creates an {@apilink Interaction|interaction} to `Ensure`, which
+     * verifies if the resolved value of the provided {@apilink Answerable}
+     * meets the specified {@apilink Expectation}.
+     * If not, it immediately throws an {@apilink AssertionError}.
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<T>} actual
-     * @param {@serenity-js/core/lib/screenplay/questions~Expectation<any, A>} expectation
+     * @param {Answerable<Actual_Type>} actual
+     *  An {@apilink Answerable} describing the actual state of the system.
      *
-     * @returns {Ensure<A>}
+     * @param {Expectation<Actual_Type>} expectation
+     *  An {@apilink Expectation} you expect the `actual` value to meet
+     *
+     * @returns {Ensure<Actual_Type>}
      */
-    static that<A>(actual: Answerable<A>, expectation: Expectation<A>): Ensure<A> {
-        return new Ensure(actual, expectation);
+    static that<Actual_Type>(actual: Answerable<Actual_Type>, expectation: Expectation<Actual_Type>): Ensure<Actual_Type> {
+        return new Ensure(actual, expectation, Activity.callerLocation(5));
     }
 
     /**
-     * @param {@serenity-js/core/lib/screenplay~Answerable<T>} actual
-     * @param {@serenity-js/core/lib/screenplay/questions~Expectation<T>} expectation
+     * Creates an {@apilink Interaction|interaction} to {@apilink EnsureEventually}, which
+     * verifies if the resolved value of the provided {@apilink Answerable}
+     * meets the specified {@apilink Expectation} within the expected timeframe.
+     *
+     * If the expectation is not met by the time the timeout expires, the interaction throws an {@apilink AssertionError}.
+     * `EnsureEventually` ignores retries the evaluation if resolving the `actual` results in an {@apilink OptionalNotPresentError},
+     * but rethrows any other errors.
+     *
+     * @param {Answerable<Actual_Type>} actual
+     *  An {@apilink Answerable} describing the actual state of the system.
+     *
+     * @param {Expectation<Actual_Type>} expectation
+     *  An {@apilink Expectation} you expect the `actual` value to meet
+     *
+     * @returns {Ensure<Actual_Type>}
      */
-    constructor(
+    static eventually<Actual_Type>(actual: Answerable<Actual_Type>, expectation: Expectation<Actual_Type>): EnsureEventually<Actual_Type> {
+        return new EnsureEventually(actual, expectation, Activity.callerLocation(5));
+    }
+
+    /**
+     * @param actual
+     * @param expectation
+     * @param location
+     */
+    private constructor(
         protected readonly actual: Answerable<Actual>,
         protected readonly expectation: Expectation<Actual>,
+        location: FileSystemLocation,
     ) {
-        super();
+        super(d`#actor ensures that ${ actual } does ${ expectation }`, location);
     }
 
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & CollectsArtifacts & AnswersQuestions} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~CollectsArtifacts}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
         const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
 
-        return match<ExpectationOutcome<unknown, Actual>, void>(outcome)
-            .when(ExpectationNotMet, o => {
-                actor.collect(this.artifactFrom(o.expected, o.actual), new Name(`Assertion Report`));
+        if (outcome instanceof ExpectationNotMet) {
+            const actualDescription = d`${ this.actual }`;
+            const message = `Expected ${ actualDescription } to ${ outcome.message }`;
 
-                throw this.errorForOutcome(o);
-            })
-            .when(ExpectationMet, _ => void 0)
-            .else(o => {
-                throw new LogicError(f`Expectation#isMetFor(actual) should return an instance of an ExpectationOutcome, not ${ o }`);
+            throw RaiseErrors.as(actor).create(AssertionError, {
+                message,
+                expectation: outcome.expectation,
+                diff: { expected: outcome.expected, actual: outcome.actual },
+                location: this.instantiationLocation(),
             });
-    }
+        }
 
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return d`#actor ensures that ${ this.actual } does ${ this.expectation }`;
+        if (! (outcome instanceof ExpectationMet)) {
+            throw new LogicError(f`Expectation#isMetFor(actual) should return an instance of an ExpectationOutcome, not ${ outcome }`);
+        }
     }
 
     /**
-     * @desc
-     *  Overrides the default {@link @serenity-js/core/lib/errors~AssertionError} thrown when
-     *  the actual value does not meet the expectations set.
+     * Overrides the default {@apilink AssertionError} thrown when
+     * the actual value does not meet the expectation.
      *
-     * @param {Function} typeOfRuntimeError
-     *  The type of RuntimeError to throw, i.e. TestCompromisedError
+     * @param typeOfRuntimeError
+     *  A constructor function producing a subtype of {@apilink RuntimeError} to throw, e.g. {@apilink TestCompromisedError}
      *
-     * @param {string} message
+     * @param message
      *  The message explaining the failure
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
      */
     otherwiseFailWith(typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError, message?: string): Interaction {
-        return new EnsureOrFailWithCustomError(this.actual, this.expectation, typeOfRuntimeError, message);
-    }
+        const location = this.instantiationLocation();
 
-    /**
-     * @desc
-     *  Maps an {@link @serenity-js/core/lib/screenplay/questions/expectations~ExpectationOutcome} to appropriate {@link @serenity-js/core/lib/errors~RuntimeError}.
-     *
-     * @param {@serenity-js/core/lib/screenplay/questions/expectations~ExpectationOutcome} outcome
-     * @returns {@serenity-js/core/lib/errors~RuntimeError}
-     *
-     * @protected
-     */
-    protected errorForOutcome(outcome: ExpectationOutcome<any, Actual>): RuntimeError {
-        return this.asAssertionError(outcome);
-    }
-
-    /**
-     * @desc
-     *  Maps an {@link Outcome} to {@link @serenity-js/core/lib/errors~AssertionError}.
-     *
-     * @param {Outcome} outcome
-     * @returns {@serenity-js/core/lib/errors~AssertionError}
-     *
-     * @protected
-     */
-    protected asAssertionError(outcome: ExpectationOutcome<any, Actual>): AssertionError {
-        return new AssertionError(
-            `Expected ${ d`${ this.actual }` } to ${ outcome.message }`,
-            outcome.expected,
-            outcome.actual,
-        );
-    }
-
-    private artifactFrom(expected: any, actual: Actual): Artifact {
-        return AssertionReport.fromJSON({
-            expected: inspected(expected),
-            actual: inspected(actual),
+        return Interaction.where(this.toString(), async actor => {
+            try {
+                await this.performAs(actor);
+            }
+            catch (error) {
+                throw RaiseErrors.as(actor).create(typeOfRuntimeError, {
+                    message: message ?? error.message,
+                    location,
+                    cause: error
+                });
+            }
         });
     }
 }
-
-/**
- * @package
- */
-class EnsureOrFailWithCustomError<Actual> extends Ensure<Actual> {
-    constructor(
-        actual: Answerable<Actual>,
-        expectation: Expectation<Actual>,
-        private readonly typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError,
-        private readonly message?: string,
-    ) {
-        super(actual, expectation);
-    }
-
-    protected errorForOutcome(outcome: ExpectationOutcome<any, Actual>): RuntimeError {
-        const assertionError = this.asAssertionError(outcome);
-
-        return new this.typeOfRuntimeError(this.message || assertionError.message, assertionError);
-    }
-}

package/src/EnsureEventually.ts

@@ -0,0 +1,173 @@
+import {
+    Answerable,
+    AnswersQuestions,
+    AssertionError,
+    CollectsArtifacts,
+    d,
+    Duration,
+    Expectation,
+    ExpectationMet,
+    ExpectationOutcome,
+    Interaction,
+    ListItemNotFoundError,
+    RaiseErrors,
+    RuntimeError,
+    ScheduleWork,
+    TimeoutExpiredError,
+    UsesAbilities,
+} from '@serenity-js/core';
+import { FileSystemLocation } from '@serenity-js/core/lib/io';
+
+/**
+ * The {@apilink Interaction|interaction} to `EnsureEventually`
+ * verifies if the resolved value of the provided {@apilink Answerable}
+ * meets the specified {@apilink Expectation} within the expected timeframe.
+ *
+ * If the expectation is not met by the time the timeout expires, the interaction throws an {@apilink AssertionError}.
+ * `EnsureEventually` retries the evaluation if resolving the `actual` results in an {@apilink ListItemNotFoundError},
+ * but rethrows any other errors.
+ *
+ * :::tip Use the factory method
+ * Use the factory method {@apilink Ensure.eventually} to instantiate this interaction.
+ * :::
+ *
+ * ## Basic usage with dynamic values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     equals('Learn Serenity/JS!')
+ *   )
+ * )
+ * ```
+ *
+ * ## Composing expectations with `and`
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     and(startsWith('Serenity'), endsWith('!'))
+ *   )
+ * )
+ * ```
+ *
+ * ## Overriding the type of Error thrown upon assertion failure
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     and(startsWith('Serenity'), endsWith('!'))
+ *   ).otherwiseFailWith(LogicError, `Looks like we're not on the right page`)
+ * )
+ * ```
+ *
+ * @experimental
+ *
+ * @group Activities
+ */
+export class EnsureEventually<Actual> extends Interaction {
+    /**
+     * @param actual
+     * @param expectation
+     * @param location
+     * @param timeout
+     */
+    constructor(
+        protected readonly actual: Answerable<Actual>,
+        protected readonly expectation: Expectation<Actual>,
+        location: FileSystemLocation,
+        protected readonly timeout?: Duration,
+    ) {
+        super(d`#actor ensures that ${ actual } does eventually ${ expectation }`, location);
+    }
+
+    /**
+     * Override the default timeout set via {@apilink SerenityConfig.interactionTimeout}.
+     *
+     * @param timeout
+     */
+    timeoutAfter(timeout: Duration): EnsureEventually<Actual> {
+        return new EnsureEventually<Actual>(this.actual, this.expectation, this.instantiationLocation(), timeout);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
+        await ScheduleWork.as(actor).repeatUntil<ExpectationOutcome>(
+            () => actor.answer(this.expectation.isMetFor(this.actual)),
+            {
+                exitCondition: outcome =>
+                    outcome instanceof ExpectationMet,
+
+                delayBetweenInvocations: (invocation) => invocation === 0
+                    ? Duration.ofMilliseconds(0)                        // perform the first evaluation straight away
+                    : Duration.ofMilliseconds(2 ** invocation * 100),   // use simple exponential backoff strategy for subsequent calls
+
+                timeout: this.timeout,
+
+                errorHandler: (error, outcome) => {
+                    if (error instanceof ListItemNotFoundError) {
+                        return; // ignore, lists might get populated later
+                    }
+
+                    if (error instanceof TimeoutExpiredError) {
+
+                        const actualDescription = d`${ this.actual }`;
+                        const message = outcome ? `Expected ${ actualDescription } to eventually ${ outcome?.message }` : error.message;
+
+                        throw RaiseErrors.as(actor).create(AssertionError, {
+                            message,
+                            expectation: outcome?.expectation,
+                            diff: outcome && { expected: outcome?.expected, actual: outcome?.actual },
+                            location: this.instantiationLocation(),
+                            cause: error,
+                        });
+                    }
+
+                    throw error;
+                },
+            },
+        );
+    }
+
+    /**
+     * Overrides the default {@apilink AssertionError} thrown when
+     * the actual value does not meet the expectation.
+     *
+     * @param typeOfRuntimeError
+     *  A constructor function producing a subtype of {@apilink RuntimeError} to throw, e.g. {@apilink TestCompromisedError}
+     *
+     * @param message
+     *  The message explaining the failure
+     */
+    otherwiseFailWith(typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError, message?: string): Interaction {
+        const location = this.instantiationLocation();
+
+        return Interaction.where(this.toString(), async actor => {
+            try {
+                await this.performAs(actor);
+            } catch (error) {
+                throw RaiseErrors.as(actor).create(typeOfRuntimeError, {
+                    message: message ?? error.message,
+                    location,
+                    cause: error,
+                });
+            }
+        });
+    }
+}

package/src/expectations/and.ts

@@ -1,7 +1,26 @@
-import { Answerable, AnswersQuestions, Expectation, ExpectationNotMet } from '@serenity-js/core';
-import { match } from 'tiny-types';
+import { Answerable, AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
 
-export function and<Actual>(...expectations: Array<Expectation<Actual>>): Expectation<Actual> {
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when all the `expectations` are met for the given actual value.
+ *
+ * Use `and` to combine several expectations using logical "and",
+ *
+ * ## Combining several expectations
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, and, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', and(startsWith('Hello'), endsWith('!'))),
+ * )
+ * ```
+ *
+ * @param expectations
+ *
+ * @group Expectations
+ */
+export function and<Actual_Type>(...expectations: Array<Expectation<Actual_Type>>): Expectation<Actual_Type> {
     return new And(expectations);
 }
 
@@ -12,18 +31,23 @@ class And<Actual> extends Expectation<Actual> {
     private static readonly Separator = ' and ';
 
     constructor(private readonly expectations: Array<Expectation<Actual>>) {
+        const description = expectations.map(expectation => expectation.toString()).join(And.Separator);
+
         super(
-            expectations.map(expectation => expectation.toString()).join(And.Separator),
-            (actor: AnswersQuestions, actual: Answerable<Actual>) => {
-                return expectations.reduce(
-                    (previous, current) =>
-                        previous.then(outcome =>
-                            match(outcome)
-                                .when(ExpectationNotMet, o => o)
-                                .else(_ => actor.answer(current.isMetFor(actual))),
-                        ),
-                    Promise.resolve(void 0),
-                );
+            'and',
+            description,
+            async (actor: AnswersQuestions, actual: Answerable<Actual>) => {
+                let outcome: ExpectationOutcome;
+
+                for (const expectation of expectations) {
+                    outcome = await actor.answer(expectation.isMetFor(actual))
+
+                    if (outcome instanceof ExpectationNotMet) {
+                        return new ExpectationNotMet(description, outcome.expectation, outcome.expected, outcome.actual);
+                    }
+                }
+
+                return new ExpectationMet(description, outcome?.expectation, outcome?.expected, outcome?.actual);
             }
         );
     }

package/src/expectations/contain.ts

@@ -1,7 +1,32 @@
-import { Answerable, Expectation } from '@serenity-js/core';
+import { Expectation } from '@serenity-js/core';
 import { equal } from 'tiny-types/lib/objects';
 
-export function contain<Item>(expected: Answerable<Item>): Expectation<Item[]> {
-    return Expectation.thatActualShould<Item, Item[]>('contain', expected)
-        .soThat((actualValue, expectedValue) => !! ~ actualValue.findIndex(av => equal(av, expectedValue)));
-}
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when the actual array of `Item[]` contains
+ * at least one `Item` that is equal to the resolved value of `expected`.
+ *
+ * Note that the equality check performs comparison **by value**
+ * using [TinyTypes `equal`](https://github.com/jan-molak/tiny-types/blob/master/src/objects/equal.ts).
+ *
+ * ## Ensuring that the array contains the given item
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, and, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * const items = [ { name: 'apples' }, { name: 'bananas' } ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(items, contain({ name: 'bananas' })),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export const contain = Expectation.define(
+    'contain', 'contain',
+    <Item>(actual: Item[], expected: Item) =>
+        actual.some(item => equal(item, expected))
+);

package/src/expectations/containAtLeastOneItemThat.ts

@@ -1,34 +1,58 @@
-import { Answerable, AnswersQuestions, d, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, d, Expectation, ExpectationDetails, ExpectationMet, ExpectationNotMet, ExpectationOutcome, Unanswered } from '@serenity-js/core';
 
-export function containAtLeastOneItemThat<Actual>(expectation: Expectation<Actual>): Expectation<Actual[]> {
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when the actual array of `Item[]` contains
+ * at least one `Item` for which the `expectation` is met.
+ *
+ * ## Ensuring that at least one item in an array meets the expectation
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, containAtLeastOneItemThat, isGreaterThan } from '@serenity-js/assertions'
+ *
+ * const items = [ 10, 15, 20 ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(items, containAtLeastOneItemThat(isGreaterThan(18))),
+ * )
+ * ```
+ *
+ * @param expectation
+ *
+ * @group Expectations
+ */
+export function containAtLeastOneItemThat<Item>(expectation: Expectation<Item>): Expectation<Item[]> {
     return new ContainAtLeastOneItemThatMeetsExpectation(expectation);
 }
 
 /**
  * @package
  */
-class ContainAtLeastOneItemThatMeetsExpectation<Actual> extends Expectation<Actual[]> {
+class ContainAtLeastOneItemThatMeetsExpectation<Item> extends Expectation<Item[]> {
 
     private static descriptionFor(expectation: Expectation<any>) {
         return d`contain at least one item that does ${ expectation }`;
     }
 
-    constructor(private readonly expectation: Expectation<Actual>) {
+    constructor(private readonly expectation: Expectation<Item>) {
         super(
+            'containAtLeastOneItemThat',
             ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
-            async (actor: AnswersQuestions, actual: Answerable<Actual[]>) => {
+            async (actor: AnswersQuestions, actual: Answerable<Item[]>) => {
 
-                const items: Actual[] = await actor.answer(actual);
+                const items: Item[] = await actor.answer(actual);
 
                 if (! items || items.length === 0) {
+                    const unanswered = new Unanswered();
                     return new ExpectationNotMet(
                         ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
-                        undefined,
+                        ExpectationDetails.of('containAtLeastOneItemThat', unanswered),
+                        unanswered,
                         items,
                     );
                 }
 
-                let outcome: ExpectationOutcome<unknown, Actual>;
+                let outcome: ExpectationOutcome;
 
                 for (const item of items) {
 
@@ -37,13 +61,19 @@ class ContainAtLeastOneItemThatMeetsExpectation<Actual> extends Expectation<Actu
                     if (outcome instanceof ExpectationMet) {
                         return new ExpectationMet(
                             ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                            ExpectationDetails.of('containAtLeastOneItemThat', outcome.expectation),
                             outcome.expected,
-                            items
+                            items,
                         );
                     }
                 }
 
-                return new ExpectationNotMet(ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation), outcome.expected, items);
+                return new ExpectationNotMet(
+                    ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                    ExpectationDetails.of('containAtLeastOneItemThat', outcome.expectation),
+                    outcome.expected,
+                    items,
+                );
             }
         );
     }