@serenity-js/core 2.32.2 → 3.0.0-rc.0

package/src/screenplay/Question.ts

@@ -1,6 +1,6 @@
-import { isMappable, Mappable } from '../io/collections';
+import { inspected } from '../io/inspected';
 import { AnswersQuestions, UsesAbilities } from './actor';
-import { AnswerMappingFunction } from './questions/mappings';
+import { Adapter, createAdapter } from './model';
 
 /**
  * @desc
@@ -53,15 +53,6 @@ import { AnswerMappingFunction } from './questions/mappings';
  */
 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 +68,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) => R): Question<R> & Adapter<Awaited<R>> {
+        return createAdapter<R>(new AnonymousQuestion<R>(description, body));
     }
 
     /**
@@ -102,9 +93,7 @@ export abstract class Question<T> {
      *
      * @returns {string}
      */
-    toString(): string {
-        return this.subject;
-    }
+    abstract toString(): string;
 
     /**
      * @desc
@@ -113,122 +102,31 @@ export abstract class Question<T> {
      * @param {string} subject
      * @returns {Question<T>}
      */
-    describedAs(subject: string): this {
-        this.subject = subject;
-
-        return this;
-    }
-
-    /**
-     * @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';
-     *
-     *  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}
-     */
-    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>>>;
-    }
+    abstract describedAs(subject: string): this;
 
     /**
      * @abstract
+     * // todo check why api docs are not getting generated for this methods
      */
     abstract answeredBy(actor: AnswersQuestions & UsesAbilities): T;
-}
-
-/**
- * @package
- */
-type AnswerOrItemOfMappableCollection<V> =
-    V extends PromiseLike<infer PromisedValue>
-        ? PromisedValue extends Mappable<infer Item>
-            ? Item
-            : PromisedValue
-        : V extends Mappable<infer Item>
-            ? Item
-            : V;
 
-/**
- * @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
+    public as<O>(mapping: (answer: Awaited<T>) => Promise<O> | O): Question<Promise<O>> {
+        return Question.about<Promise<O>>(`${ this.toString() } as ${ inspected(mapping, { inline: true }) }`, async actor => {
+            const answer = (await actor.answer(this)) as Awaited<T>;
+            return mapping(answer);
+        });
+    }
+}
 
 /**
  * @package
  */
 class AnonymousQuestion<T> extends Question<T> {
-    constructor(private description: string, private body: (actor: AnswersQuestions & UsesAbilities) => T) {
-        super(description);
+    constructor(private subject: string, private body: (actor: AnswersQuestions & UsesAbilities) => T) {
+        super();
     }
 
-    answeredBy(actor: AnswersQuestions & UsesAbilities) {
+    answeredBy(actor: AnswersQuestions & UsesAbilities): T {
         return this.body(actor);
     }
 
@@ -244,4 +142,8 @@ class AnonymousQuestion<T> extends Question<T> {
 
         return this;
     }
+
+    toString(): string {
+        return this.subject;
+    }
 }

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 './model';
 export * from './Question';
 export * from './questions';
 export * from './Task';
-export * from './tasks';

package/src/screenplay/model/Adapter.ts

@@ -0,0 +1,14 @@
+import { Answerable } from '../Answerable';
+import { Interaction } from '../Interaction';
+import { Question } from '../Question';
+
+export type Adapter<OriginalType> = {
+    [Field in keyof Omit<OriginalType, keyof Question<OriginalType>>]:
+    // is it a method?
+    OriginalType[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]> }) =>  Question<Promise<Awaited<OriginalMethodResult>>> & Interaction & Adapter<Awaited<OriginalMethodResult>>
+    // is it an object? wrap each field
+        : Question<Promise<Awaited<OriginalType[Field]>>> & Interaction & Adapter<Awaited<OriginalType[Field]>>
+}
+

package/src/screenplay/model/createAdapter.ts

