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

package/lib/screenplay/Actor.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Actor = void 0;
+const tiny_types_1 = require("tiny-types");
+const errors_1 = require("../errors");
+const events_1 = require("../events");
+const io_1 = require("../io");
+const model_1 = require("../model");
+const screenplay_1 = require("../screenplay");
+const Activity_1 = require("./Activity");
+const Question_1 = require("./Question");
+/**
+ * **Actors** represent **people** and **external systems** interacting with the system under test.
+ * Their role is to perform {@apilink Activity|activities} that demonstrate how to accomplish a given goal.
+ *
+ * Actors are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Ability|Abilities}, {@apilink Interaction|Interactions}, {@apilink Task|Tasks}, and {@apilink Question|Questions}.
+ * Actors are also the first thing you see in a typical Serenity/JS test scenario.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Cast}
+ * - {@apilink Stage}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ * - {@apilink Interaction|Interactions}
+ * - {@apilink Task|Tasks}
+ * - {@apilink Question|Questions}
+ *
+ * ## Representing people and systems as actors
+ *
+ * To use a Serenity/JS {@apilink Actor}, all you need is to say their name:
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * actorCalled('Alice')
+ * // returns: Actor
+ * ```
+ *
+ * Serenity/JS actors perform within the scope of a test scenario, so the first time you invoke {@apilink actorCalled},
+ * Serenity/JS instantiates a new actor from the default {@apilink Cast} of actors (or any custom cast you might have {@apilink configured|configured}).
+ * Any subsequent invocations of this function within the scope of the same test scenario retrieve the already instantiated actor, identified by their name.
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ *
+ * actorCalled('Alice')    // instantiates Alice
+ * actorCalled('Bob')      // instantiates Bob
+ * actorCalled('Alice')    // retrieves Alice, since she's already been instantiated
+ * ```
+ *
+ * Serenity/JS scenarios can involve as many or as few actors as you need to model the given business workflow.
+ * For example, you might want to use **multiple actors** in test scenarios that model how **different people** perform different parts of a larger business process, such as reviewing and approving a loan application.
+ * It is also quite common to introduce **supporting actors** to perform **administrative tasks**, like setting up test data and environment, or **audit tasks**, like checking the logs or messages emitted to a message queue
+ * by the system under test.
+ *
+ * :::info The Stan Lee naming convention
+ * Actor names can be much more than just simple identifiers like `Alice` or `Bob`. While you can give your actors any names you like, a good convention to follow is to give them
+ * names indicating the [personae](https://articles.uie.com/goodwin_interview/) they represent or the role they play in the system.
+ *
+ * Just like the characters in [Stan Lee](https://en.wikipedia.org/wiki/Stan_Lee) graphic novels,
+ * actors in Serenity/JS test scenarios are often given alliterate names as a mnemonic device.
+ * Names like "Adam the Admin", "Edna the Editor", "Trevor the Traveller", are far more memorable than a generic "UI user" or "API user".
+ * They're also much easier for people to associate with the context, constraints, and affordances of the given actor.
+ * :::
+ *
+ * @group Screenplay Pattern
+ */
+class Actor {
+    constructor(name, stage, abilities = new Map()) {
+        this.name = name;
+        this.stage = stage;
+        this.abilities = abilities;
+    }
+    /**
+     * Retrieves actor's {@apilink Ability} of `abilityType`, or one that extends `abilityType`.
+     *
+     * Please note that this method performs an {@apilink instanceof} check against abilities
+     * given to this actor via {@apilink Actor.whoCan}.
+     *
+     * Please also note that {@apilink Actor.whoCan} performs the same check when abilities are assigned to the actor
+     * to ensure the actor has at most one instance of a given ability type.
+     *
+     * @param abilityType
+     */
+    abilityTo(abilityType) {
+        const found = this.findAbilityTo(abilityType);
+        if (!found) {
+            if (this.abilities.size > 0) {
+                throw new errors_1.ConfigurationError(`${this.name} can ${Array.from(this.abilities.keys()).map(type => type.name).join(', ')}. ` +
+                    `They can't, however, ${abilityType.name} yet. ` +
+                    `Did you give them the ability to do so?`);
+            }
+            throw new errors_1.ConfigurationError(`${this.name} can't ${abilityType.name} yet. ` +
+                `Did you give them the ability to do so?`);
+        }
+        return found;
+    }
+    /**
+     * Instructs the actor to attempt to perform a number of {@apilink Activity|activities},
+     * so either {@apilink Task|Tasks} or {@apilink Interaction|Interactions}),
+     * one by one.
+     *
+     * @param {...activities: Activity[]} activities
+     */
+    attemptsTo(...activities) {
+        return activities
+            .map(activity => new TrackedActivity(activity, this.stage))
+            .reduce((previous, current) => {
+            return previous
+                // synchronise async operations like taking screenshots
+                .then(() => this.stage.waitForNextCue())
+                .then(() => {
+                /* todo: add an execution strategy */
+                return current.performAs(this);
+            });
+        }, this.initialiseAbilities());
+    }
+    /**
+     * Gives this Actor a list of {@apilink Ability|abilities} they can use
+     * to interact with the system under test or the test environment.
+     *
+     * @param abilities
+     *  A vararg list of abilities to give the actor
+     *
+     * @returns
+     *  The actor with newly gained abilities
+     *
+     * @throws {@apilink ConfigurationError}
+     *  Throws a ConfigurationError if the actor already has an ability of this type.
+     */
+    whoCan(...abilities) {
+        abilities.forEach(ability => this.acquireAbility(ability));
+        return this;
+    }
+    /**
+     * @param answerable -
+     *  An {@apilink Answerable} to answer (resolve the value of).
+     *
+     * @returns
+     *  The answer to the Answerable
+     */
+    answer(answerable) {
+        function isAPromise(v) {
+            return Object.prototype.hasOwnProperty.call(v, 'then');
+        }
+        function isDefined(v) {
+            return !(v === undefined || v === null);
+        }
+        if (isDefined(answerable) && isAPromise(answerable)) {
+            return answerable;
+        }
+        if (isDefined(answerable) && Question_1.Question.isAQuestion(answerable)) {
+            return this.answer(answerable.answeredBy(this));
+        }
+        return Promise.resolve(answerable);
+    }
+    /**
+     * Announce collection of an {@apilink Artifact} so that it can be picked up by a {@apilink StageCrewMember}.
+     *
+     * @param artifact
+     * @param name
+     */
+    collect(artifact, name) {
+        this.stage.announce(new events_1.ActivityRelatedArtifactGenerated(this.stage.currentSceneId(), this.stage.currentActivityId(), this.nameFrom(name || new model_1.Name(artifact.constructor.name)), artifact, this.stage.currentTime()));
+    }
+    /**
+     * Instructs the actor to invoke {@apilink Discardable.discard} method on any
+     * {@apilink Discardable} {@apilink Ability} it's been configured with.
+     */
+    dismiss() {
+        return this.findAbilitiesOfType('discard')
+            .reduce((previous, ability) => previous.then(() => ability.discard()), Promise.resolve(void 0));
+    }
+    /**
+     * Returns a human-readable, string representation of this actor and their abilities.
+     *
+     * **PRO TIP:** To get the name of the actor, use {@apilink Actor.name}
+     */
+    toString() {
+        const abilities = Array.from(this.abilities.values()).map(ability => ability.constructor.name);
+        return `Actor(name=${this.name}, abilities=[${abilities.join(', ')}])`;
+    }
+    initialiseAbilities() {
+        return this.findAbilitiesOfType('initialise', 'isInitialised')
+            .filter(ability => !ability.isInitialised())
+            .reduce((previous, ability) => previous
+            .then(() => ability.initialise())
+            .catch(error => {
+            throw new errors_1.TestCompromisedError(`${this.name} couldn't initialise the ability to ${ability.constructor.name}`, error);
+        }), Promise.resolve(void 0));
+    }
+    findAbilitiesOfType(...methodNames) {
+        const abilitiesFrom = (map) => Array.from(map.values());
+        const abilitiesWithDesiredMethods = (ability) => methodNames.every(methodName => typeof (ability[methodName]) === 'function');
+        return abilitiesFrom(this.abilities)
+            .filter(abilitiesWithDesiredMethods);
+    }
+    findAbilityTo(doSomething) {
+        const abilityType = this.mostGenericTypeOf(doSomething);
+        return this.abilities.get(abilityType);
+    }
+    acquireAbility(ability) {
+        if (!(ability instanceof screenplay_1.Ability)) {
+            throw new errors_1.ConfigurationError(`Custom abilities must extend Ability from '@serenity-js/core'. Received ${(0, io_1.typeOf)(ability)}`);
+        }
+        const abilityType = this.mostGenericTypeOf(ability.constructor);
+        this.abilities.set(abilityType, ability);
+    }
+    mostGenericTypeOf(abilityType) {
+        const parentType = Object.getPrototypeOf(abilityType);
+        return !parentType || parentType === screenplay_1.Ability
+            ? abilityType
+            : this.mostGenericTypeOf(parentType);
+    }
+    /**
+     * Instantiates a {@apilink Name} based on the string value of the parameter,
+     * or returns the argument if it's already an instance of {@apilink Name}.
+     *
+     * @param maybeName
+     */
+    nameFrom(maybeName) {
+        return typeof maybeName === 'string'
+            ? new model_1.Name(maybeName)
+            : maybeName;
+    }
+}
+exports.Actor = Actor;
+class ActivityDescriber {
+    describe(activity, actor) {
+        const template = activity.toString() === ({}).toString()
+            ? `#actor performs ${activity.constructor.name}`
+            : activity.toString();
+        return new model_1.Name(this.includeActorName(template, actor));
+    }
+    includeActorName(template, actor) {
+        return template.replace('#actor', actor.name);
+    }
+}
+class OutcomeMatcher {
+    outcomeFor(error) {
+        return (0, tiny_types_1.match)(error)
+            .when(errors_1.ImplementationPendingError, _ => new model_1.ImplementationPending(error))
+            .when(errors_1.TestCompromisedError, _ => new model_1.ExecutionCompromised(error))
+            .when(errors_1.AssertionError, _ => new model_1.ExecutionFailedWithAssertionError(error))
+            .when(Error, _ => /AssertionError/.test(error.constructor.name) // mocha
+            ? new model_1.ExecutionFailedWithAssertionError(error)
+            : new model_1.ExecutionFailedWithError(error))
+            .else(_ => new model_1.ExecutionFailedWithError(error));
+    }
+}
+class TrackedActivity extends Activity_1.Activity {
+    constructor(activity, stage) {
+        super(activity.toString(), activity.instantiationLocation());
+        this.activity = activity;
+        this.stage = stage;
+    }
+    performAs(actor) {
+        const sceneId = this.stage.currentSceneId();
+        const details = new model_1.ActivityDetails(TrackedActivity.describer.describe(this.activity, actor), this.activity.instantiationLocation());
+        const activityId = this.stage.assignNewActivityId(details);
+        const [activityStarts, activityFinished] = this.activity instanceof screenplay_1.Interaction
+            ? [events_1.InteractionStarts, events_1.InteractionFinished]
+            : [events_1.TaskStarts, events_1.TaskFinished];
+        return Promise.resolve()
+            .then(() => this.stage.announce(new activityStarts(sceneId, activityId, details, this.stage.currentTime())))
+            .then(() => this.activity.performAs(actor))
+            .then(() => {
+            const outcome = new model_1.ExecutionSuccessful();
+            this.stage.announce(new activityFinished(sceneId, activityId, details, outcome, this.stage.currentTime()));
+        })
+            .catch(error => {
+            const outcome = TrackedActivity.outcomes.outcomeFor(error);
+            this.stage.announce(new activityFinished(sceneId, activityId, details, outcome, this.stage.currentTime()));
+            throw error;
+        });
+    }
+}
+TrackedActivity.describer = new ActivityDescriber();
+TrackedActivity.outcomes = new OutcomeMatcher();
+//# sourceMappingURL=Actor.js.map

