@serenity-js/web 3.41.1 → 3.42.0

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

@@ -0,0 +1,173 @@
+import { the } from '@serenity-js/core';
+import { Page } from '../Page.js';
+/**
+ * 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 [`ModalDialog.acceptNext`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNext),
+ *   [`ModalDialog.acceptNextWithValue`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNextWithValue),
+ *   or [`ModalDialog.dismissNext`](https://serenity-js.org/api/web/class/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
+ * - [`Optional`](https://serenity-js.org/api/core/interface/Optional/)
+ *
+ * @group Models
+ */
+export 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.current().modalDialog().last().isPresent();
+    }
+    /**
+     * Produces an [interaction](https://serenity-js.org/api/core/class/Interaction/) that invokes [`ModalDialog.acceptNext`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNext).
+     */
+    static acceptNext() {
+        return Page.current().modalDialog().acceptNext()
+            .describedAs('#actor accepts next modal dialog window');
+    }
+    /**
+     * Produces an [interaction](https://serenity-js.org/api/core/class/Interaction/) that invokes [`ModalDialog.acceptNextWithValue`](https://serenity-js.org/api/web/class/ModalDialog/#acceptNextWithValue).
+     *
+     * @param value
+     */
+    static acceptNextWithValue(value) {
+        return Page.current().modalDialog().acceptNextWithValue(value)
+            .describedAs(the `#actor accepts next modal dialog window with value ${value}`);
+    }
+    /**
+     * Produces an [interaction](https://serenity-js.org/api/core/class/Interaction/) that invokes [`ModalDialog.dismissNext`](https://serenity-js.org/api/web/class/ModalDialog/#dismissNext).
+     */
+    static dismissNext() {
+        return Page.current().modalDialog().dismissNext()
+            .describedAs(the `#actor dismisses next modal dialog window`);
+    }
+    /**
+     * [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to [`ModalDialog.message`](https://serenity-js.org/api/web/class/ModalDialog/#message) for the current [`Page`](https://serenity-js.org/api/web/class/Page/).
+     */
+    static lastDialogMessage() {
+        return Page.current().modalDialog().last().message()
+            .describedAs(`last dialog message`);
+    }
+    /**
+     * [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to [`ModalDialog.state`](https://serenity-js.org/api/web/class/ModalDialog/#state) for the current [`Page`](https://serenity-js.org/api/web/class/Page/).
+     */
+    static lastDialogState() {
+        return 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();
+    }
+}
+//# sourceMappingURL=ModalDialog.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ModalDialog.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/ModalDialog.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAExC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,MAAM,OAAgB,WAAW;IAE7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,SAAS;QACZ,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,UAAU;QACb,OAAO,IAAI,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,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC;aACzD,WAAW,CAAC,GAAG,CAAA,sDAAuD,KAAM,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW;QACd,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE;aAC5C,WAAW,CAAC,GAAG,CAAA,2CAA2C,CAAC,CAAC;IACrE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB;QACpB,OAAO,IAAI,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,IAAI,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"}

package/esm/screenplay/models/dialogs/ModalDialogHandler.d.ts

@@ -0,0 +1,38 @@
+import type { ModalDialog } from './ModalDialog.js';
+/**
+ * Represent the strategy to use with any upcoming [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/) windows.
+ *
+ * ## Learn more
+ *
+ * - [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/)
+ * - [`Page.modalDialog`](https://serenity-js.org/api/web/class/Page/#modalDialog)
+ *
+ * @group Models
+ */
+export declare abstract class ModalDialogHandler {
+    protected modalDialog: ModalDialog;
+    protected constructor(modalDialog?: ModalDialog);
+    /**
+     * Configures the handler to accept the next JavaScript modal dialog.
+     */
+    abstract acceptNext(): Promise<void>;
+    /**
+     * Configures the handler to accept the next JavaScript `prompt``
+     * with a given `text` value.
+     */
+    abstract acceptNextWithValue(text: string | number): Promise<void>;
+    /**
+     * Configures the handler to dismiss the next JavaScript modal dialog.
+     */
+    abstract dismissNext(): Promise<void>;
+    /**
+     * Resets the handler to its default state.
+     */
+    abstract reset(): Promise<void>;
+    /**
+     * Returns the most recently handled [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/),
+     * or [`AbsentModalDialog`](https://serenity-js.org/api/web/class/AbsentModalDialog/) when no dialogs have been handled yet.
+     */
+    last(): Promise<ModalDialog>;
+}
+//# sourceMappingURL=ModalDialogHandler.d.ts.map

package/esm/screenplay/models/dialogs/ModalDialogHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModalDialogHandler.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/ModalDialogHandler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;GASG;AACH,8BAAsB,kBAAkB;IAEd,SAAS,CAAC,WAAW,EAAE,WAAW;IAAxD,SAAS,aAAuB,WAAW,GAAE,WAAqC;IAIlF;;OAEG;IACH,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAEpC;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAElE;;OAEG;IACH,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;CAGrC"}

package/esm/screenplay/models/dialogs/ModalDialogHandler.js

