@serenity-js/web 3.41.2 → 3.42.0

package/esm/screenplay/questions/Selected.js

@@ -0,0 +1,247 @@
+import { Question, the } from '@serenity-js/core';
+/**
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+ * options and values selected in a
+ * [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+ *
+ * ## Learn more
+ * - [`Select`](https://serenity-js.org/api/web/class/Select/)
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ *
+ * @group Questions
+ */
+export class Selected {
+    /**
+     * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * a single [option](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * selected in an [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select multiple data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown');
+     * }
+     * ```
+     *
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .whoCan(BrowseTheWeb.using(protractor.browser))
+     *   .attemptsTo(
+     *     Select.value('UK').from(Countries.dropdown),
+     *     Ensure.that(Selected.valueOf(Countries.dropdown), equals('UK')),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Select.value`](https://serenity-js.org/api/web/class/Select/#value)
+     *
+     * @param pageElement
+     *  A [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) identifying the `<select>` element of interest
+     */
+    static valueOf(pageElement) {
+        return Question.about(the `value selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.value)[0];
+        });
+    }
+    /**
+     * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * values of [options](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)
+     * selected in an [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select multiple data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
+     *
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .whoCan(BrowseTheWeb.using(protractor.browser))
+     *   .attemptsTo(
+     *     Select.values('UK').from(Countries.dropdown),
+     *     Ensure.that(Selected.valuesOf(Countries.dropdown), equals([ 'UK' ])),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Select.values`](https://serenity-js.org/api/web/class/Select/#values)
+     *
+     * @param pageElement
+     *  A [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) identifying the `<select>` element of interest
+     */
+    static valuesOf(pageElement) {
+        return Question.about(the `values selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.value);
+        });
+    }
+    /**
+     * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * a single option selected in an [HTML `<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select multiple data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
+     *
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .attemptsTo(
+     *     Select.option('Poland').from(Countries.dropdown),
+     *     Ensure.that(
+     *       Selected.optionIn(Countries.dropdown),
+     *       equals('Poland')
+     *     ),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Select.option`](https://serenity-js.org/api/web/class/Select/#option)
+     *
+     * @param pageElement
+     *  A [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) identifying the `<select>` element of interest
+     */
+    static optionIn(pageElement) {
+        return Question.about(the `option selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.label)[0];
+        });
+    }
+    /**
+     * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * options selected in an [HTML `<select multiple>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#attr-multiple)
+     *
+     * #### Example widget
+     *
+     * ```html
+     * <select multiple data-test='countries'>
+     *   <option value='UK'>United Kingdom</option>
+     *   <option value='PL'>Poland</option>
+     *   <option value='US'>United States</option>
+     * </select>
+     * ```
+     *
+     * #### Lean Page Object describing the widget
+     *
+     * ```ts
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * class Countries {
+     *   static dropdown = () =>
+     *     PageElement.located(By.css('[data-test="countries"]'))
+     *       .describedAs('countries dropdown')
+     * }
+     * ```
+     *
+     * #### Retrieving the selected value
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Select, Selected } from '@serenity-js/web'
+     * import { Ensure, equals } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Nick')
+     *   .attemptsTo(
+     *     Select.options('Poland', 'United States').from(Countries.dropdown),
+     *     Ensure.that(
+     *       Selected.optionsIn(Countries.dropdown),
+     *       equals([ 'Poland', 'United States' ])
+     *     ),
+     *   )
+     * ```
+     *
+     * #### Learn more
+     * - [`Select.options`](https://serenity-js.org/api/web/class/Select/#options)
+     *
+     * @param pageElement
+     *  A [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) identifying the `<select>` element of interest
+     */
+    static optionsIn(pageElement) {
+        return Question.about(the `options selected in ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            const options = await element.selectedOptions();
+            return options
+                .filter(option => option.selected)
+                .map(option => option.label);
+        });
+    }
+}
+//# sourceMappingURL=Selected.js.map

package/esm/screenplay/questions/Selected.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Selected.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Selected.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAIlD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,MAAM,CAAC,OAAO,CAAC,WAAoC;QAC/C,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,qBAAsB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACzE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAChD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAoC;QAChD,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,sBAAuB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC1E,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,QAAQ,CAAC,WAAoC;QAChD,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,sBAAuB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC1E,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,SAAS,CAAC,WAAoC;QACjD,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,uBAAwB,WAAY,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC3E,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC;YAEhD,OAAO,OAAO;iBACT,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;iBACjC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

package/esm/screenplay/questions/Text.d.ts

@@ -0,0 +1,116 @@
+import type { Answerable, MetaQuestionAdapter, QuestionAdapter } from '@serenity-js/core';
+import type { PageElements } from '../models/index.js';
+import { PageElement } from '../models/index.js';
+/**
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+ * the visible (i.e. not hidden by CSS) [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText) of:
+ * - a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - a group of [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ *
+ * The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <h1>Shopping list</h1>
+ * <ul id="shopping-list">
+ *   <li>Coffee<li>
+ *   <li class="bought">Honey<li>
+ *   <li>Chocolate<li>
+ * </ul>
+ * ```
+ *
+ * ## Retrieve text of a single [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Text } from '@serenity-js/web'
+ *
+ * const header = () =>
+ *   PageElement.located(By.css('h1'))
+ *     .describedAs('header')
+ *
+ * await actorCalled('Lisa')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Ensure.that(Text.of(header()), equals('Shopping list')),
+ *   )
+ * ```
+ *
+ * ## Retrieve text of multiple [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Text } from '@serenity-js/web'
+ *
+ * const shoppingListItems = () =>
+ *   PageElements.located(By.css('#shopping-list li'))
+ *     .describedAs('shopping list items')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       Text.ofAll(shoppingListItems()),
+ *       equals([ 'Coffee', 'Honey', 'Chocolate' ])
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Using as filter in [Page Element Query Language](https://serenity-js.org/handbook/web-testing/page-element-query-language/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { contain, Ensure } from '@serenity-js/assertions'
+ * import { By, CssClasses, PageElement, Text } from '@serenity-js/web'
+ *
+ * const shoppingListItemCalled = (name: string) =>
+ *   PageElements.located(By.css('#shopping-list li'))
+ *     .describedAs('shopping list items')
+ *     .where(Text, equals(name))
+ *     .first()
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       CssClasses.of(shoppingListItemCalled('Honey)),
+ *       contain('bought')
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ *
+ * @group Questions
+ */
+export declare class Text {
+    /**
+     * Instantiates a [`Question`](https://serenity-js.org/api/core/class/Question/) that uses
+     * the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * the text of a single [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+     *
+     * #### Learn more
+     * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+     *
+     * @param pageElement
+     */
+    static of(pageElement: QuestionAdapter<PageElement> | PageElement): MetaQuestionAdapter<PageElement, string>;
+    /**
+     * Instantiates a [`Question`](https://serenity-js.org/api/core/class/Question/) that uses
+     * the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * the text of a group of [`PageElement`](https://serenity-js.org/api/web/class/PageElements/).
+     *
+     * #### Learn more
+     * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+     *
+     * @param pageElements
+     */
+    static ofAll(pageElements: PageElements): MetaQuestionAdapter<PageElement, string[]>;
+    static ofAll(pageElements: Answerable<PageElement[]>): QuestionAdapter<string[]>;
+}
+//# sourceMappingURL=Text.d.ts.map

package/esm/screenplay/questions/Text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Text.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAoB,mBAAmB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI5G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,qBAAa,IAAI;IAEb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC,GAAG,WAAW,GAAG,mBAAmB,CAAC,WAAW,EAAE,MAAM,CAAC;IAY5G;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,GAAG,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IACpF,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;CAYnF"}

package/esm/screenplay/questions/Text.js

@@ -0,0 +1,121 @@
+import { Question, the } from '@serenity-js/core';
+import { asyncMap } from '@serenity-js/core/io';
+import { PageElement } from '../models/index.js';
+/**
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+ * the visible (i.e. not hidden by CSS) [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText) of:
+ * - a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - a group of [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ *
+ * The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <h1>Shopping list</h1>
+ * <ul id="shopping-list">
+ *   <li>Coffee<li>
+ *   <li class="bought">Honey<li>
+ *   <li>Chocolate<li>
+ * </ul>
+ * ```
+ *
+ * ## Retrieve text of a single [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Text } from '@serenity-js/web'
+ *
+ * const header = () =>
+ *   PageElement.located(By.css('h1'))
+ *     .describedAs('header')
+ *
+ * await actorCalled('Lisa')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Ensure.that(Text.of(header()), equals('Shopping list')),
+ *   )
+ * ```
+ *
+ * ## Retrieve text of multiple [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Text } from '@serenity-js/web'
+ *
+ * const shoppingListItems = () =>
+ *   PageElements.located(By.css('#shopping-list li'))
+ *     .describedAs('shopping list items')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       Text.ofAll(shoppingListItems()),
+ *       equals([ 'Coffee', 'Honey', 'Chocolate' ])
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Using as filter in [Page Element Query Language](https://serenity-js.org/handbook/web-testing/page-element-query-language/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { contain, Ensure } from '@serenity-js/assertions'
+ * import { By, CssClasses, PageElement, Text } from '@serenity-js/web'
+ *
+ * const shoppingListItemCalled = (name: string) =>
+ *   PageElements.located(By.css('#shopping-list li'))
+ *     .describedAs('shopping list items')
+ *     .where(Text, equals(name))
+ *     .first()
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       CssClasses.of(shoppingListItemCalled('Honey)),
+ *       contain('bought')
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ *
+ * @group Questions
+ */
+export class Text {
+    /**
+     * Instantiates a [`Question`](https://serenity-js.org/api/core/class/Question/) that uses
+     * the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * the text of a single [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+     *
+     * #### Learn more
+     * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+     *
+     * @param pageElement
+     */
+    static of(pageElement) {
+        return Question.about(the `the text of ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            return element.text();
+        }, (parent) => Text.of(PageElement.of(pageElement, parent)));
+    }
+    static ofAll(pageElements) {
+        if (Question.isAMetaQuestion(pageElements)) {
+            return Question.about(the `the text of ${pageElements}`, textOfMultiple(pageElements), (parent) => Text.ofAll(pageElements.of(parent)));
+        }
+        return Question.about(the `the text of ${pageElements}`, textOfMultiple(pageElements));
+    }
+}
+function textOfMultiple(pageElements) {
+    return async (actor) => {
+        const elements = await actor.answer(pageElements);
+        return asyncMap(elements, element => element.text());
+    };
+}
+//# sourceMappingURL=Text.js.map