package/lib/screenplay/Actor.js.map

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

package/lib/screenplay/Answerable.d.ts

@@ -1,11 +1,9 @@
 import { Question } from './Question';
 /**
- * @desc
- *  A union type that provides a convenient way to represent any value
- *  that can be resolved by {@link Actor#answer}.
+ * A union type that provides a convenient way to represent any value
+ * that can be resolved by {@apilink Actor.answer}.
  *
- * @public
- *
- * @typedef {Question<Promise<T>> | Question<T> | Promise<T> | T} Answerable<T>
+ * @group Questions
  */
-export declare type Answerable<T> = Question<Promise<T>> | Question<T> | Promise<T> | T;
+export type Answerable<T> = Question<Promise<T>> | Question<T> | Promise<T> | T;
+//# sourceMappingURL=Answerable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Answerable.d.ts","sourceRoot":"","sources":["../../src/screenplay/Answerable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC"}

package/lib/screenplay/Answered.d.ts

@@ -0,0 +1,13 @@
+import { Question } from './Question';
+/**
+ * Describes the type of answer a given {@apilink Answerable} would
+ * resolve to when given to {@apilink Actor.answer}.
+ *
+ * ```ts
+ * Answered<Answerable<T>> === T
+ * ```
+ *
+ * @group Questions
+ */
+export type Answered<T> = T extends null | undefined ? T : T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? Awaited<A> : T;
+//# sourceMappingURL=Answered.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Answered.d.ts","sourceRoot":"","sources":["../../src/screenplay/Answered.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAClB,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,OAAO,CAAC,CAAC,CAAC,GACpF,CAAC,CAAC"}

