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

package/lib/screenplay/Task.d.ts

@@ -1,55 +1,195 @@
+import { PerformsActivities } from './activities';
 import { Activity } from './Activity';
-import { PerformsActivities } from './actor';
 /**
- * @desc
- *  Aggregates {@link Interaction}s so that they represents logical
- *  steps of a business process an {@link Actor} can perform.
+ * **Tasks** model **{@apilink Activity|sequences of activities}**
+ * and help you capture meaningful steps of an {@apilink Actor|actor} workflow
+ * in your domain.
  *
- * @implements {Activity}
- * @see {@link Interaction}
- * @see {@link Actor}
+ * Typically, tasks correspond to higher-level, business domain-specific activities
+ * like to `BookAPlaneTicket`, `PlaceATrade`, `TransferFunds`, and so on.
+ * However, higher-level tasks can and should be composed of lower-level tasks.
+ * For example, a task to `SignUp` could be composed of tasks to `ProvideUsername` and `ProvidePassword`.
+ *
+ * The lowest-level tasks in your abstraction hierarchy should be composed of {@apilink Interaction|interactions}.
+ * For example, a low-level task to `ProvideUsername` could be composed of an interaction to {@apilink Enter} the value
+ * into a form field and {@apilink Press} the {@apilink Key.Enter}.
+ *
+ * Tasks 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 Question|Questions}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - [User-Centred Design: How a 50 year old technique became the key to scalable test automation](https://janmolak.com/user-centred-design-how-a-50-year-old-technique-became-the-key-to-scalable-test-automation-66a658a36555)
+ * - {@apilink Actor|Actors}
+ * - {@apilink Activity|Activities}
+ * - {@apilink Interaction|Interactions}
+ *
+ * ## Defining a task
+ *
+ * ```ts
+ * import { Answerable, Task, d } from '@serenity-js/core'
+ * import { By, Click, Enter, PageElement, Press, Key } from '@serenity-js/web'
+ *
+ * const SignIn = (username: Answerable<string>, password: Answerable<string>) =>
+ *   Task.where(d`#actor signs is as ${ username }`,
+ *     Enter.theValue(username).into(PageElement.located(By.id('username'))),
+ *     Enter.theValue(password).into(PageElement.located(By.id('password'))),
+ *     Press.the(Key.Enter),
+ *   );
+ * ```
+ *
+ * ## Defining a not implemented task
+ *
+ * Note that calling {@apilink Task.where} method without providing the sequence of {@apilink Activity|activities}
+ * produces a Task that's marked as "pending" in the test report.
+ *
+ * This feature is useful when you want to quickly write down a task that will be needed in the scenario,
+ * but you're not yet sure what activities it will involve.
+ *
+ * ```ts
+ * import { Task } from '@serenity-js/core'
+ *
+ * const SignUp = () =>
+ *     Task.where(`#actor signs up for a newsletter`) // no activities provided
+ *                                                    // => task marked as pending
+ * ```
+ *
+ * ## Composing activities into tasks
+ *
+ * The purpose of **tasks** is to help you capture domain vocabulary by **associating domain meaning** with a **sequence of activities**.
+ * From the implementation perspective, tasks help you give a **meaningful description** to such sequence
+ * and provide a way to **easily reuse activities across your code base**.
+ *
+ * :::tip Remember
+ * **Tasks** associate **domain meaning** with a sequence of **lower-level activities** and provide a mechanism for **code reuse**.
+ * :::
+ *
+ * For example, a task to _find a flight connection from London to New York_ could be modelled as a sequence of the following lower-level activities:
+ * - specify origin city of "London"
+ * - specify destination city of "New York"
+ *
+ * The easiest way to implement such task, and any custom Serenity/JS task for this matter, is to use the {@apilink Task.where} method to compose the lower-level activities:
+ *
+ * ```typescript
+ * import { Task } from '@serenity-js/core'
+ *
+ * const findFlight = (originCity: string, destinationCity: string) =>
+ *     Task.where(`#actors finds a flight from ${ originCity } to ${ destinationCity }`,   // task goal
+ *         specifyOriginCity(originCity),                                                  // activities
+ *         specifyDestinationCity(originCity),
+ *     )
+ * ```
+ *
+ * Furthermore, if the actor was interacting with a web UI, a task to _specify origin city_ could again be composed of other activities:
+ * - click on the `origin airport` widget
+ * - enter city name of `London`
+ * - pick the first suggested airport from the list
+ *
+ * Conversely, a task to _specify destination city_ could be composed of:
+ * - click on the `destination airport` widget
+ * - enter city name of `New York`
+ * - pick the first suggested airport from the list
+ *
+ * Conveniently, [Serenity/JS modules](/handbook/about/architecture) provide low-level activities that
+ * allow actors to interact with the various interfaces of the system under test.
+ * For example, [Serenity/JS Web module](/api/web) ships with activities such as {@apilink Click} or {@apilink Enter},
+ * which we can incorporate into our task definitions just like any other activities:
+ *
+ * ```typescript
+ * import { Task } from '@serenity-js/core'
+ * import { Click, Enter, Key, Press } from '@serenity-js/web'
+ *
+ * import { FlightFinder } from './ui/flight-finder'
+ *
+ * const specifyOriginCity = (originCity: string) =>
+ *     Task.where(`#actor specifies origin city of ${ originCity }`,
+ *         Click.on(FlightFinder.originAirport),
+ *         Enter.theValue(originCity).into(FlightFinder.originAirport),
+ *         Press.the(Key.ArrowDown, Key.Enter).into(FlightFinder.originAirport),
+ *     )
+ *
+ * const specifyDestinationCity = (destinationCity: string) =>
+ *     Task.where(`#actor specifies destination city of ${ destinationCity }`,
+ *         Click.on(FlightFinder.destinationAirport),
+ *         Enter.theValue(destinationCity).into(FlightFinder.destinationAirport),
+ *         Press.the(Key.ArrowDown, Key.Enter).into(FlightFinder.destinationAirport),
+ *     )
+ * ```
+ *
+ * As you can already see, tasks to _specify origin city_ and _specify destination city_ are almost identical,
+ * save for the name of the widget and the text value the actor is supposed to enter.
+ * Serenity/JS **task-based code reuse model** means that we can clean up such duplicated implementation
+ * by **extracting a parameterised task**, in this case called `specifyCity`:
+ *
+ * ```typescript
+ * import { Task } from '@serenity-js/core'
+ * import { Click, Enter, Key, PageElement, Press } from '@serenity-js/web'
+ *
+ * import { FlightFinder } from './ui/flight-finder'
+ *
+ * const specifyOriginCity = (originCity: string) =>
+ *     Task.where(`#actor specifies origin city of ${ originCity }`,
+ *         specifyCity(originCity, FlightFinder.originAirport)
+ *     )
+ *
+ * const specifyDestinationCity = (destinationCity: string) =>
+ *     Task.where(`#actor specifies destination city of ${ destinationCity }`,
+ *         specifyCity(destinationCity, FlightFinder.destinationAirport),
+ *     )
+ *
+ * const specifyCity = (cityName: string, widget: PageElement) =>
+ *     Task.where(`#actor specifies city of ${ cityName } in ${ widget }`,
+ *         Click.on(widget),
+ *         Enter.theValue(cityName).into(widget),
+ *         Press.the(Key.ArrowDown, Key.Enter).into(widget),
+ *     )
+ * ```
+ *
+ * As you work with Serenity/JS, you'll notice that the ideas of **functional decomposition**, so thinking of tasks as sequences of lower-level activities,
+ * as well as **functional composition**, so implementing reusable activities and composing them into higher-level tasks,
+ * are at the heart of the Screenplay Pattern. You'll also notice that the entire Serenity/JS framework does it best to help your team follow this approach.
+ *
+ * :::info The power of the Serenity/JS task-based code reuse model
+ * What makes the Serenity/JS task-based code reuse model so **powerful at scale** is the observation that:
+ * - for most software systems, a vast number of **diverse test scenarios** can be composed of a relatively **small number of high-level activities**
+ * - all **high-level activities** can be composed of a relatively **small number of lower-level activities**
+ * - in a reasonably consistently-designed software system, most lower-level activities tend to be similar and rather consistent across the various aspects of a given interface.
+ * In particular, **there are only so many ways** one can interact with a UI button or send an HTTP request to a web service.
+ *
+ * What this means in practice is that by investing your time in properly designing **relatively few reusable tasks**
+ * to test your system, you give your team a **significant productivity boost** and **leverage** when producing high-level test scenarios.
+ *
+ * On top of that, this design approach results not only in **simpler test scenarios** that reduce
+ * the [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) on the reader as they require them to process
+ * the scenario only one level of abstraction at the time.
+ * It also allows for the test to **take shortcuts** in well-defined points of the workflow - use a REST API request to create
+ * a test user account instead of going through the registration form.
+ * :::
+ *
+ * @group Screenplay Pattern
  */
