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

package/lib/screenplay/models/SelectOption.d.ts

@@ -0,0 +1,25 @@
+import { TinyType } from 'tiny-types';
+/**
+ * Describes the [`<option />`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+ * elements to select.
+ *
+ * ## Learn more
+ *
+ * - {@apilink Select}
+ * - {@apilink Selected}
+ * - {@apilink PageElement.selectOptions}
+ * - {@apilink PageElement.selectedOptions}
+ *
+ * @group Models
+ */
+export declare class SelectOption extends TinyType {
+    readonly label?: string;
+    readonly value?: string;
+    readonly selected?: boolean;
+    readonly disabled?: boolean;
+    static withLabel(label: string): SelectOption;
+    static withValue(value: string): SelectOption;
+    constructor(label?: string, value?: string, selected?: boolean, disabled?: boolean);
+    toString(): string;
+}
+//# sourceMappingURL=SelectOption.d.ts.map

package/lib/screenplay/models/SelectOption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectOption.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/SelectOption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,SAAQ,QAAQ;aAWlB,KAAK,CAAC,EAAE,MAAM;aACd,KAAK,CAAC,EAAE,MAAM;aACd,QAAQ,CAAC,EAAE,OAAO;aAClB,QAAQ,CAAC,EAAE,OAAO;IAZtC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAI7C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;gBAKzB,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,OAAO,EAClB,QAAQ,CAAC,EAAE,OAAO;IAKtC,QAAQ,IAAI,MAAM;CAGrB"}

package/lib/screenplay/models/SelectOption.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SelectOption = void 0;
+const tiny_types_1 = require("tiny-types");
+/**
+ * Describes the [`<option />`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+ * elements to select.
+ *
+ * ## Learn more
+ *
+ * - {@apilink Select}
+ * - {@apilink Selected}
+ * - {@apilink PageElement.selectOptions}
+ * - {@apilink PageElement.selectedOptions}
+ *
+ * @group Models
+ */
+class SelectOption extends tiny_types_1.TinyType {
+    static withLabel(label) {
+        return new SelectOption(label);
+    }
+    static withValue(value) {
+        return new SelectOption(undefined, value);
+    }
+    constructor(label, value, selected, disabled) {
+        super();
+        this.label = label;
+        this.value = value;
+        this.selected = selected;
+        this.disabled = disabled;
+    }
+    toString() {
+        return `<option /> element with label: ${this.label}, value: ${this.value}`;
+    }
+}
+exports.SelectOption = SelectOption;
+//# sourceMappingURL=SelectOption.js.map

package/lib/screenplay/models/SelectOption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectOption.js","sourceRoot":"","sources":["../../../src/screenplay/models/SelectOption.ts"],"names":[],"mappings":";;;AAAA,2CAAsC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAa,YAAa,SAAQ,qBAAQ;IAEtC,MAAM,CAAC,SAAS,CAAC,KAAa;QAC1B,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,KAAa;QAC1B,OAAO,IAAI,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,YACoB,KAAc,EACd,KAAc,EACd,QAAkB,EAClB,QAAkB;QAElC,KAAK,EAAE,CAAC;QALQ,UAAK,GAAL,KAAK,CAAS;QACd,UAAK,GAAL,KAAK,CAAS;QACd,aAAQ,GAAR,QAAQ,CAAU;QAClB,aAAQ,GAAR,QAAQ,CAAU;IAGtC,CAAC;IAED,QAAQ;QACJ,OAAO,kCAAmC,IAAI,CAAC,KAAM,YAAa,IAAI,CAAC,KAAM,EAAE,CAAC;IACpF,CAAC;CACJ;AAtBD,oCAsBC"}

package/lib/screenplay/models/Switchable.d.ts