package/lib/screenplay/{Ability.js → Answered.js}

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

package/lib/screenplay/Answered.js.map

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

package/lib/screenplay/Interaction.d.ts

@@ -1,27 +1,90 @@
+import { UsesAbilities } from './abilities';
 import { Activity } from './Activity';
-import { AnswersQuestions, CollectsArtifacts, UsesAbilities } from './actor';
+import { CollectsArtifacts } from './artifacts';
+import { AnswersQuestions } from './questions';
 /**
- * @desc
- *  Directly exercises the {@link Actor}'s {@link Ability} to interact
- *  with the System Under Test.
+ * **Interactions** are low-level {@apilink Activity|activities} that encapsulate
+ * a handful of instructions for an {@apilink Actor|actor} on how to use their {@apilink Ability|abilities}
+ * to perform an individual interaction with the given interface of the system under test.
  *
- * @implements {Activity}
- * @see {@link Ability}
- * @see {@link Actor}
+ * :::tip Tasks or interactions?
+ * Because of their low-level nature, interactions are named using the vocabulary of the [solution domain](https://blog.mattwynne.net/2013/01/17/the-problem-with-solutions/),
+ * and represent an individual interaction with the given interface, e.g. {@apilink Click}, {@apilink Enter}, or {@apilink Send}.
+ *
+ * Interactions follow the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle) which means that they do _one thing and one thing only_.
+ * If you're considering implementing an "interaction" that performs more than one logical activity, e.g. checks if the button is visible and then clicks on it if is,
+ * consider using separate interactions for separate responsibilities and then composing them using a {@apilink Task|task}.
+ * :::
+ *
+ * Interactions are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Ability|Abilities}, {@apilink Question|Questions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actor|Actor}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ *
+ * ## Writing a custom interaction
+ *
+ * [Serenity/JS modules](/handbook/about/architecture) ship with dozens of interactions to help you compose your test scenarios.
+ * However, if you need to interact with a non-standard interface, or want to create a flavour of a given interaction that behaves slightly differently than the built-in version,
+ * you can easily create your own implementations using the {@apilink Interaction.where} factory method.
+ *
+ * ```ts
+ * import { Actor, Interaction } from '@serenity-js/core'
+ * import { BrowseTheWeb, Page } from '@serenity-js/web'
+ *
+ * export const ClearLocalStorage = () =>
+ *   Interaction.where(`#actor clears local storage`, async (actor: Actor) => {
+ *     // Interaction to ClearLocalStorage directly uses Actor's ability to BrowseTheWeb
+ *     const page: Page = await BrowseTheWeb.as(actor).currentPage()
+ *     await page.executeScript(() => window.localStorage.clear())
+ *   })
+ * ```
+ *
+ * ## Using a custom interaction
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { By, Navigate, PageElement } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ *
+ * await actorCalled('Inês')
+ *   .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *   .attemptsTo(
+ *     Navigate.to(`https://serenity-js.org`),
+ *     ClearLocalStorage(), // reported as "Inês clears local storage"
+ *   )
+ * ```
+ *
+ * @group Screenplay Pattern
  */