@@ -0,0 +1,142 @@
+import { LogicError } from '../../errors';
+import { inspected } from '../../io/inspected';
+import { Actor, AnswersQuestions, UsesAbilities } from '../actor';
+import { Interaction } from '../Interaction';
+import { Question } from '../Question';
+import { Adapter } from './Adapter';
+
+export function createAdapter<A, Q extends Question<A> = Question<A>>(question: Q): Q & Adapter<Awaited<A>> {
+
+    return new Proxy<Q>(question, {
+
+        get(target: Q, key: string | symbol | number, receiver: any) {
+            if (key === Symbol.toPrimitive) {
+                return (_hint: 'number' | 'string' | 'default') => {
+                    return target.toString();
+                }
+            }
+
+            if (key in target) {
+                return Reflect.get(target, key, receiver);
+            }
+
+            if (doNotProxy(key)) {
+                return;
+            }
+
+            const fieldDescription = (typeof key === 'number' || /^\d+$/.test(String(key)))
+                ? `[${ String(key) }]`  // array index
+                : `.${ String(key) }`;  // field/method name
+
+            // when property is invoked as a method
+            function proxy(...originalParameters) {
+
+                const parameterDescriptions = [
+                    '(',
+                    originalParameters.map(p => inspected(p, { inline: true, markQuestions: true })).join(', '),
+                    ')'
+                ].join('');
+
+                const originalSubject = inspected(question, { inline: true, markQuestions: true });
+
+                return createAdapter(new DynamicProp(originalSubject + fieldDescription + parameterDescriptions, async actor => {
+                    // resolve the original answer
+                    const answer = await actor.answer(target);
+
+                    if (answer === undefined) {
+                        throw new LogicError(`${ inspected(target, { inline: true, markQuestions: true }) } is undefined, can't read property '${ String(key) }'`);
+                    }
+
+                    if (typeof answer[key] !== 'function') {
+                        throw new LogicError(`${ inspected(target, { inline: true, markQuestions: true }) } does not have a method called '${ String(key) }'`);
+                    }
+
+                    // convert parameters from Answerable<T> => T
+                    const parameters = await (Promise.all(
+                        originalParameters.map(parameter => {
+                            return actor.answer(parameter)
+                        })
+                    ));
+
+                    // invoke the method call on the original answer
+                    return answer[key](...parameters)
+                }));
+            }
+
+            const originalSubject = inspected(question, { inline: true, markQuestions: true });
+
+            proxy.subject = originalSubject + fieldDescription
+
+            // when property is accessed as a field
+            const body = async (actor: Actor) => {
+                const answer = await actor.answer(target);
+
+                if (answer === undefined) {
+                    throw new LogicError(`${ target } is undefined, can't read property "${ String(key) }"`);
+                }
+
+                return answer[key];
+            };
+
+            proxy.answeredBy = body;
+            proxy.performAs = body;
+
+            proxy.toString = () => {
+                return proxy.subject;
+            };
+
+            proxy.describedAs = (newSubject: string) => {
+                proxy.subject = newSubject;
+
+                return proxy;
+            }
+
+            proxy.as = <O>(mapping: (answer: Awaited<A>) => O): Question<Promise<O>> => {
+                return Question.about<Promise<O>>(`${ proxy.subject } as ${ inspected(mapping, { inline: true }) }`, async actor => {
+                    const answer = await actor.answer(proxy)
+                    return mapping(answer);
+                });
+            }
+
+            return createAdapter(proxy as any);
+        }
+    }) as Q & Adapter<Awaited<A>>
+}
+
+function doNotProxy(key: string | symbol | number) {
+    const prohibited: Array<string | symbol | number> = [
+        'then', // don't proxy Promises
+    ];
+
+    return prohibited.includes(key)
+}
+
+class DynamicProp<T> extends Interaction implements Question<T> {
+    constructor(protected subject: string, private body: (actor: AnswersQuestions & UsesAbilities) => T) {
+        super();
+    }
+
+    answeredBy(actor: AnswersQuestions & UsesAbilities): T {
+        return this.body(actor);
+    }
+
+    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
+        await this.body(actor);
+    }
+
+    as<O>(mapping: (answer: Awaited<T>) => Promise<O> | O): Question<Promise<O>> {
+        return createAdapter(new DynamicProp(`${ this.subject } as ${ inspected(mapping, { inline: true }) }`, async actor => {
+            const answer = (await actor.answer(this)) as Awaited<T>;
+            return mapping(answer);
+        })) as Question<Promise<O>>;
+    }
+
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
+}