@@ -0,0 +1,23 @@
+import { SwitchableOrigin } from './SwitchableOrigin';
+/**
+ * Describes a Serenity/JS model object that can be switched _to_ and switched back _from_
+ * using the {@apilink Task|task} to {@apilink Switch}.
+ *
+ * Examples of switchable models include a {@apilink Page} and {@apilink PageElement}.
+ *
+ * ## Learn more
+ * - {@apilink Page}
+ * - {@apilink PageElement}
+ * - {@apilink Switch}
+ *
+ * @group Models
+ */
+export interface Switchable {
+    /**
+     * Switches the context to the object implementing this interface
+     * and returns {@apilink SwitchableOrigin} that allows for the context to be switched
+     * back when needed.
+     */
+    switchTo(): Promise<SwitchableOrigin>;
+}
+//# sourceMappingURL=Switchable.d.ts.map

package/lib/screenplay/models/Switchable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Switchable.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/Switchable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IAEvB;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACzC"}

package/lib/screenplay/{interactions/WaitBuilder.js → models/Switchable.js}

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

package/lib/screenplay/models/Switchable.js.map

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

package/lib/screenplay/models/SwitchableOrigin.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Enables the {@apilink Task} to {@apilink Switch} to perform a sequence of activities
+ * and switch back to the original context afterwards.
+ *
+ * ## Learn more
+ *
+ * - {@apilink Switch}
+ * - {@apilink Switchable}
+ *
+ * @group Models
+ */
+export interface SwitchableOrigin {
+    /**
+     * Switches the context back to the original {@apilink Switchable}
+     */
+    switchBack(): Promise<void>;
+}
+//# sourceMappingURL=SwitchableOrigin.d.ts.map

package/lib/screenplay/models/SwitchableOrigin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwitchableOrigin.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/SwitchableOrigin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAE7B;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B"}

package/lib/screenplay/{interactions/EnterBuilder.js → models/SwitchableOrigin.js}

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

package/lib/screenplay/models/SwitchableOrigin.js.map

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

package/lib/screenplay/models/dialogs/AbsentModalDialog.d.ts

@@ -0,0 +1,15 @@
+import { ModalDialog } from './ModalDialog';
+/**
+ * `AbsentModalDialog` is a [null object](https://en.wikipedia.org/wiki/Null_object_pattern)
+ * representing a {@apilink ModalDialog} that hasn't appeared yet.
+ *
+ * ## Learn more
+ * - {@apilink ModalDialog}
+ *
+ * @group Models
+ */
+export declare class AbsentModalDialog extends ModalDialog {
+    isPresent(): Promise<boolean>;
+    message(): Promise<string>;
+}
+//# sourceMappingURL=AbsentModalDialog.d.ts.map

package/lib/screenplay/models/dialogs/AbsentModalDialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbsentModalDialog.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/AbsentModalDialog.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IACxC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CAGnC"}

package/lib/screenplay/models/dialogs/AbsentModalDialog.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbsentModalDialog = void 0;
+const core_1 = require("@serenity-js/core");
+const ModalDialog_1 = require("./ModalDialog");
+/**
+ * `AbsentModalDialog` is a [null object](https://en.wikipedia.org/wiki/Null_object_pattern)
+ * representing a {@apilink ModalDialog} that hasn't appeared yet.
+ *
+ * ## Learn more
+ * - {@apilink ModalDialog}
+ *
+ * @group Models
+ */
+class AbsentModalDialog extends ModalDialog_1.ModalDialog {
+    async isPresent() {
+        return false;
+    }
+    async message() {
+        throw new core_1.LogicError(`Can't retrieve the message of a modal dialog that hasn't been handled yet`);
+    }
+}
+exports.AbsentModalDialog = AbsentModalDialog;
+//# sourceMappingURL=AbsentModalDialog.js.map

package/lib/screenplay/models/dialogs/AbsentModalDialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbsentModalDialog.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/AbsentModalDialog.ts"],"names":[],"mappings":";;;AAAA,4CAA+C;AAE/C,+CAA4C;AAE5C;;;;;;;;GAQG;AACH,MAAa,iBAAkB,SAAQ,yBAAW;IAC9C,KAAK,CAAC,SAAS;QACX,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,OAAO;QACT,MAAM,IAAI,iBAAU,CAAC,2EAA2E,CAAC,CAAC;IACtG,CAAC;CACJ;AARD,8CAQC"}