-export declare abstract class Interaction implements Activity {
-    static where(description: string, interaction: (actor: UsesAbilities & AnswersQuestions & CollectsArtifacts) => PromiseLike<void> | void): Interaction;
+export declare abstract class Interaction extends Activity {
+    /**
+     * @param description
+     *  Description to be used when reporting this interaction, for example `#actor clears local storage`.
+     *  Note that `#actor` will be replaced with the name of the actor performing this interaction.
+     *
+     * @param interaction
+     */
+    static where(description: string, interaction: (actor: UsesAbilities & AnswersQuestions & CollectsArtifacts) => Promise<void> | void): Interaction;
     /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Interaction}.
+     * Instructs the provided {@apilink Actor} to perform this {@apilink Interaction}.
      *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     * @returns {Promise<void>}
+     * #### Learn more
+     * - {@apilink Actor}
+     * - {@apilink PerformsActivities}
+     * - {@apilink UsesAbilities}
+     * - {@apilink AnswersQuestions}
      *
-     * @see {@link Actor}
-     * @see {@link UsesAbilities}
-     * @see {@link AnswersQuestions}
+     * @param actor
      */
-    abstract performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void>;
+    abstract performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
 }
+//# sourceMappingURL=Interaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Interaction.d.ts","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,8BAAsB,WAAY,SAAQ,QAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACnG,WAAW;IAId;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAC7E"}

