@serenity-js/assertions 3.0.0-rc.4 → 3.0.0-rc.40

package/src/Ensure.ts

@@ -1,173 +1,153 @@
 import {
+    Activity,
     Answerable,
     AnswersQuestions,
     AssertionError,
     CollectsArtifacts,
+    d,
     Expectation,
     ExpectationMet,
     ExpectationNotMet,
     ExpectationOutcome,
+    f,
     Interaction,
     LogicError,
     RuntimeError,
     UsesAbilities,
 } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { FileSystemLocation } from '@serenity-js/core/lib/io';
 import { inspected } from '@serenity-js/core/lib/io/inspected';
 import { Artifact, AssertionReport, Name } from '@serenity-js/core/lib/model';
 import { match } from 'tiny-types';
 
 /**
- * @desc
- *  Used to perform verification of the system under test.
+ * 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}.
  *
- *  Resolves any `Answerable` describing the actual
- *  state and ensures that its value meets the {@link @serenity-js/core/lib/screenplay/questions~Expectation}s provided.
+ * Use `Ensure` to verify the state of the system under test.
  *
- * @example <caption>Usage with static values</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * ## Basic usage with static values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- *  const actor = actorCalled('Erica');
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', equals('Hello world!'))
+ * )
+ * ```
  *
- *  actor.attemptsTo(
- *    Ensure.that('Hello world!', equals('Hello world!'))
- *  );
+ * ## Composing expectations with `and`
  *
- * @example <caption>Composing expectations with `and`</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions';
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
  *
- *  const actor = actorCalled('Erica');
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
+ * )
+ * ```
  *
- *  actor.attemptsTo(
- *    Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
- *  );
+ * ## Overriding the type of Error thrown upon assertion failure
  *
- * @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';
+ * ```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'
  *
- *  const actor = actorCalled('Erica')
- *      .whoCan(CallAnApi.at('https://example.com'));
+ * 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!')
+ *   )
+ * ```
  *
- *  actor.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 Interactions
  */
 export class Ensure<Actual> extends Interaction {
+
     /**
+     * @param {Answerable<Actual_Type>} actual
+     *  An {@apilink Answerable} describing the actual state of the system.
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<T>} actual
-     * @param {@serenity-js/core/lib/screenplay/questions~Expectation<any, A>} expectation
+     * @param {Expectation<Actual_Type>} expectation
+     *  An {@apilink Expectation} you expect the `actual` value to meet
      *
-     * @returns {Ensure<A>}
+     * @returns {Ensure<Actual_Type>}
      */
-    static that<A>(actual: Answerable<A>, expectation: Expectation<any, 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
+     * @param actual
+     * @param expectation
+     * @param location
      */
-    constructor(
+    protected 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
      */
-    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
-        return Promise.all([
-            actor.answer(this.actual),
-            actor.answer(this.expectation),
-        ]).then(([ actual, expectation ]) =>
-            expectation(actual).then(outcome =>
-                match<ExpectationOutcome<unknown, Actual>, void>(outcome)
-                    .when(ExpectationNotMet, o => {
-                        actor.collect(this.artifactFrom(o.expected, o.actual), new Name(`Assertion Report`));
+    async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
+        const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
 
-                        throw this.errorForOutcome(o);
-                    })
-                    .when(ExpectationMet, _ => void 0)
-                    .else(o => {
-                        throw new LogicError(formatted `An Expectation should return an instance of an ExpectationOutcome, not ${ o }`);
-                    }),
-            ),
-        );
-    }
+        return match<ExpectationOutcome<unknown, Actual>, void>(outcome)
+            .when(ExpectationNotMet, o => {
+                actor.collect(this.artifactFrom(o.expected, o.actual), new Name(`Assertion Report`));
 
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor ensures that ${ this.actual } does ${ this.expectation }`;
+                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 }`);
+            });
     }
 
     /**
-     * @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);
     }
 
     /**
-     * @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
+     * Maps an {@apilink ExpectationOutcome} to appropriate {@apilink RuntimeError}.
      */
     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}
+     * Maps an {@apilink Outcome} to {@apilink AssertionError}.
      *
-     * @protected
+     * @param outcome
      */
     protected asAssertionError(outcome: ExpectationOutcome<any, Actual>): AssertionError {
+        const actualDescription = d`${ this.actual }`;
+        const inspectedActual = inspected(outcome.actual, { inline: true, markQuestions: false });
+        const message = actualDescription === inspectedActual
+            ? `Expected ${ actualDescription } to ${ outcome.message }`
+            : `Expected ${ actualDescription } to ${ outcome.message } but got ${ inspectedActual }`;
+
         return new AssertionError(
-            `Expected ${ formatted`${ this.actual }` } to ${ outcome.message }`,
+            message,
             outcome.expected,
             outcome.actual,
         );
@@ -191,7 +171,7 @@ class EnsureOrFailWithCustomError<Actual> extends Ensure<Actual> {
         private readonly typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError,
         private readonly message?: string,
     ) {
-        super(actual, expectation);
+        super(actual, expectation, Activity.callerLocation(6));
     }
 
     protected errorForOutcome(outcome: ExpectationOutcome<any, Actual>): RuntimeError {

package/src/expectations/and.ts

@@ -1,29 +1,50 @@
-import { AnswersQuestions, Expectation, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, Expectation, ExpectationNotMet } from '@serenity-js/core';
 import { match } from 'tiny-types';
 
-export function and<Actual>(...expectations: Array<Expectation<any, Actual>>): Expectation<any, 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);
 }
 
 /**
  * @package
  */