package/lib/screenplay/models/dialogs/AcceptedModalDialog.d.ts

@@ -0,0 +1,17 @@
+import { ModalDialog } from './ModalDialog';
+/**
+ * `AcceptedModalDialog` represents a {@apilink ModalDialog} that has been accepted
+ * via {@apilink ModalDialog.acceptNext}.
+ *
+ * ## Learn more
+ * - {@apilink ModalDialog}
+ *
+ * @group Models
+ */
+export declare class AcceptedModalDialog extends ModalDialog {
+    private readonly dialogMessage;
+    constructor(dialogMessage: string);
+    isPresent(): Promise<boolean>;
+    message(): Promise<string>;
+}
+//# sourceMappingURL=AcceptedModalDialog.d.ts.map

package/lib/screenplay/models/dialogs/AcceptedModalDialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcceptedModalDialog.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/AcceptedModalDialog.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM;IAK5C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CAGnC"}

package/lib/screenplay/models/dialogs/AcceptedModalDialog.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcceptedModalDialog = void 0;
+const tiny_types_1 = require("tiny-types");
+const ModalDialog_1 = require("./ModalDialog");
+/**
+ * `AcceptedModalDialog` represents a {@apilink ModalDialog} that has been accepted
+ * via {@apilink ModalDialog.acceptNext}.
+ *
+ * ## Learn more
+ * - {@apilink ModalDialog}
+ *
+ * @group Models
+ */
+class AcceptedModalDialog extends ModalDialog_1.ModalDialog {
+    constructor(dialogMessage) {
+        super();
+        this.dialogMessage = dialogMessage;
+        (0, tiny_types_1.ensure)('dialogMessage', dialogMessage, (0, tiny_types_1.isDefined)());
+    }
+    async isPresent() {
+        return true;
+    }
+    async message() {
+        return this.dialogMessage;
+    }
+}
+exports.AcceptedModalDialog = AcceptedModalDialog;
+//# sourceMappingURL=AcceptedModalDialog.js.map

package/lib/screenplay/models/dialogs/AcceptedModalDialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcceptedModalDialog.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/AcceptedModalDialog.ts"],"names":[],"mappings":";;;AAAA,2CAA+C;AAE/C,+CAA4C;AAE5C;;;;;;;;GAQG;AACH,MAAa,mBAAoB,SAAQ,yBAAW;IAChD,YAA6B,aAAqB;QAC9C,KAAK,EAAE,CAAC;QADiB,kBAAa,GAAb,aAAa,CAAQ;QAE9C,IAAA,mBAAM,EAAC,eAAe,EAAE,aAAa,EAAE,IAAA,sBAAS,GAAE,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,SAAS;QACX,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,OAAO;QACT,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;CACJ;AAbD,kDAaC"}

package/lib/screenplay/models/dialogs/DismissedModalDialog.d.ts

@@ -0,0 +1,17 @@
+import { ModalDialog } from './ModalDialog';
+/**
+ * `DismissedModalDialog` represents a {@apilink ModalDialog} that has been dismissed
+ * via {@apilink ModalDialog.dismissNext}.
+ *
+ * ## Learn more
+ * - {@apilink ModalDialog}
+ *
+ * @group Models
+ */
+export declare class DismissedModalDialog extends ModalDialog {
+    private readonly dialogMessage;
+    constructor(dialogMessage: string);
+    isPresent(): Promise<boolean>;
+    message(): Promise<string>;
+}
+//# sourceMappingURL=DismissedModalDialog.d.ts.map

package/lib/screenplay/models/dialogs/DismissedModalDialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DismissedModalDialog.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/DismissedModalDialog.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,WAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM;IAK5C,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CAGnC"}