-export declare abstract class Task implements Activity {
+export declare abstract class Task extends Activity {
     /**
-     * @desc
-     *  A factory method to make defining the Tasks more convenient.
-     *  Please note that calling this method without providing the list of {@link Activity} objects
-     *  will result in producing a Task that's marked as "pending" in the test report.
-     *
-     *  This feature is useful when you want to quickly write down a task that will be needed in the scenario,
-     *  but you're not yet sure what activities will constitute it.
-     *
-     * @example <caption>Modelling a task</caption>
-     * import { Log, Task } from '@serenity-js/core';
-     *
-     * const Debug = (something: Answerable<any>) =>
-     *     Task.where(`#actor prints the answer to a question`,
-     *          Log.the(something),
-     *     );
-     *
-     * @example <caption>Modelling a not implemented task</caption>
-     * import { Task } from '@serenity-js/core';
-     *
-     * const SignUp = () =>
-     *     Task.where(`#actor signs up for a newsletter`); // no activities given
-     *                                                     // => task marked as pending
+     * A factory method that makes defining custom tasks more convenient.
      *
-     * @param {string} description - A description to be used when reporting this task
-     * @param {Activity[]} activities - A list of lower-level activities that constitute the task
+     * @param description
+     *  A description to be used when reporting this task
      *
-     * @returns {Task}
+     * @param activities
+     *  A sequence of lower-level activities that constitute this task
      */
     static where(description: string, ...activities: Activity[]): Task;
     /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Task}.
+     * Instructs the provided {@apilink Actor} to perform this {@apilink Task}.
      *
      * @param {PerformsActivities} actor
-     * @returns {Promise<void>}
      *
-     * @see {@link Actor}
-     * @see {@link PerformsActivities}
+     * #### Learn more
+     * - {@apilink Actor}
+     * - {@apilink PerformsActivities}
+     * - {@apilink Activity}
      */
-    abstract performAs(actor: PerformsActivities): PromiseLike<void>;
+    abstract performAs(actor: PerformsActivities): Promise<void>;
 }