package/esm/screenplay/questions/Text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Text.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,OAAO,IAAI;IAEb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,WAAuD;QAC7D,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,eAAgB,WAAY,EAAE,EACnD,KAAK,EAAC,KAAK,EAAC,EAAE;YACV,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAEhD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC,EACD,CAAC,MAA+B,EAAE,EAAE,CAChC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CACnD,CAAC;IACN,CAAC;IAcD,MAAM,CAAC,KAAK,CAAC,YAAsD;QAC/D,IAAI,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,CAAC;YACzC,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,eAAgB,YAAa,EAAE,EACpD,cAAc,CAAC,YAAY,CAAC,EAC5B,CAAC,MAA+B,EAAE,EAAE,CAChC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAC1C,CAAC;QACN,CAAC;QAED,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,eAAgB,YAAa,EAAE,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5F,CAAC;CACJ;AAED,SAAS,cAAc,CAAC,YAAuC;IAC3D,OAAO,KAAK,EAAE,KAAuB,EAAE,EAAE;QACrC,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACjE,OAAO,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC,CAAA;AACL,CAAC"}

package/esm/screenplay/questions/Value.d.ts

@@ -0,0 +1,70 @@
+import type { MetaQuestionAdapter, QuestionAdapter } from '@serenity-js/core';
+import { PageElement } from '../models/index.js';
+/**
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+ * the `value` attribute of a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * ## Example widget
+ * ```html
+ * <input type="text" id="username" value="Alice" />
+ * ```
+ *
+ * ## Retrieve the `value` of a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Value } from '@serenity-js/web'
+ *
+ * const usernameField = () =>
+ *   PageElement.located(By.id('username'))
+ *     .describedAs('username field')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(Value.of(usernameField), equals('Alice')),
+ *   )
+ * ```
+ *
+ * ## Using Value as [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Value } from '@serenity-js/web'
+ *
+ * const usernameField = () =>
+ *   PageElement.located(By.id('username'))
+ *     .describedAs('username field')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       Value.of(usernameField).toLocaleLowerCase()[0],
+ *       equals('a')  // [a]lice
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ *
+ * @group Questions
+ */
+export declare class Value {
+    /**
+     * Instantiates a [`Question`](https://serenity-js.org/api/core/class/Question/) that uses
+     * the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * the `value` attribute of a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+     *
+     * #### Learn more
+     * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+     *
+     * @param pageElement
+     */
+    static of(pageElement: QuestionAdapter<PageElement> | PageElement): MetaQuestionAdapter<PageElement, string>;
+}
+//# sourceMappingURL=Value.d.ts.map