package/lib/screenplay/Interaction.js

@@ -1,16 +1,78 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Interaction = void 0;
+const Activity_1 = require("./Activity");
 /**
- * @desc
- *  Directly exercises the {@link Actor}'s {@link Ability} to interact
- *  with the System Under Test.
+ * **Interactions** are low-level {@apilink Activity|activities} that encapsulate
+ * a handful of instructions for an {@apilink Actor|actor} on how to use their {@apilink Ability|abilities}
+ * to perform an individual interaction with the given interface of the system under test.
  *
- * @implements {Activity}
- * @see {@link Ability}
- * @see {@link Actor}
+ * :::tip Tasks or interactions?
+ * Because of their low-level nature, interactions are named using the vocabulary of the [solution domain](https://blog.mattwynne.net/2013/01/17/the-problem-with-solutions/),
+ * and represent an individual interaction with the given interface, e.g. {@apilink Click}, {@apilink Enter}, or {@apilink Send}.
+ *
+ * Interactions follow the [Single Responsibility Principle](https://en.wikipedia.org/wiki/Single_responsibility_principle) which means that they do _one thing and one thing only_.
+ * If you're considering implementing an "interaction" that performs more than one logical activity, e.g. checks if the button is visible and then clicks on it if is,
+ * consider using separate interactions for separate responsibilities and then composing them using a {@apilink Task|task}.
+ * :::
+ *
+ * Interactions are the core building block of the [Screenplay Pattern](/handbook/design/screenplay-pattern),
+ * along with {@apilink Actor|Actors}, {@apilink Ability|Abilities}, {@apilink Question|Questions}, and {@apilink Task|Tasks}.
+ *
+ * ![Screenplay Pattern](/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - {@apilink Actor|Actor}
+ * - {@apilink Ability|Abilities}
+ * - {@apilink Activity|Activities}
+ *
+ * ## Writing a custom interaction
+ *
+ * [Serenity/JS modules](/handbook/about/architecture) ship with dozens of interactions to help you compose your test scenarios.
+ * However, if you need to interact with a non-standard interface, or want to create a flavour of a given interaction that behaves slightly differently than the built-in version,
+ * you can easily create your own implementations using the {@apilink Interaction.where} factory method.
+ *
+ * ```ts
+ * import { Actor, Interaction } from '@serenity-js/core'
+ * import { BrowseTheWeb, Page } from '@serenity-js/web'
+ *
+ * export const ClearLocalStorage = () =>
+ *   Interaction.where(`#actor clears local storage`, async (actor: Actor) => {
+ *     // Interaction to ClearLocalStorage directly uses Actor's ability to BrowseTheWeb
+ *     const page: Page = await BrowseTheWeb.as(actor).currentPage()
+ *     await page.executeScript(() => window.localStorage.clear())
+ *   })
+ * ```
+ *
+ * ## Using a custom interaction
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { By, Navigate, PageElement } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ *
+ * await actorCalled('Inês')
+ *   .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *   .attemptsTo(
+ *     Navigate.to(`https://serenity-js.org`),
+ *     ClearLocalStorage(), // reported as "Inês clears local storage"
+ *   )
+ * ```
+ *
+ * @group Screenplay Pattern
  */