+//# sourceMappingURL=Task.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../src/screenplay/Task.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwKG;AACH,8BAAsB,IAAK,SAAQ,QAAQ;IAEvC;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI;IAMlE;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;CAC/D"}

package/lib/screenplay/Task.js

@@ -2,44 +2,185 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Task = void 0;
 const errors_1 = require("../errors");
+const Activity_1 = require("./Activity");
 /**
- * @desc
- *  Aggregates {@link Interaction}s so that they represents logical
- *  steps of a business process an {@link Actor} can perform.
+ * **Tasks** model **{@apilink Activity|sequences of activities}**
+ * and help you capture meaningful steps of an {@apilink Actor|actor} workflow
+ * in your domain.
  *
- * @implements {Activity}
- * @see {@link Interaction}
- * @see {@link Actor}
+ * Typically, tasks correspond to higher-level, business domain-specific activities
+ * like to `BookAPlaneTicket`, `PlaceATrade`, `TransferFunds`, and so on.
+ * However, higher-level tasks can and should be composed of lower-level tasks.
+ * For example, a task to `SignUp` could be composed of tasks to `ProvideUsername` and `ProvidePassword`.
+ *
+ * The lowest-level tasks in your abstraction hierarchy should be composed of {@apilink Interaction|interactions}.
+ * For example, a low-level task to `ProvideUsername` could be composed of an interaction to {@apilink Enter} the value
+ * into a form field and {@apilink Press} the {@apilink Key.Enter}.
+ *
+ * Tasks 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 Question|Questions}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - [User-Centred Design: How a 50 year old technique became the key to scalable test automation](https://janmolak.com/user-centred-design-how-a-50-year-old-technique-became-the-key-to-scalable-test-automation-66a658a36555)
+ * - {@apilink Actor|Actors}
+ * - {@apilink Activity|Activities}
+ * - {@apilink Interaction|Interactions}
+ *
+ * ## Defining a task
+ *
+ * ```ts
+ * import { Answerable, Task, d } from '@serenity-js/core'
+ * import { By, Click, Enter, PageElement, Press, Key } from '@serenity-js/web'
+ *
+ * const SignIn = (username: Answerable<string>, password: Answerable<string>) =>
+ *   Task.where(d`#actor signs is as ${ username }`,
+ *     Enter.theValue(username).into(PageElement.located(By.id('username'))),
+ *     Enter.theValue(password).into(PageElement.located(By.id('password'))),
+ *     Press.the(Key.Enter),
+ *   );
+ * ```
+ *
+ * ## Defining a not implemented task
+ *
+ * Note that calling {@apilink Task.where} method without providing the sequence of {@apilink Activity|activities}
+ * produces a Task that's marked as "pending" in the test report.
+ *
+ * This feature is useful when you want to quickly write down a task that will be needed in the scenario,
+ * but you're not yet sure what activities it will involve.
+ *
+ * ```ts
+ * import { Task } from '@serenity-js/core'
+ *
+ * const SignUp = () =>
+ *     Task.where(`#actor signs up for a newsletter`) // no activities provided
+ *                                                    // => task marked as pending
+ * ```
+ *
+ * ## Composing activities into tasks
+ *
+ * The purpose of **tasks** is to help you capture domain vocabulary by **associating domain meaning** with a **sequence of activities**.
+ * From the implementation perspective, tasks help you give a **meaningful description** to such sequence
+ * and provide a way to **easily reuse activities across your code base**.
+ *
+ * :::tip Remember
+ * **Tasks** associate **domain meaning** with a sequence of **lower-level activities** and provide a mechanism for **code reuse**.
+ * :::
+ *
+ * For example, a task to _find a flight connection from London to New York_ could be modelled as a sequence of the following lower-level activities:
+ * - specify origin city of "London"
+ * - specify destination city of "New York"
+ *
+ * The easiest way to implement such task, and any custom Serenity/JS task for this matter, is to use the {@apilink Task.where} method to compose the lower-level activities:
+ *
+ * ```typescript
+ * import { Task } from '@serenity-js/core'
+ *
+ * const findFlight = (originCity: string, destinationCity: string) =>
+ *     Task.where(`#actors finds a flight from ${ originCity } to ${ destinationCity }`,   // task goal
+ *         specifyOriginCity(originCity),                                                  // activities
+ *         specifyDestinationCity(originCity),
+ *     )
+ * ```
+ *
+ * Furthermore, if the actor was interacting with a web UI, a task to _specify origin city_ could again be composed of other activities:
+ * - click on the `origin airport` widget
+ * - enter city name of `London`
+ * - pick the first suggested airport from the list
+ *
+ * Conversely, a task to _specify destination city_ could be composed of:
+ * - click on the `destination airport` widget
+ * - enter city name of `New York`
+ * - pick the first suggested airport from the list
+ *
+ * Conveniently, [Serenity/JS modules](/handbook/about/architecture) provide low-level activities that
+ * allow actors to interact with the various interfaces of the system under test.
+ * For example, [Serenity/JS Web module](/api/web) ships with activities such as {@apilink Click} or {@apilink Enter},
+ * which we can incorporate into our task definitions just like any other activities:
+ *
+ * ```typescript
+ * import { Task } from '@serenity-js/core'
+ * import { Click, Enter, Key, Press } from '@serenity-js/web'
+ *
+ * import { FlightFinder } from './ui/flight-finder'
+ *
+ * const specifyOriginCity = (originCity: string) =>
+ *     Task.where(`#actor specifies origin city of ${ originCity }`,
+ *         Click.on(FlightFinder.originAirport),
+ *         Enter.theValue(originCity).into(FlightFinder.originAirport),
+ *         Press.the(Key.ArrowDown, Key.Enter).into(FlightFinder.originAirport),
+ *     )
+ *
+ * const specifyDestinationCity = (destinationCity: string) =>
+ *     Task.where(`#actor specifies destination city of ${ destinationCity }`,
+ *         Click.on(FlightFinder.destinationAirport),
+ *         Enter.theValue(destinationCity).into(FlightFinder.destinationAirport),
+ *         Press.the(Key.ArrowDown, Key.Enter).into(FlightFinder.destinationAirport),
+ *     )
+ * ```
+ *
+ * As you can already see, tasks to _specify origin city_ and _specify destination city_ are almost identical,
+ * save for the name of the widget and the text value the actor is supposed to enter.
+ * Serenity/JS **task-based code reuse model** means that we can clean up such duplicated implementation
+ * by **extracting a parameterised task**, in this case called `specifyCity`:
+ *
+ * ```typescript
+ * import { Task } from '@serenity-js/core'
+ * import { Click, Enter, Key, PageElement, Press } from '@serenity-js/web'
+ *
+ * import { FlightFinder } from './ui/flight-finder'
+ *
+ * const specifyOriginCity = (originCity: string) =>
+ *     Task.where(`#actor specifies origin city of ${ originCity }`,
+ *         specifyCity(originCity, FlightFinder.originAirport)
+ *     )
+ *
+ * const specifyDestinationCity = (destinationCity: string) =>
+ *     Task.where(`#actor specifies destination city of ${ destinationCity }`,
+ *         specifyCity(destinationCity, FlightFinder.destinationAirport),
+ *     )
+ *
+ * const specifyCity = (cityName: string, widget: PageElement) =>
+ *     Task.where(`#actor specifies city of ${ cityName } in ${ widget }`,
+ *         Click.on(widget),
+ *         Enter.theValue(cityName).into(widget),
+ *         Press.the(Key.ArrowDown, Key.Enter).into(widget),
+ *     )
+ * ```
+ *
+ * As you work with Serenity/JS, you'll notice that the ideas of **functional decomposition**, so thinking of tasks as sequences of lower-level activities,
+ * as well as **functional composition**, so implementing reusable activities and composing them into higher-level tasks,
+ * are at the heart of the Screenplay Pattern. You'll also notice that the entire Serenity/JS framework does it best to help your team follow this approach.
+ *
+ * :::info The power of the Serenity/JS task-based code reuse model
+ * What makes the Serenity/JS task-based code reuse model so **powerful at scale** is the observation that:
+ * - for most software systems, a vast number of **diverse test scenarios** can be composed of a relatively **small number of high-level activities**
+ * - all **high-level activities** can be composed of a relatively **small number of lower-level activities**
+ * - in a reasonably consistently-designed software system, most lower-level activities tend to be similar and rather consistent across the various aspects of a given interface.
+ * In particular, **there are only so many ways** one can interact with a UI button or send an HTTP request to a web service.
+ *
+ * What this means in practice is that by investing your time in properly designing **relatively few reusable tasks**
+ * to test your system, you give your team a **significant productivity boost** and **leverage** when producing high-level test scenarios.
+ *
+ * On top of that, this design approach results not only in **simpler test scenarios** that reduce
+ * the [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) on the reader as they require them to process
+ * the scenario only one level of abstraction at the time.
+ * It also allows for the test to **take shortcuts** in well-defined points of the workflow - use a REST API request to create
+ * a test user account instead of going through the registration form.
+ * :::
+ *
+ * @group Screenplay Pattern
  */
