@serenity-js/core 2.33.1 → 3.0.0-rc.11

package/src/screenplay/Question.ts

@@ -1,6 +1,8 @@
-import { isMappable, Mappable } from '../io/collections';
+import { f } from '../io';
 import { AnswersQuestions, UsesAbilities } from './actor';
-import { AnswerMappingFunction } from './questions/mappings';
+import { Answerable } from './Answerable';
+import { Interaction } from './Interaction';
+import { Optional } from './Optional';
 
 /**
  * @desc
@@ -52,16 +54,6 @@ import { AnswerMappingFunction } from './questions/mappings';
  * @abstract
  */
 export abstract class Question<T> {
-
-    /**
-     * @param {string} subject
-     *  The subject of this question
-     *
-     * @protected
-     */
-    protected constructor(protected subject: string) {
-    }
-
     /**
      * @desc
      *  Factory method that simplifies the process of defining custom questions.
@@ -77,8 +69,8 @@ export abstract class Question<T> {
      *
      * @returns {Question<R>}
      */
-    static about<R>(description: string, body: (actor: AnswersQuestions & UsesAbilities) => R): Question<R> {
-        return new AnonymousQuestion<R>(description, body);
+    static about<R>(description: string, body: (actor: AnswersQuestions & UsesAbilities) => Promise<R> | R): QuestionAdapter<Awaited<R>> {
+        return Question.createAdapter(new QuestionStatement(description, body));
     }
 
     /**
@@ -96,15 +88,91 @@ export abstract class Question<T> {
         return !! maybeQuestion && !! (maybeQuestion as any).answeredBy;
     }
 
+    protected static createAdapter<AT>(statement: Question<AT>): QuestionAdapter<Awaited<AT>> {
+        return new Proxy<() => Question<AT>, QuestionStatement<AT>>(() => statement, {
+
+            get(currentStatement: () => Question<AT>, key: string | symbol, receiver: any) {
+                const target = currentStatement();
+
+                if (key === Symbol.toPrimitive) {
+                    return (_hint: 'number' | 'string' | 'default') => {
+                        return target.toString();
+                    }
+                }
+
+                if (key in target) {
+                    return Reflect.get(target, key)
+                }
+
+                if (key === 'then') {
+                    return;
+                }
+
+                const originalSubject = f`${ target }`;
+
+                const fieldDescription = (typeof key === 'number' || /^\d+$/.test(String(key)))
+                    ? `[${ String(key) }]`  // array index
+                    : `.${ String(key) }`;  // field/method name
+
+                return Question.about(`${ originalSubject }${ fieldDescription }`, async (actor: AnswersQuestions & UsesAbilities) => {
+                    const answer = await actor.answer(target as Answerable<AT>);
+
+                    if (! isDefined(answer)) {
+                        return undefined;       // eslint-disable-line unicorn/no-useless-undefined
+                    }
+
+                    const field = answer[key];
+
+                    return typeof field === 'function'
+                        ? field.bind(answer)
+                        : field;
+                })
+            },
+
+            set(currentStatement: () => Question<AT>, key: string | symbol, value: any, receiver: any): boolean {
+                const target = currentStatement();
+
+                return Reflect.set(target, key, value);
+            },
+
+            apply(currentStatement: () => Question<AT>, _thisArgument: any, parameters: unknown[]): QuestionAdapter<AT> {
+
+                const target = currentStatement();
+
+                const parameterDescriptions = [
+                    '(',
+                    parameters.map(p => f`${ p }`).join(', '),
+                    ')'
+                ].join('');
+
+                return Question.about(target.toString() + parameterDescriptions, async actor => {
+                    const params = [] as any;
+                    for (const parameter of parameters) {
+                        const answered = await actor.answer(parameter);
+                        params.push(answered);
+                    }
+
+                    const field = await actor.answer(target);
+
+                    return typeof field === 'function'
+                        ? field(...params)
+                        : field;
+                });
+            },
+
+            getPrototypeOf(currentStatement: () => Question<AT>): object | null {
+                return Reflect.getPrototypeOf(currentStatement());
+            },
+        }) as any;
+    }
+
     /**
      * @desc
      *  Describes the subject of this {@link Question}.
      *
      * @returns {string}
      */
-    toString(): string {
-        return this.subject;
-    }
+    abstract toString(): string;
 
     /**
      * @desc
@@ -113,135 +181,149 @@ export abstract class Question<T> {
      * @param {string} subject
      * @returns {Question<T>}
      */
-    describedAs(subject: string): this {
-        this.subject = subject;
+    abstract describedAs(subject: string): this;
 
-        return this;
+    /**
+     * @abstract
+     */
+    abstract answeredBy(actor: AnswersQuestions & UsesAbilities): T;
+
+    public as<O>(mapping: (answer: Awaited<T>) => Promise<O> | O): QuestionAdapter<O> {
+        return Question.about<O>(f`${ this }.as(${ mapping })`, async actor => {
+            const answer = (await actor.answer(this)) as Awaited<T>;
+            return mapping(answer);
+        });
+    }
+}
+
+declare global  {
+    interface ProxyConstructor {
+        new <Source_Type extends object, Target_Type extends object>(target: Source_Type, handler: ProxyHandler<Source_Type>): Target_Type;
+    }
+}
+
+/* eslint-disable @typescript-eslint/indent */
+export type ProxiedAnswer<Original_Type> = {
+    [Field in keyof Omit<Original_Type, keyof QuestionStatement<Original_Type>>]:
+        // is it a method?
+        Original_Type[Field] extends (...args: infer OriginalParameters) => infer OriginalMethodResult
+            // make the method signature asynchronous, accepting Answerables and returning a Promise
+            ? (...args: { [P in keyof OriginalParameters]: Answerable<OriginalParameters[P]> }) =>
+                { isPresent(): Question<Promise<boolean>> } & QuestionAdapter<Awaited<OriginalMethodResult>>
+            // is it an object? wrap each field
+            : { isPresent(): Question<Promise<boolean>> } & QuestionAdapter<Awaited<Original_Type[Field]>>
+};
+/* eslint-enable @typescript-eslint/indent */
+
+export type QuestionAdapter<Original_Type> =
+    Question<Promise<Original_Type>> &
+    Interaction &
+    Optional &
+    ProxiedAnswer<Original_Type>;
+
+class QuestionStatement<Answer_Type> extends Interaction implements Question<Promise<Answer_Type>>, Optional {
+
+    constructor(
+        private subject: string,
+        private readonly body: (actor: AnswersQuestions & UsesAbilities, ...Parameters) => Promise<Answer_Type> | Answer_Type,
+    ) {
+        super();
     }
 
     /**
      * @desc
-     *  Creates a new {@link Question}, which value is a result of applying the `mapping`
-     *  function to the value of this {@link Question}.
-     *
-     * @example <caption>Mapping a Question<Promise<string>> to Question<Promise<number>></caption>
-     *  import { Question, replace, toNumber } from '@serenity-js/core';
-     *
-     *  Question.about('the price of some item', actor => '$3.99')
-     *      .map(replace('$', ''))
-     *      .map(toNumber)
-     *
-     *  // => Question<Promise<number>>
-     *  //      3.99
-     *
-     * @example <caption>Mapping all items of Question<string[]> to Question<Promise<number>></caption>
-     *  import { Question, trim } from '@serenity-js/core';
-     *
-     *  Question.about('things to do', actor => [ ' walk the dog  ', '  read a book  ' ])
-     *      .map(trim())
-     *
-     *  // => Question<Promise<string[]>>
-     *  //      [ 'walk the dog', 'read a book' ]
-     *
-     * @example <caption>Using a custom mapping function</caption>
-     *  import { Question } from '@serenity-js/core';
+     *  Returns a Question that resolves to `true` if resolving the {@link QuestionStatement}
+     *  returns a value other than `null` or `undefined` and doesn't throw errors.
      *
-     *  Question.about('normalised percentages', actor => [ 0.1, 0.3, 0.6 ])
-     *      .map((actor: AnswersQuestions) => (value: number) => value * 100)
-     *
-     *  // => Question<Promise<number[]>>
-     *  //      [ 10, 30, 60 ]
-     *
-     * @example <caption>Extracting values from LastResponse.body()</caption>
-     *  import { Question } from '@serenity-js/core';
-     *  import { LastResponse } from '@serenity-js/rest';
-     *
-     *  interface UserDetails {
-     *      id: number;
-     *      name: string;
-     *  }
-     *
-     *  LastResponse.body<UserDetails>().map(actor => details => details.id)
-     *
-     *  // => Question<number>
-     *
-     * @param {function(value: A, index?: number): Promise<O> | O} mapping
-     *  A mapping function that receives a value of type `<A>`, which is either:
-     *  - an answer to the original question, if the question is defined as `Question<Promise<A>>` or `Question<A>`
-     *  - or, if the question is defined as `Question<Promise<Mappable<A>>`, `Question<Mappable<A>>` - each item of the {@link Mappable} collection,
-     *
-     * @returns {Question<Promise<Mapped>>}
-     *  A new Question which value is a result of applying the `mapping` function
-     *  to the value of the current question, so that:
-     *  - if the answer to the current question is a `Mappable<A>`, the result becomes `Question<Promise<O[]>>`
-     *  - if the answer is a value `<A>` or `Promise<A>`, the result becomes `Question<Promise<O>>`
-     *
-     * @see {@link AnswerMappingFunction}
-     * @see {@link Mappable}
+     * @returns {Question<Promise<boolean>>}
      */
-    map<O>(mapping: AnswerMappingFunction<AnswerOrItemOfMappableCollection<T>, O>): Question<Promise<Mapped<T, O>>> {
-        return Question.about(this.subject, actor =>
-            actor.answer(this).then(value =>
-                (isMappable(value)
-                    ? Promise.all(((value).map(mapping(actor)) as Array<PromiseLike<O> | O>))
-                    : mapping(actor)(value as AnswerOrItemOfMappableCollection<T>)
-                ) as Promise<Mapped<T, O>>
-            )
-        ) as Question<Promise<Mapped<T, O>>>;
+    isPresent(): Question<Promise<boolean>> {
+        return new IsPresent(f`${ this }.isPresent()`, this.body);
     }
 
-    /**
-     * @abstract
-     */
-    abstract answeredBy(actor: AnswersQuestions & UsesAbilities): T;
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Answer_Type> {
+        const result = await this.body(actor);
+
+        return isDefined(result)
+            ? result
+            : undefined;
+    }
+
+    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
+        await this.body(actor);
+    }
+
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
+
+    as<O>(mapping: (answer: Awaited<Answer_Type>) => (Promise<O> | O)): QuestionAdapter<O>{
+        return Question.about<O>(f`${ this }.as(${ mapping })`, async actor => {
+            const answer = await actor.answer(this);
+
+            if (! isDefined(answer)) {
+                return undefined;   // eslint-disable-line unicorn/no-useless-undefined
+            }
+
+            return mapping(answer);
+        });
+    }
 }
 
 /**
  * @package
  */
-type AnswerOrItemOfMappableCollection<V> =
-    V extends PromiseLike<infer PromisedValue>
-        ? PromisedValue extends Mappable<infer Item>
-            ? Item
-            : PromisedValue
-        : V extends Mappable<infer Item>
-            ? Item
-            : V;
+class IsPresent<T> extends Question<Promise<boolean>> {
 
-/**
- * @package
- */
-type Mapped<T, O> =
-    T extends PromiseLike<infer PromisedValue>
-        ? PromisedValue extends Mappable<infer Item>        // eslint-disable-line @typescript-eslint/no-unused-vars
-            ? O[]
-            : O
-        : T extends Mappable<infer Item>                    // eslint-disable-line @typescript-eslint/no-unused-vars
-            ? O[]
-            : O
+    constructor(
+        private subject: string,
+        private readonly body: (actor: AnswersQuestions & UsesAbilities) => T,
+    ) {
+        super();
+    }
 
-/**
- * @package
- */
-class AnonymousQuestion<T> extends Question<T> {
-    constructor(private description: string, private body: (actor: AnswersQuestions & UsesAbilities) => T) {
-        super(description);
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<boolean> {
+        try  {
+            const answer = await this.body(actor);
+
+            if (answer === undefined || answer === null) {
+                return false;
+            }
+
+            if (this.isOptional(answer)) {
+                return await actor.answer(answer.isPresent());
+            }
+
+            return true;
+        } catch {
+            return false;
+        }
     }
 
-    answeredBy(actor: AnswersQuestions & UsesAbilities) {
-        return this.body(actor);
+    private isOptional(maybeOptional: any): maybeOptional is Optional {
+        return typeof maybeOptional === 'object'
+            && Reflect.has(maybeOptional, 'isPresent');
     }
 
-    /**
-     * Changes the description of this question's subject
-     * and produces a new instance without mutating the original one.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
     describedAs(subject: string): this {
         this.subject = subject;
-
         return this;
     }
+
+    toString(): string {
+        return this.subject;
+    }
+}
+
+/**
+ * @package
+ */
+function isDefined<T>(value: T): boolean {
+    return value !== undefined
+        && value !== null;
 }

package/src/screenplay/actor/Actor.ts

@@ -114,11 +114,11 @@ export class Actor implements
      */
     answer<T>(answerable: Answerable<T>): Promise<T> {
         function isAPromise<V>(v: Answerable<V>): v is Promise<V> {
-            return !!(v as any).then;
+            return Object.prototype.hasOwnProperty.call(v, 'then');
         }
 
         function isDefined<V>(v: Answerable<V>) {
-            return ! (answerable === undefined || answerable === null);
+            return ! (v === undefined || v === null);
         }
 
         if (isDefined(answerable) && isAPromise(answerable)) {

package/src/screenplay/index.ts

@@ -6,7 +6,7 @@ export * from './actor';
 export * from './Answerable';
 export * from './Interaction';
 export * from './interactions';
+export * from './Optional';
 export * from './Question';
 export * from './questions';
 export * from './Task';
-export * from './tasks';

package/src/screenplay/interactions/index.ts

@@ -1,3 +1,2 @@
 export * from './Log';
-export * from './See';
 export * from './TakeNote';

package/src/screenplay/questions/Check.ts

@@ -1,4 +1,4 @@
-import { formatted } from '../../io';
+import { d } from '../../io';
 import { Activity } from '../Activity';
 import { AnswersQuestions, PerformsActivities } from '../actor';
 import { Answerable } from '../Answerable';
@@ -44,7 +44,7 @@ import { ExpectationMet } from './expectations';
  */
 export class Check<Actual> extends Task {
     // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-    static whether<A>(actual: Answerable<A>, expectation: Expectation<any, A>) {
+    static whether<A>(actual: Answerable<A>, expectation: Expectation<A>) {
         return {
             andIfSo: (...activities: Activity[]) => new Check(actual, expectation, activities),
         };
@@ -59,7 +59,7 @@ export class Check<Actual> extends Task {
      */
     constructor(
         private readonly actual: Answerable<Actual>,
-        private readonly expectation: Expectation<any, Actual>,
+        private readonly expectation: Expectation<Actual>,
         private readonly activities: Activity[],
         private readonly alternativeActivities: Activity[] = [],
     ) {
@@ -86,17 +86,12 @@ export class Check<Actual> extends Task {
      * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
      * @see {@link @serenity-js/core/lib/screenplay/actor~PerformsActivities}
      */
-    performAs(actor: AnswersQuestions & PerformsActivities): PromiseLike<void> {
-        return Promise.all([
-            actor.answer(this.actual),
-            actor.answer(this.expectation),
-        ]).then(([actual, expectation]) =>
-            expectation(actual).then(outcome =>
-                outcome instanceof ExpectationMet
-                    ? actor.attemptsTo(...this.activities)
-                    : actor.attemptsTo(...this.alternativeActivities),
-            ),
-        );
+    async performAs(actor: AnswersQuestions & PerformsActivities): Promise<void> {
+        const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
+
+        return outcome instanceof ExpectationMet
+            ? actor.attemptsTo(...this.activities)
+            : actor.attemptsTo(...this.alternativeActivities);
     }
 
     /**
@@ -106,6 +101,6 @@ export class Check<Actual> extends Task {
      * @returns {string}
      */
     toString(): string {
-        return formatted `#actor checks whether ${ this.actual } does ${ this.expectation }`;
+        return d`#actor checks whether ${ this.actual } does ${ this.expectation }`;
     }
 }

package/src/screenplay/questions/Expectation.ts

@@ -1,13 +1,14 @@
-import { formatted } from '../../io';
-import { Answerable, AnswersQuestions, Question } from '../';
-import { ExpectationMet, ExpectationNotMet, ExpectationOutcome  } from './expectations';
+import { d } from '../../io';
+import { Answerable, AnswersQuestions, ExpectationMet, ExpectationNotMet, Question, QuestionAdapter } from '../';
+import { ExpectationOutcome } from './expectations';
 
 /**
  * @public
  *
- * @typedef {function(actual: A, expected: E) => boolean} Predicate<A,E>
+ * @typedef {function(actual: Answerable<Actual>) => Promise<ExpectationOutcome<Expected, Actual>> | ExpectationOutcome<unknown, Actual>} Predicate<Actual>
  */
-export type Predicate<A, E> = (actual: A, expected: E) => boolean;
+export type Predicate<Actual> = (actor: AnswersQuestions, actual: Answerable<Actual>) =>
+    Promise<ExpectationOutcome<unknown, Actual>> | ExpectationOutcome<unknown, Actual>;     // eslint-disable-line @typescript-eslint/indent
 
 /**
  * @desc
@@ -16,9 +17,7 @@ export type Predicate<A, E> = (actual: A, expected: E) => boolean;
  *
  * @extends {Question}
  */
-export abstract class Expectation<Expected, Actual = Expected>
-    extends Question<(actual: Actual) => Promise<ExpectationOutcome<Expected, Actual>>>
-{
+export class Expectation<Actual> {
 
     /**
      * @desc
@@ -40,14 +39,28 @@ export abstract class Expectation<Expected, Actual = Expected>
      * @param {string} relationshipName
      * @param {@serenity-js/core/lib/screenplay~Answerable<E>} expectedValue
      *
-     * @returns {"soThat": function(predicate: Predicate<A,E>): Expectation<E, A>}
+     * @returns {"soThat": function(predicate: Predicate<Expected, Actual>): Expectation<Expected, Actual>}
      */
-    static thatActualShould<E, A>(relationshipName: string, expectedValue: Answerable<E>): {
-        soThat: (predicate: Predicate<A, E>) => Expectation<E, A>,
+    static thatActualShould<E, A>(relationshipName: string, expectedValue?: Answerable<E>): {
+        soThat: (simplifiedPredicate: (actualValue: A, expectedValue: E) => Promise<boolean> | boolean) => Expectation<A>,
     } {
         return ({
-            soThat: (predicate: Predicate<A, E>): Expectation<E, A> => {
-                return new DynamicallyGeneratedExpectation<E, A>(relationshipName, predicate, expectedValue);
+            soThat: (simplifiedPredicate: (actualValue: A, expectedValue: E) => Promise<boolean> | boolean): Expectation<A> => {
+                const subject = relationshipName + ' ' + d`${expectedValue}`;
+
+                return new Expectation<A>(
+                    subject,
+                    async (actor: AnswersQuestions, actualValue: Answerable<A>): Promise<ExpectationOutcome<E, A>> => {
+                        const expected = await actor.answer(expectedValue);
+                        const actual   = await actor.answer(actualValue);
+
+                        const result   = await simplifiedPredicate(actual, expected);
+
+                        return result
+                            ? new ExpectationMet(subject, expected, actual)
+                            : new ExpectationNotMet(subject, expected, actual);
+                    }
+                );
             },
         });
     }
@@ -77,60 +90,39 @@ export abstract class Expectation<Expected, Actual = Expected>
      *
      * @returns {"soThat": function(...expectations: Array<Expectation<any, A>>): Expectation<any, A>}
      */
-    static to<A>(relationshipName: string): {
-        soThatActual: (...expectations: Array<Expectation<any, A>>) => Expectation<any, A>,
+    static to<E, A>(relationshipName: string): {
+        soThatActual: (...expectations: Array<Expectation<A>>) => Expectation<A>,
     } {
         return {
-            soThatActual: (expectation: Expectation<any, A>): Expectation<any, A> => {
-                return new ExpectationAlias<A>(relationshipName, expectation);
+            soThatActual: (expectation: Expectation<A>): Expectation<A> => {
+                return new Expectation<A>(
+                    relationshipName,
+                    async (actor: AnswersQuestions, actualValue: Answerable<A>): Promise<ExpectationOutcome<E, A>> => {
+                        const outcome  = await actor.answer(expectation.isMetFor(actualValue));
+
+                        return outcome as ExpectationOutcome<E, A>;
+                    }
+                );
             },
         };
     }
 
-    abstract answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<Expected, Actual>>;
-}
-
-/**
- * @package
- */
-class DynamicallyGeneratedExpectation<Expected, Actual> extends Expectation<Expected, Actual> {
-
-    constructor(
-        private readonly description: string,
-        private readonly predicate: Predicate<Actual, Expected>,
-        private readonly expectedValue: Answerable<Expected>,
+    protected constructor(
+        private subject: string,
+        private readonly predicate: Predicate<Actual>,
     ) {
-        super(`${ description } ${ formatted `${ expectedValue }` }`);
     }
 
-    answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<Expected, Actual>> {
-
-        return (actual: Actual) => actor.answer(this.expectedValue)
-            .then(expected => {
-                return this.predicate(actual, expected)
-                    ? new ExpectationMet(this.toString(), expected, actual)
-                    : new ExpectationNotMet(this.toString(), expected, actual);
-            });
+    isMetFor(actual: Answerable<Actual>): QuestionAdapter<ExpectationOutcome<unknown, Actual>> {
+        return Question.about(this.subject, actor => this.predicate(actor, actual));
     }
-}
-
-/**
- * @package
- */
-class ExpectationAlias<Actual> extends Expectation<any, Actual> {
 
-    constructor(
-        subject: string,
-        private readonly expectation: Expectation<any, Actual>,
-    ) {
-        super(subject);
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
     }
 
-    answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<any, Actual>> {
-
-        return (actual: Actual) =>
-            this.expectation.answeredBy(actor)(actual).then(_ => _ instanceof ExpectationMet
-                ? new ExpectationMet(this.subject, _.expected, _.actual)
-                : new ExpectationNotMet(_.message, _.expected, _.actual));
+    toString(): string {
+        return this.subject;
     }
 }