-class Interaction {
+class Interaction extends Activity_1.Activity {
+    /**
+     * @param description
+     *  Description to be used when reporting this interaction, for example `#actor clears local storage`.
+     *  Note that `#actor` will be replaced with the name of the actor performing this interaction.
+     *
+     * @param interaction
+     */
     static where(description, interaction) {
         return new DynamicallyGeneratedInteraction(description, interaction);
     }
@@ -21,20 +83,9 @@ exports.Interaction = Interaction;
  */
 class DynamicallyGeneratedInteraction extends Interaction {
     constructor(description, interaction) {
-        super();
-        this.description = description;
+        super(description, Interaction.callerLocation(4));
         this.interaction = interaction;
     }
-    /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this {@link Interaction}.
-     *
-     * @param {Actor} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link Actor}
-     */
     performAs(actor) {
         try {
             return Promise.resolve(this.interaction(actor));
@@ -43,14 +94,5 @@ class DynamicallyGeneratedInteraction extends Interaction {
             return Promise.reject(error);
         }
     }
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link Activity}.
-     *
-     * @returns {string}
-     */
-    toString() {
-        return this.description;
-    }
 }
 //# sourceMappingURL=Interaction.js.map

package/lib/screenplay/Interaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interaction.js","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;GAQG;AACH,MAAsB,WAAW;IAC7B,MAAM,CAAC,KAAK,CACR,WAAmB,EACnB,WAAsG;QAEtG,OAAO,IAAI,+BAA+B,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACzE,CAAC;CAeJ;AArBD,kCAqBC;AAED;;GAEG;AACH,MAAM,+BAAgC,SAAQ,WAAW;IACrD,YACqB,WAAmB,EACnB,WAAsG;QAEvH,KAAK,EAAE,CAAC;QAHS,gBAAW,GAAX,WAAW,CAAQ;QACnB,gBAAW,GAAX,WAAW,CAA2F;IAG3H,CAAC;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,KAAY;QAClB,IAAI;YACA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;SACnD;QAAC,OAAO,KAAK,EAAE;YACZ,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SAChC;IACL,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ"}
+{"version":3,"file":"Interaction.js","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":";;;AACA,yCAAsC;AAItC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAsB,WAAY,SAAQ,mBAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAmB,EACnB,WAAkG;QAElG,OAAO,IAAI,+BAA+B,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACzE,CAAC;CAcJ;AA5BD,kCA4BC;AAED;;GAEG;AACH,MAAM,+BAAgC,SAAQ,WAAW;IACrD,YACI,WAAmB,EACF,WAAkG;QAEnH,KAAK,CAAC,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QAFjC,gBAAW,GAAX,WAAW,CAAuF;IAGvH,CAAC;IAED,SAAS,CAAC,KAA2D;QACjE,IAAI;YACA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;SACnD;QAAC,OAAO,KAAK,EAAE;YACZ,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;SAChC;IACL,CAAC;CACJ"}

package/lib/screenplay/Optional.d.ts

@@ -1,29 +1,26 @@
 import { Answerable } from './Answerable';
 /**
- * @desc
- *  `Optional` is a container object, which holds a value that may or may not be "present",
+ * `Optional` is a container object, which holds a value that may or may not be "present",
  *
- *  The meaning of being "present" depends on the context and typically means a value that:
- *  - is other than `null` or `undefined`
- *  - is retrievable, so retrieving it doesn't throw any errors
+ * The meaning of being "present" depends on the context and typically means a value that:
+ * - is other than `null` or `undefined`
+ * - is retrievable, so retrieving it doesn't throw any errors
  *
- *  Additionally, `Optional` can also have a context-specific meaning. For example, `Optional#isPresent()`:
- *  - in the context of a `PageElement` means that the element exists in the DOM.
- *  - in the context of a `ModalWindow` means that the modal window is open.
- *  - in the case of a REST API response, `LastResponse.body().books[0].author.name.isPresent()`
- *    will inform us if a given entry exists (so `books[0].author.name`),
- *    and if all the links of the property chain leading to the entry of interest exist too
- *    (so `books` is present, and so is `books[0]`, `books[0].author`, `books[0].author.name`).
+ * Additionally, `Optional` can also have a context-specific meaning. For example, `Optional#isPresent()`:
+ * - in the context of a `PageElement` means that the element exists in the DOM.
+ * - in the context of a `ModalWindow` means that the modal window is open.
+ * - in the case of a REST API response, `LastResponse.body().books[0].author.name.isPresent()`
+ *   will inform us if a given entry exists (so `books[0].author.name`),
+ *   and if all the links of the property chain leading to the entry of interest exist too
+ *   (so `books` is present, and so is `books[0]`, `books[0].author`, `books[0].author.name`).
  *
- * @public
+ * @group Questions
  */
 export interface Optional {
     /**
-     * @desc
-     *  Returns an {@link Answerable} that resolves to `true` when the optional value
-     *  is present, `false` otherwise.
-     *
-     * @returns {Answerable<boolean>}
+     * Returns an {@apilink Answerable} that resolves to `true` when the optional value
+     * is present, `false` otherwise.
      */
     isPresent(): Answerable<boolean>;
 }
+//# sourceMappingURL=Optional.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Optional.d.ts","sourceRoot":"","sources":["../../src/screenplay/Optional.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,QAAQ;IACrB;;;OAGG;IACH,SAAS,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;CACpC"}