-class Task {
+class Task extends Activity_1.Activity {
     /**
-     * @desc
-     *  A factory method to make defining the Tasks more convenient.
-     *  Please note that calling this method without providing the list of {@link Activity} objects
-     *  will result in producing a Task that's marked as "pending" in the test report.
+     * A factory method that makes defining custom tasks more convenient.
      *
-     *  This feature is useful when you want to quickly write down a task that will be needed in the scenario,
-     *  but you're not yet sure what activities will constitute it.
+     * @param description
+     *  A description to be used when reporting this task
      *
-     * @example <caption>Modelling a task</caption>
-     * import { Log, Task } from '@serenity-js/core';
-     *
-     * const Debug = (something: Answerable<any>) =>
-     *     Task.where(`#actor prints the answer to a question`,
-     *          Log.the(something),
-     *     );
-     *
-     * @example <caption>Modelling a not implemented task</caption>
-     * import { Task } from '@serenity-js/core';
-     *
-     * const SignUp = () =>
-     *     Task.where(`#actor signs up for a newsletter`); // no activities given
-     *                                                     // => task marked as pending
-     *
-     * @param {string} description - A description to be used when reporting this task
-     * @param {Activity[]} activities - A list of lower-level activities that constitute the task
-     *
-     * @returns {Task}
+     * @param activities
+     *  A sequence of lower-level activities that constitute this task
      */
     static where(description, ...activities) {
         return activities.length > 0
@@ -53,64 +194,22 @@ exports.Task = Task;
  */
 class DynamicallyGeneratedTask extends Task {
     constructor(description, activities) {
-        super();
-        this.description = description;
+        super(description, Task.callerLocation(4));
         this.activities = activities;
     }
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Task}.
-     *
-     * @param {PerformsActivities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link Actor}
-     * @see {@link PerformsActivities}
-     */
     performAs(actor) {
         return actor.attemptsTo(...this.activities);
     }
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link Activity}.
-     *
-     * @returns {string}
-     */
-    toString() {
-        return this.description;
-    }
 }
 /**
  * @package
  */
 class NotImplementedTask extends Task {
     constructor(description) {
-        super();
-        this.description = description;
+        super(description, Task.callerLocation(4));
     }
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Task}.
-     *
-     * @param {PerformsActivities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link Actor}
-     * @see {@link PerformsActivities}
-     */
     performAs(actor) {
         return Promise.reject(new errors_1.ImplementationPendingError(`A task where "${this.toString()}" has not been implemented yet`));
     }
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link Activity}.
-     *
-     * @returns {string}
-     */
-    toString() {
-        return this.description;
-    }
 }
 //# sourceMappingURL=Task.js.map