package/lib/screenplay/models/dialogs/DismissedModalDialog.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DismissedModalDialog = void 0;
+const tiny_types_1 = require("tiny-types");
+const ModalDialog_1 = require("./ModalDialog");
+/**
+ * `DismissedModalDialog` represents a {@apilink ModalDialog} that has been dismissed
+ * via {@apilink ModalDialog.dismissNext}.
+ *
+ * ## Learn more
+ * - {@apilink ModalDialog}
+ *
+ * @group Models
+ */
+class DismissedModalDialog extends ModalDialog_1.ModalDialog {
+    constructor(dialogMessage) {
+        super();
+        this.dialogMessage = dialogMessage;
+        (0, tiny_types_1.ensure)('dialogMessage', dialogMessage, (0, tiny_types_1.isDefined)());
+    }
+    async isPresent() {
+        return true;
+    }
+    async message() {
+        return this.dialogMessage;
+    }
+}
+exports.DismissedModalDialog = DismissedModalDialog;
+//# sourceMappingURL=DismissedModalDialog.js.map

package/lib/screenplay/models/dialogs/DismissedModalDialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DismissedModalDialog.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/DismissedModalDialog.ts"],"names":[],"mappings":";;;AAAA,2CAA+C;AAE/C,+CAA4C;AAE5C;;;;;;;;GAQG;AACH,MAAa,oBAAqB,SAAQ,yBAAW;IACjD,YAA6B,aAAqB;QAC9C,KAAK,EAAE,CAAC;QADiB,kBAAa,GAAb,aAAa,CAAQ;QAE9C,IAAA,mBAAM,EAAC,eAAe,EAAE,aAAa,EAAE,IAAA,sBAAS,GAAE,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,SAAS;QACX,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,OAAO;QACT,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;CACJ;AAbD,oDAaC"}

package/lib/screenplay/models/dialogs/ModalDialog.d.ts

