@serenity-js/core 3.41.2 → 3.42.1

package/esm/screenplay/Answerable.d.ts

@@ -0,0 +1,9 @@
+import type { Question } from './Question.js';
+/**
+ * A union type that provides a convenient way to represent any value
+ * that can be resolved by [`Actor.answer`](https://serenity-js.org/api/core/class/Actor/#answer).
+ *
+ * @group Questions
+ */
+export type Answerable<T> = Question<Promise<T>> | Question<T> | Promise<T> | T;
+//# sourceMappingURL=Answerable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Answerable.d.ts","sourceRoot":"","sources":["../../src/screenplay/Answerable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;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/esm/screenplay/Answerable.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Answerable.js.map

package/esm/screenplay/Answerable.js.map

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

package/esm/screenplay/Answered.d.ts

@@ -0,0 +1,13 @@
+import type { Question } from './Question.js';
+/**
+ * Describes the type of answer a given [`Answerable`](https://serenity-js.org/api/core/#Answerable) would
+ * resolve to when given to [`Actor.answer`](https://serenity-js.org/api/core/class/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/esm/screenplay/Answered.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Answered.d.ts","sourceRoot":"","sources":["../../src/screenplay/Answered.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;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/esm/screenplay/Answered.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Answered.js.map

package/esm/screenplay/Answered.js.map

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

package/esm/screenplay/Interaction.d.ts

@@ -0,0 +1,91 @@
+import type { UsesAbilities } from './abilities/index.js';
+import { Activity } from './Activity.js';
+import type { Answerable } from './Answerable.js';
+import type { CollectsArtifacts } from './artifacts/index.js';
+import type { AnswersQuestions } from './questions/index.js';
+/**
+ * **Interactions** are low-level [activities](https://serenity-js.org/api/core/class/Activity/) that encapsulate
+ * a handful of instructions for an [actor](https://serenity-js.org/api/core/class/Actor/) on how to use their [abilities](https://serenity-js.org/api/core/class/Ability/)
+ * to perform an individual interaction with the given interface of the system under test.
+ *
+ * :::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. [`Click`](https://serenity-js.org/api/web/class/Click/), [`Enter`](https://serenity-js.org/api/web/class/Enter/), or [`Send`](https://serenity-js.org/api/rest/class/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 [task](https://serenity-js.org/api/core/class/Task/).
+ * :::
+ *
+ * Interactions are the core building block of the [Screenplay Pattern](https://serenity-js.org/handbook/design/screenplay-pattern),
+ * along with [actors](https://serenity-js.org/api/core/class/Actor/), [abilities](https://serenity-js.org/api/core/class/Ability/), [questions](https://serenity-js.org/api/core/class/Question/), and [tasks](https://serenity-js.org/api/core/class/Task/).
+ *
+ * ![Screenplay Pattern](https://serenity-js.org/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [Abilities](https://serenity-js.org/api/core/class/Ability/)
+ * - [Activities](https://serenity-js.org/api/core/class/Activity/)
+ *
+ * ## Writing a custom interaction
+ *
+ * [Serenity/JS modules](https://serenity-js.org/handbook/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 [`Interaction.where`](https://serenity-js.org/api/core/class/Interaction/#where) factory method.
+ *
+ * ```ts
+ * import { Actor, Interaction, the } from '@serenity-js/core'
+ * import { BrowseTheWeb, Page } from '@serenity-js/web'
+ *
+ * export const ClearLocalStorage = () =>
+ *   Interaction.where(the`#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 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: Answerable<string>, interaction: (actor: UsesAbilities & AnswersQuestions & CollectsArtifacts) => Promise<void> | void): Interaction;
+    /**
+     * Instructs the provided [`Actor`](https://serenity-js.org/api/core/class/Actor/) to perform this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * #### Learn more
+     * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     * - [`PerformsActivities`](https://serenity-js.org/api/core/interface/PerformsActivities/)
+     * - [`UsesAbilities`](https://serenity-js.org/api/core/interface/UsesAbilities/)
+     * - [`AnswersQuestions`](https://serenity-js.org/api/core/interface/AnswersQuestions/)
+     *
+     * @param actor
+     */
+    abstract performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}
+//# sourceMappingURL=Interaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Interaction.d.ts","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,8BAAsB,WAAY,SAAQ,QAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,EAC/B,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/esm/screenplay/Interaction.js

