@serenity-js/core 3.0.0-rc.9 → 3.0.0

package/lib/screenplay/Question.d.ts

@@ -1,105 +1,222 @@
-import { AnswersQuestions, UsesAbilities } from './actor';
+/// <reference types="node" />
+import * as util from 'util';
+import { UsesAbilities } from './abilities';
 import { Answerable } from './Answerable';
 import { Interaction } from './Interaction';
 import { Optional } from './Optional';
+import { AnswersQuestions } from './questions/AnswersQuestions';
+import { RecursivelyAnswered } from './RecursivelyAnswered';
+import { WithAnswerableProperties } from './WithAnswerableProperties';
 /**
- * @desc
- *  Enables the {@link Actor} to query the system under test.
+ * **Questions** describe how {@apilink Actor|actors} should query the system under test or the test environment to retrieve some information.
  *
- * @example <caption>A basic Question</caption>
- *  import { Actor, AnswersQuestions, UsesAbilities, Question } from '@serenity-js/core'
+ * Questions are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Ability|Abilities}, {@apilink Interaction|Interactions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actor}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Interaction}
+ * - {@apilink QuestionAdapter}
+ *
+ * ## Implementing a basic custom Question
+ *
+ * ```ts
+ *  import { actorCalled, AnswersQuestions, UsesAbilities, Question } from '@serenity-js/core'
  *  import { Ensure, equals } from '@serenity-js/assertions'
  *
  *  const LastItemOf = <T>(list: T[]): Question<T> =>
- *      Question.about('last item from the list', (actor: AnswersQuestions & UsesAbilities) => {
- *          return list[list.length - 1];
- *      });
+ *    Question.about('last item from the list', (actor: AnswersQuestions & UsesAbilities) => {
+ *      return list[list.length - 1]
+ *    });
+ *
+ *  await actorCalled('Quentin').attemptsTo(
+ *    Ensure.that(LastItemFrom([1,2,3]), equals(3)),
+ *  )
+ * ```
  *
- *  Actor.named('Quentin').attemptsTo(
- *      Ensure.that(LastItemFrom([1,2,3]), equals(3)),
- *  );
+ * ## Implementing a Question that uses an Ability
  *
- * @example <caption>A question using the Actor's Ability to do something</caption>
+ * Just like the {@apilink Interaction|interactions}, a {@apilink Question}
+ * also can use {@apilink Actor|actor's} {@apilink Ability|abilities}.
+ *
+ * Here, we use the ability to {@apilink CallAnApi} to retrieve a property of
+ * an HTTP response.
+ *
+ * ```ts
  *  import { AnswersQuestions, UsesAbilities, Question } from '@serenity-js/core'
  *  import { CallAnApi } from '@serenity-js/rest'
  *
  *  const TextOfLastResponseStatus = () =>
- *      Question.about<number>(`the text of the last response status`, actor => {
- *          return CallAnApi.as(actor).mapLastResponse(response => response.statusText);
- *      });
+ *    Question.about<number>(`the text of the last response status`, actor => {
+ *      return CallAnApi.as(actor).mapLastResponse(response => response.statusText)
+ *    })
+ * ```
+ *
+ * #### Learn more
+ * - {@apilink CallAnApi}
+ * - {@apilink LastResponse}
+ *
+ * ## Mapping answers to other questions
+ *
+ * Apart from retrieving information, {@apilink Question|questions} can be used to transform information retrieved by other questions.
  *
- *  @example <caption>Mapping answers to other questions</caption>
- *  import { Actor, AnswersQuestions, UsesAbilities, Question } from '@serenity-js/core'
- *  import { CallAnApi, LastResponse } from '@serenity-js/rest'
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * Here, we use the factory method {@apilink Question.about} to produce a question that makes the received {@apilink Actor|actor}
+ * answer {@apilink LastResponse.status} and then compare it against some expected value.
  *
- *  const RequestWasSuccessful = () =>
- *      Question.about<number>(`the text of the last response status`, actor => {
- *          return LastResponse.status().answeredBy(actor) === 200;
- *      });
+ * ```ts
+ * import { actorCalled, AnswersQuestions, UsesAbilities, Question } from '@serenity-js/core'
+ * import { CallAnApi, LastResponse } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- *  const actor = Actor.named('Quentin').whoCan(CallAnApi.at('https://myapp.com/api'));
+ * const RequestWasSuccessful = () =>
+ *   Question.about<number>(`the text of the last response status`, actor => {
+ *     return LastResponse.status().answeredBy(actor) === 200;
+ *   });
  *
- *  actor.attemptsTo(
- *      Send.a(GetRequest.to('/books/0-688-00230-7')),
- *      Ensure.that(RequestWasSuccessful(), isTrue()),
- *  );
+ * await actorCalled('Quentin')
+ *   .whoCan(CallAnApi.at('https://api.example.org/'));
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/books/0-688-00230-7')),
+ *     Ensure.that(RequestWasSuccessful(), isTrue()),
+ *   );
+ * ```
  *
- * @see {@link Actor}
- * @see {@link Interaction}
- * @see {@link Ability}
+ * Note that the above example is for demonstration purposes only, Serenity/JS provides an easier way to
+ * verify the response status of the {@apilink LastResponse}:
  *
- * @abstract
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { CallAnApi, LastResponse } from '@serenity-js/rest'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Quentin')
+ *   .whoCan(CallAnApi.at('https://api.example.org/'));
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/books/0-688-00230-7')),
+ *     Ensure.that(LastResponse.status(), equals(200)),
+ *   );
+ * ```
+ *
+ * @group Screenplay Pattern
  */
 export declare abstract class Question<T> {
     /**
-     * @desc
-     *  Factory method that simplifies the process of defining custom questions.
+     * Factory method that simplifies the process of defining custom questions.
      *
-     * @example
-     *  const EnvVariable = (name: string) =>
-     *      Question.about(`the ${ name } env variable`, actor => process.env[name])
+     * #### Defining a custom question
      *
-     * @static
+     * ```ts
+     * import { Question } from '@serenity-js/core'
      *
-     * @param {string} description
-     * @param {function(actor: AnswersQuestions & UsesAbilities): R} body
+     * const EnvVariable = (name: string) =>
+     *   Question.about(`the ${ name } env variable`, actor => process.env[name])
+     * ```
      *
-     * @returns {Question<R>}
+     * @param description
+     * @param body
      */
-    static about<R>(description: string, body: (actor: AnswersQuestions & UsesAbilities) => Promise<R> | R): QuestionAdapter<Awaited<R>>;
+    static about<Result_Type>(description: string, body: (actor: AnswersQuestions & UsesAbilities) => Promise<Result_Type> | Result_Type): QuestionAdapter<Awaited<Result_Type>>;
     /**
-     * @desc
-     *  Checks if the value is a {@link Question}.
+     * Generates a {@apilink QuestionAdapter} that recursively resolves
+     * any {@apilink Answerable} fields of the provided object,
+     * including {@apilink Answerable} fields of {@apilink WithAnswerableProperties|nested objects}.
      *
-     * @static
+     * Optionally, the method accepts `overrides` to be shallow-merged with the fields of the original `source`,
+     * producing a new merged object.
      *
-     * @param {any} maybeQuestion
-     *  The value to check
+     * Overrides are applied from left to right, with subsequent objects overwriting property assignments of the previous ones.
+     *
+     * #### Resolving an object recursively using `Question.fromObject`
+     *
+     * ```ts
+     * import { actorCalled, Question } from '@serenity-js/core'
+     * import { Send, PostRequest } from '@serenity-js/rest'
+     * import { By, Text, PageElement } from '@serenity-js/web'
+     *
+     * await actorCalled('Daisy')
+     *   .whoCan(CallAnApi.at('https://api.example.org'))
+     *   .attemptsTo(
+     *     Send.a(
+     *       PostRequest.to('/products/2')
+     *         .with(
+     *           Question.fromObject({
+     *             name: Text.of(PageElement.located(By.css('.name'))),
+     *           })
+     *         )
+     *       )
+     *   );
+     * ```
+     *
+     * #### Merging objects using `Question.fromObject`
+     *
+     * ```ts
+     *  import { actorCalled, Question } from '@serenity-js/core'
+     *  import { Send, PostRequest } from '@serenity-js/rest'
+     *  import { By, Text, PageElement } from '@serenity-js/web'
+     *
+     *  await actorCalled('Daisy')
+     *    .whoCan(CallAnApi.at('https://api.example.org'))
+     *    .attemptsTo(
+     *      Send.a(
+     *        PostRequest.to('/products/2')
+     *          .with(
+     *            Question.fromObject({
+     *              name: Text.of(PageElement.located(By.css('.name'))),
+     *              quantity: undefined,
+     *            }, {
+     *              quantity: 2,
+     *            })
+     *          )
+     *        )
+     *    );
      *
-     * @returns {boolean}
+     * @param source
+     * @param overrides
+     *
+     * #### Learn more
+     * - {@apilink WithAnswerableProperties}
+     * - {@apilink RecursivelyAnswered}
+     * - {@apilink Answerable}
+     */
+    static fromObject<Source_Type extends object>(source: Answerable<WithAnswerableProperties<Source_Type>>, ...overrides: Array<Answerable<Partial<WithAnswerableProperties<Source_Type>>>>): QuestionAdapter<RecursivelyAnswered<Source_Type>>;
+    /**
+     * Checks if the value is a {@apilink Question}.
+     *
+     * @param maybeQuestion
+     *  The value to check
      */
     static isAQuestion<T>(maybeQuestion: unknown): maybeQuestion is Question<T>;
     protected static createAdapter<AT>(statement: Question<AT>): QuestionAdapter<Awaited<AT>>;
+    private static fieldDescription;
+    private static methodDescription;
     /**
-     * @desc
-     *  Describes the subject of this {@link Question}.
-     *
-     * @returns {string}
+     * Returns the description of the subject of this {@apilink Question}.
      */
     abstract toString(): string;
     /**
-     * @desc
-     *  Changes the description of this question's subject.
+     * Changes the description of this question's subject.
      *
-     * @param {string} subject
-     * @returns {Question<T>}
+     * @param subject
      */
     abstract describedAs(subject: string): this;
     /**
-     * @abstract
+     * Instructs the provided {@apilink Actor} to use their {@apilink Ability|abilities}
+     * to answer this question.
      */
     abstract answeredBy(actor: AnswersQuestions & UsesAbilities): T;
+    /**
+     * Maps this question to one of a different type.
+     *
+     * ```ts
+     * Question.about('number returned as string', actor => '42')   // returns: QuestionAdapter<string>
+     *   .as(Number)                                                // returns: QuestionAdapter<number>
+     * ```
+     *
+     * @param mapping
+     */
     as<O>(mapping: (answer: Awaited<T>) => Promise<O> | O): QuestionAdapter<O>;
 }
 declare global {
@@ -107,32 +224,46 @@ declare global {
         new <Source_Type extends object, Target_Type extends object>(target: Source_Type, handler: ProxyHandler<Source_Type>): Target_Type;
     }
 }