package/esm/screenplay/questions/Value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Value.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,mBAAmB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,KAAK;IAEd;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC,GAAG,WAAW,GAAG,mBAAmB,CAAC,WAAW,EAAE,MAAM,CAAC;CAU/G"}

package/esm/screenplay/questions/Value.js

@@ -0,0 +1,75 @@
+import { Question, the } from '@serenity-js/core';
+import { PageElement } from '../models/index.js';
+/**
+ * Uses the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+ * the `value` attribute of a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * ## Example widget
+ * ```html
+ * <input type="text" id="username" value="Alice" />
+ * ```
+ *
+ * ## Retrieve the `value` of a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Value } from '@serenity-js/web'
+ *
+ * const usernameField = () =>
+ *   PageElement.located(By.id('username'))
+ *     .describedAs('username field')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(Value.of(usernameField), equals('Alice')),
+ *   )
+ * ```
+ *
+ * ## Using Value as [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Value } from '@serenity-js/web'
+ *
+ * const usernameField = () =>
+ *   PageElement.located(By.id('username'))
+ *     .describedAs('username field')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       Value.of(usernameField).toLocaleLowerCase()[0],
+ *       equals('a')  // [a]lice
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ *
+ * @group Questions
+ */
+export class Value {
+    /**
+     * Instantiates a [`Question`](https://serenity-js.org/api/core/class/Question/) that uses
+     * the [actor's](https://serenity-js.org/api/core/class/Actor/) [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/) to retrieve
+     * the `value` attribute of a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+     *
+     * #### Learn more
+     * - [`MetaQuestion`](https://serenity-js.org/api/core/interface/MetaQuestion/)
+     *
+     * @param pageElement
+     */
+    static of(pageElement) {
+        return Question.about(the `the value of ${pageElement}`, async (actor) => {
+            const element = await actor.answer(pageElement);
+            return element.value();
+        }, (parent) => Value.of(PageElement.of(pageElement, parent)));
+    }
+}
+//# sourceMappingURL=Value.js.map

package/esm/screenplay/questions/Value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Value.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Value.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,OAAO,KAAK;IAEd;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,WAAuD;QAC7D,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAA,gBAAiB,WAAY,EAAE,EACpD,KAAK,EAAC,KAAK,EAAC,EAAE;YACV,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAChD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;QAC3B,CAAC,EACD,CAAC,MAA+B,EAAE,EAAE,CAChC,KAAK,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CACpD,CAAC;IACN,CAAC;CACJ"}

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

@@ -0,0 +1,8 @@
+export * from './Attribute.js';
+export * from './ComputedStyle.js';
+export * from './CssClasses.js';
+export * from './LastScriptExecution.js';
+export * from './Selected.js';
+export * from './Text.js';
+export * from './Value.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}