@@ -0,0 +1,95 @@
+import { Activity } from './Activity.js';
+/**
+ * **Interactions** are low-level [activities](https://serenity-js.org/api/core/class/Activity/) that encapsulate
+ * a handful of instructions for an [actor](https://serenity-js.org/api/core/class/Actor/) on how to use their [abilities](https://serenity-js.org/api/core/class/Ability/)
+ * to perform an individual interaction with the given interface of the system under test.
+ *
+ * :::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. [`Click`](https://serenity-js.org/api/web/class/Click/), [`Enter`](https://serenity-js.org/api/web/class/Enter/), or [`Send`](https://serenity-js.org/api/rest/class/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 [task](https://serenity-js.org/api/core/class/Task/).
+ * :::
+ *
+ * Interactions are the core building block of the [Screenplay Pattern](https://serenity-js.org/handbook/design/screenplay-pattern),
+ * along with [actors](https://serenity-js.org/api/core/class/Actor/), [abilities](https://serenity-js.org/api/core/class/Ability/), [questions](https://serenity-js.org/api/core/class/Question/), and [tasks](https://serenity-js.org/api/core/class/Task/).
+ *
+ * ![Screenplay Pattern](https://serenity-js.org/images/design/serenity-js-screenplay-pattern.png)
+ *
+ * Learn more about:
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [Abilities](https://serenity-js.org/api/core/class/Ability/)
+ * - [Activities](https://serenity-js.org/api/core/class/Activity/)
+ *
+ * ## Writing a custom interaction
+ *
+ * [Serenity/JS modules](https://serenity-js.org/handbook/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 [`Interaction.where`](https://serenity-js.org/api/core/class/Interaction/#where) factory method.
+ *
+ * ```ts
+ * import { Actor, Interaction, the } from '@serenity-js/core'
+ * import { BrowseTheWeb, Page } from '@serenity-js/web'
+ *
+ * export const ClearLocalStorage = () =>
+ *   Interaction.where(the`#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 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, interaction) {
+        return new DynamicallyGeneratedInteraction(description, interaction);
+    }
+}
+/**
+ * @package
+ */
+class DynamicallyGeneratedInteraction extends Interaction {
+    interaction;
+    constructor(description, interaction) {
+        super(description, Interaction.callerLocation(4));
+        this.interaction = interaction;
+    }
+    performAs(actor) {
+        try {
+            return Promise.resolve(this.interaction(actor));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+}
+//# sourceMappingURL=Interaction.js.map

package/esm/screenplay/Interaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Interaction.js","sourceRoot":"","sources":["../../src/screenplay/Interaction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAKzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,OAAgB,WAAY,SAAQ,QAAQ;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACR,WAA+B,EAC/B,WAAkG;QAElG,OAAO,IAAI,+BAA+B,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACzE,CAAC;CAcJ;AAED;;GAEG;AACH,MAAM,+BAAgC,SAAQ,WAAW;IAGhC;IAFrB,YACI,WAA+B,EACd,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,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;IACL,CAAC;CACJ"}

package/esm/screenplay/Optional.d.ts

@@ -0,0 +1,26 @@
+import type { Answerable } from './Answerable.js';
+/**
+ * `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
+ *
+ * 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`).
+ *
+ * @group Questions
+ */
+export interface Optional {
+    /**
+     * Returns an [`Answerable`](https://serenity-js.org/api/core/#Answerable) that resolves to `true` when the optional value
+     * is present, `false` otherwise.
+     */
+    isPresent(): Answerable<boolean>;
+}
+//# sourceMappingURL=Optional.d.ts.map

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

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

package/esm/screenplay/Optional.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Optional.js.map

package/esm/screenplay/Optional.js.map

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