package/src/screenplay/model/index.ts

@@ -0,0 +1,2 @@
+export * from './Adapter';
+export * from './createAdapter';

package/src/screenplay/questions/Expectation.ts

@@ -19,6 +19,9 @@ export type Predicate<A, E> = (actual: A, expected: E) => boolean;
 export abstract class Expectation<Expected, Actual = Expected>
     extends Question<(actual: Actual) => Promise<ExpectationOutcome<Expected, Actual>>>
 {
+    constructor(protected subject: string) {
+        super();
+    }
 
     /**
      * @desc
@@ -88,6 +91,22 @@ export abstract class Expectation<Expected, Actual = Expected>
     }
 
     abstract answeredBy(actor: AnswersQuestions): (actual: Actual) => Promise<ExpectationOutcome<Expected, Actual>>;
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
 }
 
 /**
@@ -96,7 +115,7 @@ export abstract class Expectation<Expected, Actual = Expected>
 class DynamicallyGeneratedExpectation<Expected, Actual> extends Expectation<Expected, Actual> {
 
     constructor(
-        private readonly description: string,
+        description: string,
         private readonly predicate: Predicate<Actual, Expected>,
         private readonly expectedValue: Answerable<Expected>,
     ) {

package/src/screenplay/questions/List.ts

@@ -64,6 +64,7 @@ export class List<
 >
     extends Question<Collection_Return_Type>
 {
+    private subject: string;
 
     /**
      * @desc
@@ -88,7 +89,8 @@ export class List<
      * @param {List_Adapter_Type} collection
      */
     constructor(private readonly collection: List_Adapter_Type) {
-        super(formatted`${ collection }`);
+        super();
+        this.subject = formatted`${ collection }`;
     }
 
     /**
@@ -241,6 +243,22 @@ export class List<
         return this.collection.items(actor);
     }
 
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
+
     private static ordinalSuffixOf(index: number): string {
         const
             lastDigit = index % 10,

package/src/screenplay/questions/Note.ts

@@ -1,3 +1,4 @@
+import { formatted } from '../../io';
 import { TakeNotes } from '../abilities';
 import { AnswersQuestions, UsesAbilities } from '../actor';
 import { Question } from '../Question';
@@ -42,6 +43,8 @@ import { Question } from '../Question';
  */
 export class Note<Answer> extends Question<Promise<Answer>> {
 
+    private subject: string;
+
     /**
      * @desc
      *  Retrieves the previously recorded answer to a given {@link Question}
@@ -58,7 +61,8 @@ export class Note<Answer> extends Question<Promise<Answer>> {
      * @param {Question<Promise<Answer>> | Question<Answer> | string} topic
      */
     constructor(private readonly topic: Question<Promise<Answer>> | Question<Answer> | string) {
-        super(`a note of ${ topic }`);
+        super();
+        this.subject = formatted `a note of ${ topic }`;
     }
 
     /**
@@ -76,4 +80,20 @@ export class Note<Answer> extends Question<Promise<Answer>> {
     answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Answer> {
         return TakeNotes.as(actor).answerTo(this.topic);
     }
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
 }

package/src/screenplay/questions/index.ts

@@ -2,9 +2,6 @@ export * from './Check';
 export * from './Expectation';
 export * from './expectations';
 export * from './List';
-export * from './mappings';
 export * from './MetaQuestion';
 export * from './Note';
-export { Property } from './Property';
 export * from './q';
-export * from './Transform';

package/src/screenplay/questions/lists/ArrayListAdapter.ts

@@ -154,16 +154,19 @@ export class ArrayListAdapter<Item_Type> implements ListAdapter<Item_Type, Item_
 class ArrayListFilter<Item_Type, Answer_Type>
     extends Question<Promise<Item_Type[]>>
 {
+    private subject: string;
+
     constructor(
         private readonly collection: Answerable<Item_Type[]>,
         private readonly question: MetaQuestion<Item_Type, Promise<Answer_Type> | Answer_Type>,
         private readonly expectation: Expectation<any, Answer_Type>
     ) {
-        super([
+        super();
+        this.subject = [
             formatted `${ collection }`,
             collection instanceof ArrayListFilter ? 'and' : 'where',
             formatted `${ question } does ${ expectation }`
-        ].join(' '));
+        ].join(' ');
     }
 
     answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Item_Type[]> {
@@ -182,5 +185,21 @@ class ArrayListFilter<Item_Type, Answer_Type>
                     .map(result => result.item)
             );
     }
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    toString(): string {
+        return this.subject;
+    }
 }
 

package/lib/decorators/pending.js

@@ -1,2 +0,0 @@
-// class-level
-//# sourceMappingURL=pending.js.map

package/lib/decorators/pending.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"pending.js","sourceRoot":"","sources":["../../src/decorators/pending.ts"],"names":[],"mappings":"AAAA,cAAc"}

package/lib/decorators/step.js

@@ -1,2 +0,0 @@
-// performAs level; sets a toString; deprecated
-//# sourceMappingURL=step.js.map

package/lib/decorators/step.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/decorators/step.ts"],"names":[],"mappings":"AAAA,+CAA+C"}

package/lib/io/collections/mappable.d.ts

@@ -1,52 +0,0 @@
-/**
- * @desc
- *  Describes a collection providing
- *  a [`map`-like interface](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
- *
- * @interface
- *
- * @see {@link Question#map}
- * @see {@link ElementArrayFinder}
- */
-export interface Mappable<Item> {
-    /**
-     * @desc
-     *  Applies a {@link MappingFunction} function to each element of a {@link Mappable} collection.
-     *
-     *  The callback receives an item from the collection as the first argument
-     *  and its index as the second argument.
-     *
-     * @abstract
-     *
-     * @type {function<U>(callback: (item?: Item, index?: number) => U): PromiseLike<U[]> | U[]}
-     */
-    map: <U>(callback: (item?: Item, index?: number) => U) => PromiseLike<U[]> | U[];
-}
-/**
- * @desc
- *  A mapping function converting one type into another.
- *
- * @public
- *
- * @typedef {function(item?: V, index?: number) => Promise<O> | O} Mapping<V,O>
- */
-export declare type MappingFunction<V, O> = (item?: V, index?: number) => O;
-/**
- * @desc
- *  Checks if the value is a {@link Mappable} collection of items.
- *
- * @example <caption>An Array</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *
- *  Mappable.isMappable([ 1, 2, 3 ]) === true
- *
- * @example <caption>Protractor's ElementArrayFinder</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *  import { element } from 'protractor';
- *
- *  Mappable.isMappable(element.all(by.tagName('li')) === true
- *
- * @param {Mappable<Item> | any} maybeCollection
- * @returns {boolean}
- */
-export declare function isMappable<Item>(maybeCollection: Mappable<Item> | any): maybeCollection is Mappable<Item>;

package/lib/io/collections/mappable.js

@@ -1,28 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isMappable = void 0;
-/**
- * @desc
- *  Checks if the value is a {@link Mappable} collection of items.
- *
- * @example <caption>An Array</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *
- *  Mappable.isMappable([ 1, 2, 3 ]) === true
- *
- * @example <caption>Protractor's ElementArrayFinder</caption>
- *  import { Mappable } from '@serenity-js/core/lib/io';
- *  import { element } from 'protractor';
- *
- *  Mappable.isMappable(element.all(by.tagName('li')) === true
- *
- * @param {Mappable<Item> | any} maybeCollection
- * @returns {boolean}
- */
-function isMappable(maybeCollection) {
-    return !!maybeCollection
-        && !!maybeCollection.map
-        && typeof maybeCollection.map === 'function';
-}
-exports.isMappable = isMappable;
-//# sourceMappingURL=mappable.js.map

package/lib/io/collections/mappable.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mappable.js","sourceRoot":"","sources":["../../../src/io/collections/mappable.ts"],"names":[],"mappings":";;;AAqCA;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,UAAU,CAAO,eAAqC;IAClE,OAAO,CAAC,CAAE,eAAe;WAClB,CAAC,CAAE,eAAe,CAAC,GAAG;WACtB,OAAO,eAAe,CAAC,GAAG,KAAK,UAAU,CAAC;AACrD,CAAC;AAJD,gCAIC"}