@@ -0,0 +1,168 @@
+import { Answerable, Interaction, Optional, Question, QuestionAdapter } from '@serenity-js/core';
+/**
+ * Manages interactions with JavaScript modal dialog windows,
+ * triggered by [window.alert](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert),
+ * [window.confirm](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm),
+ * or [`window.prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt),
+ * and stores their `message` so that it can be asserted on once the dialog is handled.
+ *
+ * Note that in order to make handling modal windows
+ * consistent across the various Web integration tools (such as Playwright, Puppeteer,
+ * WebdriverIO or Selenium), Serenity/JS works as follows:
+ * - Serenity/JS dismisses any modal dialogs by default and stores their message so that it can be asserted on.
+ * - This behaviour can be changed by invoking {@apilink ModalDialog.acceptNext}, {@apilink ModalDialog.acceptNextWithValue]], or [[ModalDialog.dismissNext} before the dialog is triggered, as per the below examples.
+ * - Serenity/JS also allows you to `Wait.until(ModalDialog, isPresent())` so that you can synchronise your tests
+ *   with modal dialogs that appear after a delay.
+ *
+ * ## Example HTML widget
+ *
+ * In the below example widget, clicking on the button results in a [confirmation dialog](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm)
+ * appearing.
+ *
+ * ```html
+ * <button id="trigger" onclick="trigger()">Trigger Alert</button>
+ * <p id="result"></p>
+ *
+ * <script>
+ *   function trigger() {
+ *     document.getElementById("result").innerHTML = (
+ *       function () {
+ *         return confirm('Continue?')
+ *           ? 'accepted'
+ *           : 'dismissed';
+ *       }
+ *     )();
+ *   }
+ * </script>
+ * ```
+ *
+ * ## Modal dialog gets dismissed by default
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Text, PageElement, ModalDialog } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * const Example = {
+ *   trigger: () =>
+ *     PageElement.located(By.id('trigger')).describedAs('the modal dialog trigger'),
+ *
+ *   result: () =>
+ *     PageElement.located(By.id('result')).describedAs('result'),
+ * }
+ *
+ * await actorCalled('Nick').attemptsTo(
+ *   Click.on(Example.trigger()),
+ *
+ *   Ensure.that(ModalDialog.lastDialogState(), equals('dismissed')),
+ *
+ *   Ensure.that(Text.of(Example.result()), equals('dismissed')),
+ * )
+ * ```
+ *
+ * ## Changing modal dialog handler
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Text, PageElement, ModalDialog } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * const Example = {
+ *   trigger: () =>
+ *     PageElement.located(By.id('trigger')).describedAs('the modal dialog trigger'),
+ *
+ *   result: () =>
+ *     PageElement.located(By.id('result')).describedAs('result'),
+ * }
+ *
+ * await actorCalled('Nick').attemptsTo(
+ *   ModalDialog.acceptNext(),
+ *   // or: ModalDialog.acceptNextWithValue('some value'),
+ *   // or: ModalDialog.dismissNext(),
+ *
+ *   Click.on(Example.trigger),
+ *
+ *   Ensure.that(ModalDialog.lastDialogState(), equals('accepted')),
+ *
+ *   Ensure.that(Text.of(Example.result), equals('accepted')),
+ * )
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink Optional}
+ *
+ * @group Models
+ */
+export declare abstract class ModalDialog implements Optional {
+    /**
+     * Returns a promise that resolves to `true`
+     * when a modal dialog has been handled, so accepted or dismissed.
+     * Returns `false` for dialogs that haven't been handled yet.
+     *
+     * Useful when a JavaScript modal dialog is generated after a delay,
+     * e.g. triggered by `setTimeout`.
+     *
+     * #### Example usage
+     *
+     * ```ts
+     * import { actorCalled, Wait } from '@serenity-js/core'
+     * import { Ensure, equals, isPresent } from '@serenity-js/assertions'
+     * import { ModalDialog } from '@serenity-js/web'
+     *
+     * await actorCalled('Nick').attemptsTo(
+     *   ModalDialog.acceptNext(),
+     *   Wait.until(ModalDialog, isPresent()),
+     *   Ensure.that(ModalDialog.lastDialogState(), equals('accepted')),
+     * )
+     * ```
+     */
+    static isPresent(): Question<Promise<boolean>>;
+    /**
+     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.acceptNext}.
+     */
+    static acceptNext(): Interaction;
+    /**
+     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.acceptNextWithValue}.
+     *
+     * @param value
+     */
+    static acceptNextWithValue(value: Answerable<string | number>): Interaction;
+    /**
+     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.dismissNext}.
+     */
+    static dismissNext(): Interaction;
+    /**
+     * {@apilink QuestionAdapter} that resolves to {@apilink ModalDialog.message} for the current {@apilink Page}.
+     */
+    static lastDialogMessage(): QuestionAdapter<string>;
+    /**
+     * {@apilink QuestionAdapter} that resolves to {@apilink ModalDialog.state} for the current {@apilink Page}.
+     */
+    static lastDialogState(): QuestionAdapter<string>;
+    /**
+     * Returns the message of the last modal dialog handled,
+     * or rejects the promise with a {@apilink LogicError}
+     * when no modal dialogs have been observed yet.
+     *
+     * @returns
+     *  Message of the last handled dialog, or a `Promise`
+     *  rejected with a {@apilink LogicError}
+     *  when no dialog has been handled yet.
+     */
+    abstract message(): Promise<string>;
+    /**
+     * Returns a promise that resolves to `true`
+     * when a modal dialog has been handled, so either accepted or dismissed.
+     * Returns `false` for dialogs that haven't been handled yet.
+     *
+     * Useful when a JavaScript modal dialog is generated after a delay,
+     * e.g. triggered by `setTimeout`.
+     */
+    abstract isPresent(): Promise<boolean>;
+    /**
+     * Returns `accepted` or `dismissed` for dialogs that have been handled,
+     * or `absent` for those that haven't been handled yet.
+     */
+    state(): string;
+}
+//# sourceMappingURL=ModalDialog.d.ts.map