@@ -0,0 +1,27 @@
+import { ensure, isDefined } from 'tiny-types';
+import { AbsentModalDialog } from './AbsentModalDialog.js';
+/**
+ * Represent the strategy to use with any upcoming [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/) windows.
+ *
+ * ## Learn more
+ *
+ * - [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/)
+ * - [`Page.modalDialog`](https://serenity-js.org/api/web/class/Page/#modalDialog)
+ *
+ * @group Models
+ */
+export class ModalDialogHandler {
+    modalDialog;
+    constructor(modalDialog = new AbsentModalDialog()) {
+        this.modalDialog = modalDialog;
+        ensure('modalDialog', modalDialog, isDefined());
+    }
+    /**
+     * Returns the most recently handled [`ModalDialog`](https://serenity-js.org/api/web/class/ModalDialog/),
+     * or [`AbsentModalDialog`](https://serenity-js.org/api/web/class/AbsentModalDialog/) when no dialogs have been handled yet.
+     */
+    async last() {
+        return this.modalDialog;
+    }
+}
+//# sourceMappingURL=ModalDialogHandler.js.map

package/esm/screenplay/models/dialogs/ModalDialogHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModalDialogHandler.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/ModalDialogHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D;;;;;;;;;GASG;AACH,MAAM,OAAgB,kBAAkB;IAEJ;IAAhC,YAAgC,cAA2B,IAAI,iBAAiB,EAAE;QAAlD,gBAAW,GAAX,WAAW,CAAuC;QAC9E,MAAM,CAAC,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;IACpD,CAAC;IAuBD;;;OAGG;IACH,KAAK,CAAC,IAAI;QACN,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ"}

package/esm/screenplay/models/dialogs/index.d.ts

@@ -0,0 +1,6 @@
+export * from './AbsentModalDialog.js';
+export * from './AcceptedModalDialog.js';
+export * from './DismissedModalDialog.js';
+export * from './ModalDialog.js';
+export * from './ModalDialogHandler.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/models/dialogs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC"}

package/esm/screenplay/models/dialogs/index.js

@@ -0,0 +1,6 @@
+export * from './AbsentModalDialog.js';
+export * from './AcceptedModalDialog.js';
+export * from './DismissedModalDialog.js';
+export * from './ModalDialog.js';
+export * from './ModalDialogHandler.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/models/dialogs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/models/dialogs/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC"}

package/esm/screenplay/models/index.d.ts

@@ -0,0 +1,18 @@
+export * from './ArgumentDehydrator.js';
+export * from './BrowserCapabilities.js';
+export * from './BrowsingSession.js';
+export * from './Cookie.js';
+export * from './CookieData.js';
+export * from './dialogs/index.js';
+export * from './Key.js';
+export * from './Locator.js';
+export * from './Page.js';
+export * from './PageElement.js';
+export * from './PageElements.js';
+export * from './PageElementsLocator.js';
+export * from './RootLocator.js';
+export * from './SelectOption.js';
+export * from './selectors/index.js';
+export * from './Switchable.js';
+export * from './SwitchableOrigin.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC"}

package/esm/screenplay/models/index.js

@@ -0,0 +1,18 @@
+export * from './ArgumentDehydrator.js';
+export * from './BrowserCapabilities.js';
+export * from './BrowsingSession.js';
+export * from './Cookie.js';
+export * from './CookieData.js';
+export * from './dialogs/index.js';
+export * from './Key.js';
+export * from './Locator.js';
+export * from './Page.js';
+export * from './PageElement.js';
+export * from './PageElements.js';
+export * from './PageElementsLocator.js';
+export * from './RootLocator.js';
+export * from './SelectOption.js';
+export * from './selectors/index.js';
+export * from './Switchable.js';
+export * from './SwitchableOrigin.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/models/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC"}

package/esm/screenplay/models/selectors/By.d.ts