package/lib/screenplay/Task.js.map

@@ -1 +1 @@
-{"version":3,"file":"Task.js","sourceRoot":"","sources":["../../src/screenplay/Task.ts"],"names":[],"mappings":";;;AAAA,sCAAuD;AAIvD;;;;;;;;GAQG;AACH,MAAsB,IAAI;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,KAAK,CAAC,WAAmB,EAAE,GAAG,UAAsB;QACvD,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC;YACxB,CAAC,CAAC,IAAI,wBAAwB,CAAC,WAAW,EAAE,UAAU,CAAC;YACvD,CAAC,CAAC,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;CAcJ;AAjDD,oBAiDC;AAED;;GAEG;AACH,MAAM,wBAAyB,SAAQ,IAAI;IACvC,YAAoB,WAAmB,EAAU,UAAsB;QACnE,KAAK,EAAE,CAAC;QADQ,gBAAW,GAAX,WAAW,CAAQ;QAAU,eAAU,GAAV,UAAU,CAAY;IAEvE,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAyB;QAC/B,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,kBAAmB,SAAQ,IAAI;IACjC,YAAoB,WAAmB;QACnC,KAAK,EAAE,CAAC;QADQ,gBAAW,GAAX,WAAW,CAAQ;IAEvC,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAyB;QAC/B,OAAO,OAAO,CAAC,MAAM,CACjB,IAAI,mCAA0B,CAAC,iBAAkB,IAAI,CAAC,QAAQ,EAAG,gCAAgC,CAAC,CACrG,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ"}
+{"version":3,"file":"Task.js","sourceRoot":"","sources":["../../src/screenplay/Task.ts"],"names":[],"mappings":";;;AAAA,sCAAuD;AAEvD,yCAAsC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwKG;AACH,MAAsB,IAAK,SAAQ,mBAAQ;IAEvC;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,WAAmB,EAAE,GAAG,UAAsB;QACvD,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC;YACxB,CAAC,CAAC,IAAI,wBAAwB,CAAC,WAAW,EAAE,UAAU,CAAC;YACvD,CAAC,CAAC,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;CAaJ;AA5BD,oBA4BC;AAED;;GAEG;AACH,MAAM,wBAAyB,SAAQ,IAAI;IACvC,YAAY,WAAmB,EAAU,UAAsB;QAC3D,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QADN,eAAU,GAAV,UAAU,CAAY;IAE/D,CAAC;IAED,SAAS,CAAC,KAAyB;QAC/B,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,kBAAmB,SAAQ,IAAI;IACjC,YAAY,WAAmB;QAC3B,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,SAAS,CAAC,KAAyB;QAC/B,OAAO,OAAO,CAAC,MAAM,CACjB,IAAI,mCAA0B,CAAC,iBAAkB,IAAI,CAAC,QAAQ,EAAG,gCAAgC,CAAC,CACrG,CAAC;IACN,CAAC;CACJ"}