package/lib/screenplay/models/dialogs/ModalDialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModalDialog.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/ModalDialog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAK,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,8BAAsB,WAAY,YAAW,QAAQ;IAEjD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,SAAS,IAAI,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAI9C;;OAEG;IACH,MAAM,CAAC,UAAU,IAAI,WAAW;IAKhC;;;;OAIG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,WAAW;IAK3E;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,WAAW;IAKjC;;OAEG;IACH,MAAM,CAAC,iBAAiB,IAAI,eAAe,CAAC,MAAM,CAAC;IAKnD;;OAEG;IACH,MAAM,CAAC,eAAe,IAAI,eAAe,CAAC,MAAM,CAAC;IAKjD;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAEtC;;;OAGG;IACH,KAAK,IAAI,MAAM;CAKlB"}

package/lib/screenplay/models/dialogs/ModalDialog.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModalDialog = void 0;
+const core_1 = require("@serenity-js/core");
+const Page_1 = require("../Page");
+/**
+ * Manages interactions with JavaScript modal dialog windows,
+ * triggered by [window.alert](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert),
+ * [window.confirm](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm),
+ * or [`window.prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt),
+ * and stores their `message` so that it can be asserted on once the dialog is handled.
+ *
+ * Note that in order to make handling modal windows
+ * consistent across the various Web integration tools (such as Playwright, Puppeteer,
+ * WebdriverIO or Selenium), Serenity/JS works as follows:
+ * - Serenity/JS dismisses any modal dialogs by default and stores their message so that it can be asserted on.
+ * - This behaviour can be changed by invoking {@apilink ModalDialog.acceptNext}, {@apilink ModalDialog.acceptNextWithValue]], or [[ModalDialog.dismissNext} before the dialog is triggered, as per the below examples.
+ * - Serenity/JS also allows you to `Wait.until(ModalDialog, isPresent())` so that you can synchronise your tests
+ *   with modal dialogs that appear after a delay.
+ *
+ * ## Example HTML widget
+ *
+ * In the below example widget, clicking on the button results in a [confirmation dialog](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm)
+ * appearing.
+ *
+ * ```html
+ * <button id="trigger" onclick="trigger()">Trigger Alert</button>
+ * <p id="result"></p>
+ *
+ * <script>
+ *   function trigger() {
+ *     document.getElementById("result").innerHTML = (
+ *       function () {
+ *         return confirm('Continue?')
+ *           ? 'accepted'
+ *           : 'dismissed';
+ *       }
+ *     )();
+ *   }
+ * </script>
+ * ```
+ *
+ * ## Modal dialog gets dismissed by default
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Text, PageElement, ModalDialog } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * const Example = {
+ *   trigger: () =>
+ *     PageElement.located(By.id('trigger')).describedAs('the modal dialog trigger'),
+ *
+ *   result: () =>
+ *     PageElement.located(By.id('result')).describedAs('result'),
+ * }
+ *
+ * await actorCalled('Nick').attemptsTo(
+ *   Click.on(Example.trigger()),
+ *
+ *   Ensure.that(ModalDialog.lastDialogState(), equals('dismissed')),
+ *
+ *   Ensure.that(Text.of(Example.result()), equals('dismissed')),
+ * )
+ * ```
+ *
+ * ## Changing modal dialog handler
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Text, PageElement, ModalDialog } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * const Example = {
+ *   trigger: () =>
+ *     PageElement.located(By.id('trigger')).describedAs('the modal dialog trigger'),
+ *
+ *   result: () =>
+ *     PageElement.located(By.id('result')).describedAs('result'),
+ * }
+ *
+ * await actorCalled('Nick').attemptsTo(
+ *   ModalDialog.acceptNext(),
+ *   // or: ModalDialog.acceptNextWithValue('some value'),
+ *   // or: ModalDialog.dismissNext(),
+ *
+ *   Click.on(Example.trigger),
+ *
+ *   Ensure.that(ModalDialog.lastDialogState(), equals('accepted')),
+ *
+ *   Ensure.that(Text.of(Example.result), equals('accepted')),
+ * )
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink Optional}
+ *
+ * @group Models
+ */
+class ModalDialog {
+    /**
+     * Returns a promise that resolves to `true`
+     * when a modal dialog has been handled, so accepted or dismissed.
+     * Returns `false` for dialogs that haven't been handled yet.
+     *
+     * Useful when a JavaScript modal dialog is generated after a delay,
+     * e.g. triggered by `setTimeout`.
+     *
+     * #### Example usage
+     *
+     * ```ts
+     * import { actorCalled, Wait } from '@serenity-js/core'
+     * import { Ensure, equals, isPresent } from '@serenity-js/assertions'
+     * import { ModalDialog } from '@serenity-js/web'
+     *
+     * await actorCalled('Nick').attemptsTo(
+     *   ModalDialog.acceptNext(),
+     *   Wait.until(ModalDialog, isPresent()),
+     *   Ensure.that(ModalDialog.lastDialogState(), equals('accepted')),
+     * )
+     * ```
+     */
+    static isPresent() {
+        return Page_1.Page.current().modalDialog().last().isPresent();
+    }
+    /**
+     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.acceptNext}.
+     */
+    static acceptNext() {
+        return Page_1.Page.current().modalDialog().acceptNext()
+            .describedAs('#actor accepts next modal dialog window');
+    }
+    /**
+     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.acceptNextWithValue}.
+     *
+     * @param value
+     */
+    static acceptNextWithValue(value) {
+        return Page_1.Page.current().modalDialog().acceptNextWithValue(value)
+            .describedAs((0, core_1.d) `#actor accepts next modal dialog window with value ${value}`);
+    }
+    /**
+     * Produces an {@apilink Interaction|interaction} that invokes {@apilink ModalDialog.dismissNext}.
+     */
+    static dismissNext() {
+        return Page_1.Page.current().modalDialog().dismissNext()
+            .describedAs((0, core_1.d) `#actor dismisses next modal dialog window`);
+    }
+    /**
+     * {@apilink QuestionAdapter} that resolves to {@apilink ModalDialog.message} for the current {@apilink Page}.
+     */
+    static lastDialogMessage() {
+        return Page_1.Page.current().modalDialog().last().message()
+            .describedAs(`last dialog message`);
+    }
+    /**
+     * {@apilink QuestionAdapter} that resolves to {@apilink ModalDialog.state} for the current {@apilink Page}.
+     */
+    static lastDialogState() {
+        return Page_1.Page.current().modalDialog().last().state()
+            .describedAs(`last dialog state`);
+    }
+    /**
+     * Returns `accepted` or `dismissed` for dialogs that have been handled,
+     * or `absent` for those that haven't been handled yet.
+     */
+    state() {
+        return this.constructor.name
+            .replace('ModalDialog', '')
+            .toLowerCase();
+    }
+}
+exports.ModalDialog = ModalDialog;
+//# sourceMappingURL=ModalDialog.js.map

package/lib/screenplay/models/dialogs/ModalDialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModalDialog.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/ModalDialog.ts"],"names":[],"mappings":";;;AAAA,4CAAoG;AAEpG,kCAA+B;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,MAAsB,WAAW;IAE7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,SAAS;QACZ,OAAO,WAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,UAAU;QACb,OAAO,WAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,EAAE;aAC3C,WAAW,CAAC,yCAAyC,CAAC,CAAC;IAChE,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAkC;QACzD,OAAO,WAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC;aACzD,WAAW,CAAC,IAAA,QAAC,EAAA,sDAAuD,KAAM,EAAE,CAAC,CAAC;IACvF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW;QACd,OAAO,WAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE;aAC5C,WAAW,CAAC,IAAA,QAAC,EAAA,2CAA2C,CAAC,CAAC;IACnE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB;QACpB,OAAO,WAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE;aAC/C,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe;QAClB,OAAO,WAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE;aAC7C,WAAW,CAAC,mBAAmB,CAAC,CAAC;IAC1C,CAAC;IAwBD;;;OAGG;IACH,KAAK;QACD,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI;aACvB,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC;aAC1B,WAAW,EAAE,CAAC;IACvB,CAAC;CACJ;AArGD,kCAqGC"}