-export declare type ProxiedAnswer<Original_Type> = {
+/**
+ * Describes an object recursively wrapped in {@apilink QuestionAdapter} proxies, so that:
+ * - both methods and fields of the wrapped object can be used as {@apilink Question|questions} or {@apilink Interactions|interactions}
+ * - method parameters of the wrapped object will accept {@apilink Answerable|Answerable<T>}
+ *
+ * @group Questions
+ */
+export type QuestionAdapterFieldDecorator<Original_Type> = {
     [Field in keyof Omit<Original_Type, keyof QuestionStatement<Original_Type>>]: Original_Type[Field] extends (...args: infer OriginalParameters) => infer OriginalMethodResult ? (...args: {
-        [P in keyof OriginalParameters]: Answerable<OriginalParameters[P]>;
-    }) => {
-        isPresent(): Question<Promise<boolean>>;
-    } & QuestionAdapter<Awaited<OriginalMethodResult>> : {
-        isPresent(): Question<Promise<boolean>>;
-    } & QuestionAdapter<Awaited<Original_Type[Field]>>;
+        [P in keyof OriginalParameters]: Answerable<Awaited<OriginalParameters[P]>>;
+    }) => QuestionAdapter<Awaited<OriginalMethodResult>> : Original_Type[Field] extends number | bigint | boolean | string | symbol | object ? QuestionAdapter<Awaited<Original_Type[Field]>> : any;
 };