-class And<Actual> extends Expectation<any, Actual> {
-    constructor(private readonly expectations: Array<Expectation<any, Actual>>) {
-        super(expectations.map(assertion => assertion.toString()).join(' and '));
-    }
-
-    answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<any, Actual>> {
+class And<Actual> extends Expectation<Actual> {
+    private static readonly Separator = ' and ';
 
-        return (actual: any) =>
-            this.expectations.reduce(
-                (previous, current) =>
-                    previous.then(outcome =>
-                        match(outcome)
-                            .when(ExpectationNotMet, o => o)
-                            .else(_ => current.answeredBy(actor)(actual)),
-                    ),
-                Promise.resolve(void 0),
-            );
+    constructor(private readonly expectations: Array<Expectation<Actual>>) {
+        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),
+                );
+            }
+        );
     }
 }

package/src/expectations/contain.ts

@@ -1,7 +1,31 @@
 import { Answerable, Expectation } from '@serenity-js/core';
 import { equal } from 'tiny-types/lib/objects';
 
-export function contain<Item>(expected: Answerable<Item>): Expectation<Item, Item[]> {
+/**
+ * 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 function contain<Item>(expected: Answerable<Item>): Expectation<Item[]> {
     return Expectation.thatActualShould<Item, Item[]>('contain', expected)
-        .soThat((actualValue, expectedValue) => !! ~ actualValue.findIndex(av => equal(av, expectedValue)));
+        .soThat((actualValue, expectedValue) => actualValue.some(item => equal(item, expectedValue)));
 }

package/src/expectations/containAtLeastOneItemThat.ts

@@ -1,26 +1,71 @@
-import { AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, d, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
 
-export function containAtLeastOneItemThat<Actual>(expectation: Expectation<any, Actual>): Expectation<any, 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<Expected, Actual> extends Expectation<Expected, Actual[]> {
-    constructor(private readonly expectation: Expectation<Expected, Actual>) {
-        super(formatted `contain at least one item that does ${ expectation }`);
+class ContainAtLeastOneItemThatMeetsExpectation<Item> extends Expectation<Item[]> {
+
+    private static descriptionFor(expectation: Expectation<any>) {
+        return d`contain at least one item that does ${ expectation }`;
     }
 
-    answeredBy(actor: AnswersQuestions): (actual: Actual[]) => Promise<ExpectationOutcome<Expected, Actual[]>> {
-        return (actual: Actual[]) =>
-            actual.length === 0
-                ? Promise.resolve(new ExpectationNotMet(this.toString(), undefined, actual))
-                : Promise.all(actual.map(item => this.expectation.answeredBy(actor)(item)))
-                    .then(results => results.some(result => result instanceof ExpectationMet)
-                        ? new ExpectationMet(this.toString(), results[0].expected, actual)
-                        : new ExpectationNotMet(this.toString(), results[0].expected, actual),
+    constructor(private readonly expectation: Expectation<Item>) {
+        super(
+            ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+            async (actor: AnswersQuestions, actual: Answerable<Item[]>) => {
+
+                const items: Item[] = await actor.answer(actual);
+
+                if (! items || items.length === 0) {
+                    return new ExpectationNotMet(
+                        ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                        undefined,
+                        items,
                     );
+                }
+
+                let outcome: ExpectationOutcome<unknown, Item>;
+
+                for (const item of items) {
+
+                    outcome = await actor.answer(expectation.isMetFor(item))
+
+                    if (outcome instanceof ExpectationMet) {
+                        return new ExpectationMet(
+                            ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                            outcome.expected,
+                            items
+                        );
+                    }
+                }
+
+                return new ExpectationNotMet(ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation), outcome.expected, items);
+            }
+        );
     }
 }

package/src/expectations/containItemsWhereEachItem.ts

@@ -1,26 +1,71 @@
-import { AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, d, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
 
-export function containItemsWhereEachItem<Actual>(expectation: Expectation<any, Actual>): Expectation<any, Actual[]> {
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when all the items of the actual array of `Item[]`
+ * meet the `expectation`.
+ *
+ * ## Ensuring that all the items in an array meet the expectation
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, containItemsWhereEachItem, endsWith } from '@serenity-js/assertions'
+ *
+ * const items = [ 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday' ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(items, containItemsWhereEachItem(endsWith('day'))),
+ * )
+ * ```
+ *
+ * @param expectation
+ *
+ * @group Expectations
+ */
+export function containItemsWhereEachItem<Actual>(expectation: Expectation<Actual>): Expectation<Actual[]> {
     return new ContainItemsWhereEachItemMeetsExpectation(expectation);
 }
 
 /**
  * @package
  */
-class ContainItemsWhereEachItemMeetsExpectation<Expected, Actual> extends Expectation<Expected, Actual[]> {
-    constructor(private readonly expectation: Expectation<Expected, Actual>) {
-        super(formatted `contain items where each item does ${ expectation }`);
+class ContainItemsWhereEachItemMeetsExpectation<Actual> extends Expectation<Actual[]> {
+
+    private static descriptionFor(expectation: Expectation<any>) {
+        return d`contain items where each item does ${ expectation }`;
     }
 
-    answeredBy(actor: AnswersQuestions): (actual: Actual[]) => Promise<ExpectationOutcome<Expected, Actual[]>> {
-        return (actual: Actual[]) =>
-            actual.length === 0
-                ? Promise.resolve(new ExpectationNotMet(this.toString(), undefined, actual))
-                : Promise.all(actual.map(item => this.expectation.answeredBy(actor)(item)))
-                    .then(results => results.every(result => result instanceof ExpectationMet)
-                        ? new ExpectationMet(this.toString(), results[0].expected, actual)
-                        : new ExpectationNotMet(this.toString(), results[0].expected, actual),
+    constructor(private readonly expectation: Expectation<Actual>) {
+        super(
+            ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
+            async (actor: AnswersQuestions, actual: Answerable<Actual[]>) => {
+
+                const items: Actual[] = await actor.answer(actual);
+
+                if (! items || items.length === 0) {
+                    return new ExpectationNotMet(
+                        ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
+                        undefined,
+                        items,
                     );
+                }
+
+                let outcome: ExpectationOutcome<unknown, Actual>;
+
+                for (const item of items) {
+
+                    outcome = await actor.answer(expectation.isMetFor(item))
+
+                    if (outcome instanceof ExpectationNotMet) {
+                        return new ExpectationNotMet(
+                            ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation),
+                            outcome.expected,
+                            items
+                        );
+                    }
+                }
+
+                return new ExpectationMet(ContainItemsWhereEachItemMeetsExpectation.descriptionFor(expectation), outcome.expected, items);
+            }
+        );
     }
 }

package/src/expectations/endsWith.ts

@@ -1,5 +1,24 @@
 import { Answerable, Expectation } from '@serenity-js/core';
 
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `string` value
+ * ends with the resolved value of `expected`.
+ *
+ * ## Ensuring that a given string ends with an expected substring
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', endsWith('!')),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
 export function endsWith(expected: Answerable<string>): Expectation<string> {
     return Expectation.thatActualShould<string, string>('end with', expected)
         .soThat((actualValue, expectedValue) => actualValue.endsWith(expectedValue));

package/src/expectations/equals.ts

@@ -1,6 +1,31 @@
 import { Answerable, Expectation } from '@serenity-js/core';
 import { equal } from 'tiny-types/lib/objects';
 
+/**
+ * Produces an {@apilink Expectation|expectation} that is met when the actual value
+ * is equal to the resolved value of `expectedValue`.
+ *
+ * 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 actual value equals expected value
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * const actual   = { name: 'apples' }
+ * const expected = { name: 'apples' }
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(actual, equals(expected)),
+ * )
+ * ```
+ *
+ * @param expectedValue
+ *
+ * @group Expectations
+ */
 export function equals<Expected>(expectedValue: Answerable<Expected>): Expectation<Expected> {
     return Expectation.thatActualShould<Expected, Expected>('equal', expectedValue)
         .soThat((actual, expected) => equal(actual, expected));

package/src/expectations/includes.ts

@@ -1,5 +1,24 @@
 import { Answerable, Expectation } from '@serenity-js/core';
 
+/**
+ * Creates an {@apilink Expectation|expectation} that is met when the actual `string` value
+ * includes a substring of `expected`.
+ *
+ * ## Ensuring that a given string includes the expected substring
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, includes } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', includes('World')),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
 export function includes(expected: Answerable<string>): Expectation<string> {
     return Expectation.thatActualShould<string, string>('include', expected)
         .soThat((actualValue, expectedValue) => actualValue.includes(expectedValue));

package/src/expectations/index.ts

@@ -7,9 +7,11 @@ export * from './equals';
 export * from './includes';
 export * from './isAfter';
 export * from './isBefore';
+export * from './isCloseTo';
 export * from './isFalse';
 export * from './isGreaterThan';
 export * from './isLessThan';
+export * from './isPresent';
 export * from './isTrue';
 export * from './matches';
 export * from './not';