@serenity-js/web 3.41.1 → 3.42.0

package/esm/screenplay/models/selectors/By.js

@@ -0,0 +1,217 @@
+import { f, Question, the } from '@serenity-js/core';
+import { ByCss } from './ByCss.js';
+import { ByCssContainingText } from './ByCssContainingText.js';
+import { ByDeepCss } from './ByDeepCss.js';
+import { ById } from './ById.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 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) {
+        return Question.about(f `by css (${selector})`, async (actor) => {
+            const bySelector = await actor.answer(selector);
+            return new ByCss(bySelector);
+        });
+    }
+    /**
+     * 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, text) {
+        return Question.about(f `by css (${selector}) containing text ${text}`, async (actor) => {
+            const bySelector = await actor.answer(selector);
+            const textSelector = await actor.answer(text);
+            return new ByCssContainingText(bySelector, textSelector);
+        });
+    }
+    /**
+     * 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) {
+        return Question.about(f `by deep css (${selector})`, async (actor) => {
+            const bySelector = await actor.answer(selector);
+            return new ByDeepCss(bySelector);
+        });
+    }
+    /**
+     * 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) {
+        return Question.about(f `by id (${selector})`, async (actor) => {
+            const bySelector = await actor.answer(selector);
+            return new ById(bySelector);
+        });
+    }
+    /**
+     * 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, options = {}) {
+        const descriptionOf = (selectorOptions) => {
+            if (Question.isAQuestion(selectorOptions)) {
+                return the `by role ${role} (options: ${options})`;
+            }
+            if (Object.keys(selectorOptions).length === 0) {
+                return `by role "${role}"`;
+            }
+            const description = [];
+            for (const [key, value] of Object.entries(selectorOptions)) {
+                description.push(key + f `: ${value}`);
+            }
+            return `by role "${role}" (${description.join(', ')})`;
+        };
+        return Question.about(descriptionOf(options), async (actor) => {
+            const optionsValue = await actor.answer(Question.fromObject(options));
+            return new ByRole(role, optionsValue);
+        });
+    }
+    /**
+     * 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) {
+        return Question.about(f `by tag name (${selector})`, async (actor) => {
+            const bySelector = await actor.answer(selector);
+            return new ByTagName(bySelector);
+        });
+    }
+    /**
+     * 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) {
+        return Question.about(f `by xpath (${selector})`, async (actor) => {
+            const bySelector = await actor.answer(selector);
+            return new ByXPath(bySelector);
+        });
+    }
+}
+//# sourceMappingURL=By.js.map

package/esm/screenplay/models/selectors/By.js.map

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

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

@@ -0,0 +1,13 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.css`](https://serenity-js.org/api/web/class/By/#css)
+ *
+ * @group Models
+ */
+export declare class ByCss extends Selector {
+    readonly value: string;
+    constructor(value: string);
+}
+//# sourceMappingURL=ByCss.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ByCss.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCss.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,qBAAa,KAAM,SAAQ,QAAQ;aACH,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAG5C"}

package/esm/screenplay/models/selectors/ByCss.js