-export declare type QuestionAdapter<Original_Type> = Question<Promise<Original_Type>> & Interaction & Optional & ProxiedAnswer<Original_Type>;
+/**
+ * A union type representing a proxy object returned by {@apilink Question.about}.
+ *
+ * {@apilink QuestionAdapter} proxies the methods and fields of the wrapped object recursively,
+ * allowing them to be used as either a {@apilink Question} or an {@apilink Interaction}.
+ *
+ * @group Questions
+ */
+export type QuestionAdapter<T> = Question<Promise<T>> & Interaction & {
+    isPresent(): Question<Promise<boolean>>;
+} & QuestionAdapterFieldDecorator<T>;
+/** @package */
 declare class QuestionStatement<Answer_Type> extends Interaction implements Question<Promise<Answer_Type>>, Optional {
     private subject;
     private readonly body;
+    private answer;
     constructor(subject: string, body: (actor: AnswersQuestions & UsesAbilities, ...Parameters: any[]) => Promise<Answer_Type> | Answer_Type);
     /**
-     * @desc
-     *  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.
-     *
-     * @returns {Question<Promise<boolean>>}
+     * Returns a Question that resolves to `true` if resolving the {@apilink QuestionStatement}
+     * returns a value other than `null` or `undefined`, and doesn't throw errors.
      */
     isPresent(): Question<Promise<boolean>>;
     answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Answer_Type>;
     performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+    [util.inspect.custom](depth: number, options: util.InspectOptionsStylized, inspect: typeof util.inspect): string;
     describedAs(subject: string): this;
     toString(): string;
     as<O>(mapping: (answer: Awaited<Answer_Type>) => (Promise<O> | O)): QuestionAdapter<O>;
 }
 export {};
+//# sourceMappingURL=Question.d.ts.map

package/lib/screenplay/Question.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Question.d.ts","sourceRoot":"","sources":["../../src/screenplay/Question.ts"],"names":[],"mappings":"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"}