@@ -0,0 +1,169 @@
+import type { Answerable, WithAnswerableProperties } from '@serenity-js/core';
+import { Question } from '@serenity-js/core';
+import { ByCss } from './ByCss.js';
+import { ByCssContainingText } from './ByCssContainingText.js';
+import { ById } from './ById.js';
+import type { ByRoleSelectorOptions, ByRoleSelectorValue } from './ByRole.js';
+import { ByRole } from './ByRole.js';
+import { ByTagName } from './ByTagName.js';
+import { ByXPath } from './ByXPath.js';
+/**
+ * `By` produces a [`Selector`](https://serenity-js.org/api/web/class/Selector/) used to locate a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or [`PageElement`](https://serenity-js.org/api/web/class/PageElements/) on a web page.
+ * Selectors can be defined using a static value or a [`Question`](https://serenity-js.org/api/core/class/Question/) to be resolved at runtime.
+ *
+ * ## Defining a selector using a string
+ *
+ * Every selector method on this class accepts a static `string` value to define a selector.
+ *
+ * ```typescript
+ * import { PageElement, By } from '@serenity-js/web'
+ *
+ * class LoginForm {
+ *   static usernameField = () =>
+ *     PageElement.located(By.role('textbox', { name: 'Username' }))
+ *       .describedAs('username field'),
+ *
+ *   static passwordField = () =>
+ *     PageElement.located(By.css('[data-test-id="password"]'))
+ *       .describedAs('password field')
+ * }
+ * ```
+ *
+ * ## Defining a selector using a Question
+ *
+ * Each method on this class also accepts an [`Answerable`](https://serenity-js.org/api/core/#Answerable) to allow for dynamic resolution of the selector.
+ * This can be useful when the selector is not known at the time of writing the test, or when the selector
+ * needs to be calculated based on the state of the system under test.
+ *
+ * The example below demonstrates how to use [`q`](https://serenity-js.org/api/core/function/q/) to define a selector that includes a dynamic value.
+ *
+ * ```typescript
+ * import { q } from '@serenity-js/core'
+ * import { PageElement, By } from '@serenity-js/web'
+ *
+ * class FormField {
+ *   static withTestId = (id: Answerable<string>) =>
+ *     PageElement.located(By.css(q`input[data-test-id="${ id }"]`))
+ *       .describedAs('form field')
+ * }
+ *
+ * ```
+ *
+ * ## Learn more
+ * - [Page Element Query Language](https://serenity-js.org/handbook/web-testing/page-element-query-language)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ * - [`q`](https://serenity-js.org/api/core/function/q/)
+ *
+ * @group Models
+ */
+export declare class By {
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).
+     *
+     * @param selector
+     */
+    static css(selector: Answerable<string>): Question<Promise<ByCss>>;
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) with a given [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
+     * using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).
+     *
+     * @param selector
+     * @param text
+     */
+    static cssContainingText(selector: Answerable<string>, text: Answerable<string>): Question<Promise<ByCssContainingText>>;
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors)
+     * capable of piercing [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)-piercing
+     *
+     * @param selector
+     */
+    static deepCss(selector: Answerable<string>): Question<Promise<ByCss>>;
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using its [id](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors).
+     *
+     * @param selector
+     */
+    static id(selector: Answerable<string>): Question<Promise<ById>>;
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) by its [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
+     * [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+     *
+     * ### Example usage
+     *
+     * Given the following HTML structure:
+     *
+     * ```html
+     * <h3>Sign up</h3>
+     * <label>
+     *   <input type="checkbox" /> Subscribe
+     * </label>
+     * <br/>
+     * <button>Submit</button>
+     * ```
+     *
+     * Each element can be located by its implicit accessibility role:
+     *
+     * ```ts
+     * const heading  = PageElement.located(By.role('heading', { name: 'Sign up' })).describedAs('Sign up heading');
+     * const checkbox = PageElement.located(By.role('checkbox', { name: 'Subscribe' })).describedAs('Subscribe checkbox');
+     * const button   = PageElement.located(By.role('button', { name: 'Submit' })).describedAs('Submit button');
+     * ```
+     *
+     * #### Playwright Test
+     *
+     * ```ts
+     * import { Ensure } from '@serenity-js/assertions'
+     * import { Click, PageElement, By, isVisible } from '@serenity-js/web'
+     *
+     * // ... page element definitions as above
+     *
+     * describe('ARIA role selector', () => {
+     *   it('locates an element by its accessible name', async ({ actor }) => {
+     *     await actor.attemptsTo(
+     *       Ensure.that(heading, isVisible()),
+     *       Click.on(checkbox),
+     *       Click.on(button),
+     *     )
+     *   })
+     * })
+     * ```
+     *
+     * #### WebdriverIO
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Ensure } from '@serenity-js/assertions'
+     * import { Click, PageElement, By, isVisible } from '@serenity-js/web'
+     *
+     * // ... page element definitions as above
+     *
+     * describe('ARIA role selector', () => {
+     *   it('locates an element by its accessible name', async () => {
+     *     await actorCalled('Nick').attemptsTo(
+     *       Ensure.that(heading, isVisible()),
+     *       Click.on(checkbox),
+     *       Click.on(button),
+     *     )
+     *   })
+     * })
+     * ```
+     *
+     * @param role
+     * @param options
+     */
+    static role(role: ByRoleSelectorValue, options?: Answerable<WithAnswerableProperties<ByRoleSelectorOptions>>): Question<Promise<ByRole>>;
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using the name of its [HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
+     *
+     * @param selector
+     */
+    static tagName(selector: Answerable<string>): Question<Promise<ByTagName>>;
+    /**
+     * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using an [XPath selector](https://developer.mozilla.org/en-US/docs/Web/XPath).
+     *
+     * @param selector
+     */
+    static xpath(selector: Answerable<string>): Question<Promise<ByXPath>>;
+}
+//# sourceMappingURL=By.d.ts.map

package/esm/screenplay/models/selectors/By.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"By.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/By.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAK,QAAQ,EAAO,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,EAAE;IAEX;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAOlE;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAQxH;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAOtE;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAOhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,GAAE,UAAU,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAwB5I;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAO1E;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAMzE"}