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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/assertions",
-  "version": "3.0.0-rc.4",
+  "version": "3.0.0-rc.41",
   "description": "Screenplay-style assertion library",
   "author": {
     "name": "Jan Molak",
@@ -26,58 +26,34 @@
     "testing"
   ],
   "scripts": {
-    "clean": "rimraf .nyc_output lib target",
-    "lint": "eslint --ext ts --config ../../.eslintrc.yml .",
-    "lint:fix": "npm run lint -- --fix",
-    "test": "nyc --report-dir ../../target/coverage/assertions mocha --config ../../.mocharc.yml 'spec/**/*.spec.*'",
-    "compile": "tsc --project tsconfig.json",
-    "site": "esdoc -c .esdoc.js"
+    "clean": "rimraf '../../target/coverage/assertions'",
+    "test": "nyc mocha --config ../../.mocharc.yml 'spec/**/*.spec.*'",
+    "compile": "rimraf lib && tsc --project tsconfig.build.json"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/serenity-js/serenity-js.git"
+    "url": "https://github.com/serenity-js/serenity-js.git",
+    "directory": "packages/assertions"
   },
   "bugs": {
     "url": "https://github.com/serenity-js/serenity-js/issues"
   },
   "engines": {
-    "node": "^14 || ^16",
+    "node": "^14 || ^16 || ^18",
     "npm": "^6 || ^7 || ^8"
   },
   "dependencies": {
-    "@serenity-js/core": "3.0.0-rc.4",
-    "tiny-types": "^1.17.0"
+    "@serenity-js/core": "3.0.0-rc.41",
+    "tiny-types": "^1.19.0"
   },
   "devDependencies": {
-    "@documentation/esdoc-template": "3.0.0",
     "@integration/testing-tools": "3.0.0",
-    "@types/chai": "^4.3.0",
-    "@types/mocha": "^9.0.0",
-    "mocha": "^9.1.3",
-    "ts-node": "^10.4.0",
-    "typescript": "^4.5.2"
-  },
-  "nyc": {
-    "include": [
-      "src/**/*.ts"
-    ],
-    "exclude": [
-      "src/**/*.d.ts",
-      "lib",
-      "node_modules",
-      "spec"
-    ],
-    "extension": [
-      ".ts"
-    ],
-    "require": [
-      "ts-node/register"
-    ],
-    "reporter": [
-      "json"
-    ],
-    "cache": true,
-    "all": true
-  },
-  "gitHead": "126a1cad42bcb1416ca68e62f54bf0d3eb3ea157"
+    "@types/chai": "^4.3.4",
+    "@types/mocha": "^10.0.1",
+    "mocha": "^10.2.0",
+    "nyc": "15.1.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.4"
+  },
+  "gitHead": "e74f8f4989f18fe37edde3f8500b2084289d385b"
 }

package/src/Ensure.ts

@@ -1,202 +1,144 @@
 import {
+    Activity,
     Answerable,
     AnswersQuestions,
     AssertionError,
     CollectsArtifacts,
+    d,
     Expectation,
     ExpectationMet,
     ExpectationNotMet,
-    ExpectationOutcome,
+    f,
     Interaction,
     LogicError,
+    RaiseErrors,
     RuntimeError,
     UsesAbilities,
 } from '@serenity-js/core';
-import { formatted } 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';
+import { FileSystemLocation } from '@serenity-js/core/lib/io';
 
 /**
- * @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(
+    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
      */
-    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 }`);
-                    }),
-            ),
-        );
-    }
+        if (outcome instanceof ExpectationNotMet) {
+            const actualDescription = d`${ this.actual }`;
+            const message = `Expected ${ actualDescription } to ${ outcome.message }`;
 
-    /**
-     * @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 RaiseErrors.as(actor).create(AssertionError, {
+                message,
+                expectation: outcome.expectation,
+                diff: { expected: outcome.expected, actual: outcome.actual },
+                location: this.instantiationLocation(),
+            });
+        }
+
+        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);
-    }
-
-    /**
-     * @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 ${ formatted`${ this.actual }` } to ${ outcome.message }`,
-            outcome.expected,
-            outcome.actual,
-        );
-    }
+        const location = this.instantiationLocation();
 
-    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/expectations/and.ts

@@ -1,29 +1,54 @@
-import { AnswersQuestions, Expectation, ExpectationNotMet, ExpectationOutcome } 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<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 '));
-    }
+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(
+            'and',
+            description,
+            async (actor: AnswersQuestions, actual: Answerable<Actual>) => {
+                let outcome: ExpectationOutcome;
+
+                for (const expectation of expectations) {
+                    outcome = await actor.answer(expectation.isMetFor(actual))
 
-    answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<any, Actual>> {
+                    if (outcome instanceof ExpectationNotMet) {
+                        return new ExpectationNotMet(description, outcome.expectation, outcome.expected, outcome.actual);
+                    }
+                }
 
-        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),
-            );
+                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, 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,26 +1,80 @@
-import { AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, d, Expectation, ExpectationDetails, ExpectationMet, ExpectationNotMet, ExpectationOutcome, Unanswered } 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(
+            'containAtLeastOneItemThat',
+            ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+            async (actor: AnswersQuestions, actual: Answerable<Item[]>) => {
+
+                const items: Item[] = await actor.answer(actual);
+
+                if (! items || items.length === 0) {
+                    const unanswered = new Unanswered();
+                    return new ExpectationNotMet(
+                        ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                        ExpectationDetails.of('containAtLeastOneItemThat', unanswered),
+                        unanswered,
+                        items,
                     );
+                }
+
+                let outcome: ExpectationOutcome;
+
+                for (const item of items) {
+
+                    outcome = await actor.answer(expectation.isMetFor(item))
+
+                    if (outcome instanceof ExpectationMet) {
+                        return new ExpectationMet(
+                            ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                            ExpectationDetails.of('containAtLeastOneItemThat', outcome.expectation),
+                            outcome.expected,
+                            items,
+                        );
+                    }
+                }
+
+                return new ExpectationNotMet(
+                    ContainAtLeastOneItemThatMeetsExpectation.descriptionFor(expectation),
+                    ExpectationDetails.of('containAtLeastOneItemThat', outcome.expectation),
+                    outcome.expected,
+                    items,
+                );
+            }
+        );
     }
 }