package/lib/screenplay/WithAnswerableProperties.d.ts

@@ -0,0 +1,33 @@
+import { Answerable } from './Answerable';
+import { Question } from './Question';
+/**
+ * Describes a plain JavaScript object with {@apilink Answerable} properties.
+ * Typically, used in conjunction with {@apilink RecursivelyAnswered} and {@apilink Question.fromObject}.
+ *
+ * ```ts
+ * import {
+ *   actorCalled, notes, q, Question, QuestionAdapter, WithAnswerableProperties
+ * } from '@serenity-js/core';
+ *
+ * interface RequestConfiguration {
+ *   headers: Record<string, string>;
+ * }
+ *
+ * const requestConfiguration: WithAnswerableProperties<RequestConfiguration> = {
+ *   headers: {
+ *     Authorization: q`Bearer ${ notes().get('authDetails').token }`
+ *   }
+ * }
+ *
+ * const question: QuestionAdapter<RequestConfiguration> =
+ *     Question.fromObject<RequestConfiguration>(requestConfiguration)
+ *
+ * const answer: RequestConfiguration = await actorCalled('Annie').answer(question);
+ * ```
+ *
+ * @group Questions
+ */
+export type WithAnswerableProperties<T> = T extends null | undefined ? T : T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? Answerable<A> : T extends object ? {
+    [K in keyof T]: WithAnswerableProperties<T[K]>;
+} : Answerable<T>;
+//# sourceMappingURL=WithAnswerableProperties.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WithAnswerableProperties.d.ts","sourceRoot":"","sources":["../../src/screenplay/WithAnswerableProperties.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAClC,CAAC,SAAS,IAAI,GAAG,SAAS,GAAG,CAAC,GAC1B,CAAC,SAAS,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GACvF,CAAC,SAAS,MAAM,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACjE,UAAU,CAAC,CAAC,CAAC,CAC5B"}

package/lib/screenplay/WithAnswerableProperties.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=WithAnswerableProperties.js.map

package/lib/screenplay/WithAnswerableProperties.js.map

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