@@ -0,0 +1,16 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.css`](https://serenity-js.org/api/web/class/By/#css)
+ *
+ * @group Models
+ */
+export class ByCss extends Selector {
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+}
+//# sourceMappingURL=ByCss.js.map

package/esm/screenplay/models/selectors/ByCss.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByCss.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCss.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,OAAO,KAAM,SAAQ,QAAQ;IACH;IAA5B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ"}

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

@@ -0,0 +1,15 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.cssContainingText`](https://serenity-js.org/api/web/class/By/#cssContainingText)
+ *
+ * @group Models
+ */
+export declare class ByCssContainingText extends Selector {
+    readonly value: string;
+    readonly text: string;
+    constructor(value: string, text: string);
+}
+//# sourceMappingURL=ByCssContainingText.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ByCssContainingText.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCssContainingText.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;aACjB,KAAK,EAAE,MAAM;aAAkB,IAAI,EAAE,MAAM;gBAA3C,KAAK,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAG1E"}

package/esm/screenplay/models/selectors/ByCssContainingText.js

@@ -0,0 +1,19 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.cssContainingText`](https://serenity-js.org/api/web/class/By/#cssContainingText)
+ *
+ * @group Models
+ */
+export class ByCssContainingText extends Selector {
+    value;
+    text;
+    constructor(value, text) {
+        super();
+        this.value = value;
+        this.text = text;
+    }
+}
+//# sourceMappingURL=ByCssContainingText.js.map

package/esm/screenplay/models/selectors/ByCssContainingText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByCssContainingText.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByCssContainingText.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IACjB;IAA+B;IAA3D,YAA4B,KAAa,EAAkB,IAAY;QACnE,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;QAAkB,SAAI,GAAJ,IAAI,CAAQ;IAEvE,CAAC;CACJ"}

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

@@ -0,0 +1,14 @@
+import { Selector } from './Selector.js';
+/**
+ * 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
+ *
+ * **Pro tip:** Instantiate using [`By.deepCss`](https://serenity-js.org/api/web/class/By/#deepCss)
+ *
+ * @group Models
+ */
+export declare class ByDeepCss extends Selector {
+    readonly value: string;
+    constructor(value: string);
+}
+//# sourceMappingURL=ByDeepCss.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ByDeepCss.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByDeepCss.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,QAAQ;aACP,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAG5C"}

package/esm/screenplay/models/selectors/ByDeepCss.js

@@ -0,0 +1,17 @@
+import { Selector } from './Selector.js';
+/**
+ * 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
+ *
+ * **Pro tip:** Instantiate using [`By.deepCss`](https://serenity-js.org/api/web/class/By/#deepCss)
+ *
+ * @group Models
+ */
+export class ByDeepCss extends Selector {
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+}
+//# sourceMappingURL=ByDeepCss.js.map

package/esm/screenplay/models/selectors/ByDeepCss.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByDeepCss.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByDeepCss.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACP;IAA5B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ"}

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

@@ -0,0 +1,13 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.id`](https://serenity-js.org/api/web/class/By/#id)
+ *
+ * @group Models
+ */
+export declare class ById extends Selector {
+    readonly value: string;
+    constructor(value: string);
+}
+//# sourceMappingURL=ById.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ById.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ById.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,QAAQ;aACF,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAG5C"}

package/esm/screenplay/models/selectors/ById.js

@@ -0,0 +1,16 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.id`](https://serenity-js.org/api/web/class/By/#id)
+ *
+ * @group Models
+ */
+export class ById extends Selector {
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+}
+//# sourceMappingURL=ById.js.map

package/esm/screenplay/models/selectors/ById.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ById.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ById.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,OAAO,IAAK,SAAQ,QAAQ;IACF;IAA5B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ"}

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

@@ -0,0 +1,126 @@
+import { Selector } from './Selector.js';
+/**
+ * @group Models
+ */
+export type ByRoleSelectorValue = 'alert' | 'alertdialog' | 'application' | 'article' | 'banner' | 'blockquote' | 'button' | 'caption' | 'cell' | 'checkbox' | 'code' | 'columnheader' | 'combobox' | 'complementary' | 'contentinfo' | 'definition' | 'deletion' | 'dialog' | 'directory' | 'document' | 'emphasis' | 'feed' | 'figure' | 'form' | 'generic' | 'grid' | 'gridcell' | 'group' | 'heading' | 'img' | 'insertion' | 'link' | 'list' | 'listbox' | 'listitem' | 'log' | 'main' | 'marquee' | 'math' | 'meter' | 'menu' | 'menubar' | 'menuitem' | 'menuitemcheckbox' | 'menuitemradio' | 'navigation' | 'none' | 'note' | 'option' | 'paragraph' | 'presentation' | 'progressbar' | 'radio' | 'radiogroup' | 'region' | 'row' | 'rowgroup' | 'rowheader' | 'scrollbar' | 'search' | 'searchbox' | 'separator' | 'slider' | 'spinbutton' | 'status' | 'strong' | 'subscript' | 'superscript' | 'switch' | 'tab' | 'table' | 'tablist' | 'tabpanel' | 'term' | 'textbox' | 'time' | 'timer' | 'toolbar' | 'tooltip' | 'tree' | 'treegrid' | 'treeitem';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.role`](https://serenity-js.org/api/web/class/By/#role)
+ *
+ * @group Models
+ */
+export declare class ByRole extends Selector {
+    readonly value: ByRoleSelectorValue;
+    readonly options: ByRoleSelectorOptions;
+    constructor(value: ByRoleSelectorValue, options: ByRoleSelectorOptions);
+}
+/**
+ * @group Models
+ */
+export interface ByRoleSelectorOptions {
+    /**
+     * An attribute that is usually set by [`aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked) or
+     * native `<input type=checkbox>` controls.
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    checked?: boolean;
+    /**
+     * An attribute that is usually set by `aria-disabled` or `disabled`.
+     *
+     * **NOTE** Unlike most other attributes, `disabled` is inherited through the DOM hierarchy. Learn more about
+     * [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled).
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    disabled?: boolean;
+    /**
+     * Whether [`name`](https://serenity-js.org/api/web/interface/ByRoleSelectorOptions/#name) is matched exactly:
+     * case-sensitive and whole-string.
+     *
+     * :::tip Playwright matching defaults
+     * Playwright defaults to `false` for backwards compatibility, but we recommend setting this property to `true`
+     * to avoid unintentional matches.
+     * :::
+     *
+     * :::tip Playwright and name RegExp
+     * Playwright supports using a `RegExp` to match the name.
+     * When using a `RegExp`, exact matching is not applicable and this option is ignored.
+     * Note that **exact match still trims whitespace**.
+     * :::
+     *
+     * :::tip WebdriverIO
+     * WebdriverIO always performs exact matching, so this option is ignored.
+     * :::
+     */
+    exact?: boolean;
+    /**
+     * An attribute that is usually set by `aria-expanded`.
+     *
+     * Learn more about [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded).
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    expanded?: boolean;
+    /**
+     * Option that controls whether hidden elements are matched. By default, only non-hidden elements, as
+     * [defined by ARIA](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion), are matched by role selector.
+     *
+     * Learn more about [`aria-hidden`](https://www.w3.org/TR/wai-aria-1.2/#aria-hidden).
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    includeHidden?: boolean;
+    /**
+     * A number attribute that is usually present for roles `heading`, `listitem`, `row`, `treeitem`, with default values
+     * for `<h1>-<h6>` elements.
+     *
+     * Learn more about [`aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level).
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    level?: number;
+    /**
+     * Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+     *
+     * :::tip Playwright
+     * Only Playwright supports using a `RegExp` to match the name. When using a `string` instead, Playwright performs
+     * a **case-insensitive** match and searches for a **substring**. Use
+     * [`exact`](https://serenity-js.org/api/web/interface/ByRoleSelectorOptions/#exact) to control this behavior.
+     * :::
+     *
+     * :::tip WebdriverIO
+     * WebdriverIO does not support using `RegExp` and performs a **case-sensitive** and **exact** matching.
+     * :::
+     */
+    name?: string | RegExp;
+    /**
+     * An attribute that is usually set by [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed).
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    pressed?: boolean;
+    /**
+     * An attribute that is usually set by [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-selected).
+     *
+     * :::tip Playwright only
+     * This property is supported only by Playwright.
+     * :::
+     */
+    selected?: boolean;
+}
+//# sourceMappingURL=ByRole.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ByRole.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByRole.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GACzB,OAAO,GACP,aAAa,GACb,aAAa,GACb,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,QAAQ,GACR,SAAS,GACT,MAAM,GACN,UAAU,GACV,MAAM,GACN,cAAc,GACd,UAAU,GACV,eAAe,GACf,aAAa,GACb,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,WAAW,GACX,UAAU,GACV,UAAU,GACV,MAAM,GACN,QAAQ,GACR,MAAM,GACN,SAAS,GACT,MAAM,GACN,UAAU,GACV,OAAO,GACP,SAAS,GACT,KAAK,GACL,WAAW,GACX,MAAM,GACN,MAAM,GACN,SAAS,GACT,UAAU,GACV,KAAK,GACL,MAAM,GACN,SAAS,GACT,MAAM,GACN,OAAO,GACP,MAAM,GACN,SAAS,GACT,UAAU,GACV,kBAAkB,GAClB,eAAe,GACf,YAAY,GACZ,MAAM,GACN,MAAM,GACN,QAAQ,GACR,WAAW,GACX,cAAc,GACd,aAAa,GACb,OAAO,GACP,YAAY,GACZ,QAAQ,GACR,KAAK,GACL,UAAU,GACV,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,aAAa,GACb,QAAQ,GACR,KAAK,GACL,OAAO,GACP,SAAS,GACT,UAAU,GACV,MAAM,GACN,SAAS,GACT,MAAM,GACN,OAAO,GACP,SAAS,GACT,SAAS,GACT,MAAM,GACN,UAAU,GACV,UAAU,CAAA;AAEhB;;;;;;;GAOG;AACH,qBAAa,MAAO,SAAQ,QAAQ;aACJ,KAAK,EAAE,mBAAmB;aAAkB,OAAO,EAAE,qBAAqB;gBAA1E,KAAK,EAAE,mBAAmB,EAAkB,OAAO,EAAE,qBAAqB;CAGzG;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAElC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/esm/screenplay/models/selectors/ByRole.js

@@ -0,0 +1,19 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.role`](https://serenity-js.org/api/web/class/By/#role)
+ *
+ * @group Models
+ */
+export class ByRole extends Selector {
+    value;
+    options;
+    constructor(value, options) {
+        super();
+        this.value = value;
+        this.options = options;
+    }
+}
+//# sourceMappingURL=ByRole.js.map

package/esm/screenplay/models/selectors/ByRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByRole.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByRole.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAyFzC;;;;;;;GAOG;AACH,MAAM,OAAO,MAAO,SAAQ,QAAQ;IACJ;IAA4C;IAAxE,YAA4B,KAA0B,EAAkB,OAA8B;QAClG,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAqB;QAAkB,YAAO,GAAP,OAAO,CAAuB;IAEtG,CAAC;CACJ"}

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

@@ -0,0 +1,13 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.tagName`](https://serenity-js.org/api/web/class/By/#tagName)
+ *
+ * @group Models
+ */
+export declare class ByTagName extends Selector {
+    readonly value: string;
+    constructor(value: string);
+}
+//# sourceMappingURL=ByTagName.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ByTagName.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByTagName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,QAAQ;aACP,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAG5C"}

package/esm/screenplay/models/selectors/ByTagName.js

@@ -0,0 +1,16 @@
+import { Selector } from './Selector.js';
+/**
+ * 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).
+ *
+ * **Pro tip:** Instantiate using [`By.tagName`](https://serenity-js.org/api/web/class/By/#tagName)
+ *
+ * @group Models
+ */
+export class ByTagName extends Selector {
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+}
+//# sourceMappingURL=ByTagName.js.map

package/esm/screenplay/models/selectors/ByTagName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByTagName.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByTagName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACP;IAA5B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ"}

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

@@ -0,0 +1,13 @@
+import { Selector } from './Selector.js';
+/**
+ * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using an [XPath selector](https://developer.mozilla.org/en-US/docs/Web/XPath).
+ *
+ * **Pro tip:** Instantiate using [`By.xpath`](https://serenity-js.org/api/web/class/By/#xpath)
+ *
+ * @group Models
+ */
+export declare class ByXPath extends Selector {
+    readonly value: string;
+    constructor(value: string);
+}
+//# sourceMappingURL=ByXPath.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ByXPath.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByXPath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,QAAQ;aACL,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAG5C"}

package/esm/screenplay/models/selectors/ByXPath.js

@@ -0,0 +1,16 @@
+import { Selector } from './Selector.js';
+/**
+ * Locates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) using an [XPath selector](https://developer.mozilla.org/en-US/docs/Web/XPath).
+ *
+ * **Pro tip:** Instantiate using [`By.xpath`](https://serenity-js.org/api/web/class/By/#xpath)
+ *
+ * @group Models
+ */
+export class ByXPath extends Selector {
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+}
+//# sourceMappingURL=ByXPath.js.map

package/esm/screenplay/models/selectors/ByXPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByXPath.js","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/ByXPath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,OAAO,OAAQ,SAAQ,QAAQ;IACL;IAA5B,YAA4B,KAAa;QACrC,KAAK,EAAE,CAAC;QADgB,UAAK,GAAL,KAAK,CAAQ;IAEzC,CAAC;CACJ"}

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

@@ -0,0 +1,10 @@
+import { TinyType } from 'tiny-types';
+/**
+ * Describes a selector you use to identify a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or a group of [`PageElement`](https://serenity-js.org/api/web/class/PageElements/).
+ *
+ * @group Models
+ */
+export declare abstract class Selector extends TinyType {
+    toString(): string;
+}
+//# sourceMappingURL=Selector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Selector.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/models/selectors/Selector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;GAIG;AACH,8BAAsB,QAAS,SAAQ,QAAQ;IAE3C,QAAQ,IAAI,MAAM;CAMrB"}