@serenity-js/web 3.0.0-rc.8 → 3.0.0

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

@@ -1,97 +1,116 @@
 import { Answerable, MetaQuestion, QuestionAdapter } from '@serenity-js/core';
 import { PageElement, PageElements } from '../models';
 /**
- * @desc
- *  Resolves to the visible (i.e. not hidden by CSS) `innerText` of:
- *  - a given {@link WebElement}, represented by Answerable<{@link @wdio/types~Element}>
- *  - a group of {@link WebElement}s, represented by Answerable<{@link @wdio/types~ElementList}>
- *
- *  The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
- *
- * @example <caption>Example widget</caption>
- *  <h1>Shopping list</h1>
- *  <ul id="shopping-list">
- *    <li>Coffee<li>
- *    <li class="bought">Honey<li>
- *    <li>Chocolate<li>
- *  </ul>
- *
- * @example <caption>Retrieve text of a single element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, Target, Text } from '@serenity-js/webdriverio';
- *
- *  const header = () =>
- *      Target.the('header').located(by.tagName('h1'))
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(Text.of(header()), equals('Shopping list')),
- *      )
- *
- * @example <caption>Retrieve text of a multiple elements</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, Target, Text } from '@serenity-js/webdriverio';
- *
- *  const shoppingListItems = () =>
- *      Target.the('shopping list items').located(by.css('#shopping-list li'))
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(
- *              Text.ofAll(shoppingListItems()),
- *              equals([ 'Coffee', 'Honey', 'Chocolate' ])
- *          ),
- *      )
- *
- * @example <caption>Find element with matching text</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { contain, Ensure } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, CssClasses, Target, Text } from '@serenity-js/webdriverio';
- *
- *  const shoppingListItemCalled = (name: string) =>
- *      Target.the('shopping list items').located(by.css('#shopping-list li'))
- *          .where(Text, equals(name))
- *          .first()
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(
- *              CssClasses.of(shoppingListItemCalled('Honey)),
- *              contain('bought')
- *          ),
- *      )
- *
- * @public
- * @see {@link Target}
+ * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink 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 {@apilink PageElement}
+ * - a group of {@apilink 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 {@apilink 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 {@apilink 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 {@apilink PageElements|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
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink MetaQuestion}
+ * - {@apilink QuestionAdapter}
+ * - {@apilink Question}
+ *
+ * @group Questions
  */
 export declare class Text {
     /**
-     * @desc
-     *  Retrieves text of a single {@link WebElement},
-     *  represented by Answerable<{@link @wdio/types~Element}>.
+     * Instantiates a {@apilink Question} that uses
+     * the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * the text of a single {@apilink PageElement}.
      *
-     * @param {Answerable<PageElement>} element
-     * @returns {Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>>}
+     * #### Learn more
+     * - {@apilink MetaQuestion}
      *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     * @param pageElement
      */
-    static of(element: Answerable<PageElement>): QuestionAdapter<string> & // eslint-disable-line @typescript-eslint/indent
+    static of(pageElement: Answerable<PageElement>): QuestionAdapter<string> & // eslint-disable-line @typescript-eslint/indent
     MetaQuestion<Answerable<PageElement>, Promise<string>>;
     /**
-     * @desc
-     *  Retrieves text of a group of {@link WebElement}s,
-     *  represented by Answerable<{@link @wdio/types~ElementList}>
+     * Instantiates a {@apilink Question} that uses
+     * the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * the text of a group of {@apilink PageElements}.
      *
-     * @param {Answerable<PageElement[]>} elements
-     * @returns {Question<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>}
+     * #### Learn more
+     * - {@apilink MetaQuestion}
      *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     * @param pageElements
      */
-    static ofAll(elements: PageElements): QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>;
-    static ofAll(elements: Answerable<PageElement[]>): QuestionAdapter<string[]>;
+    static ofAll(pageElements: PageElements): QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>;
+    static ofAll(pageElements: Answerable<PageElement[]>): QuestionAdapter<string[]>;
 }
+//# sourceMappingURL=Text.d.ts.map

package/lib/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,EAAE,UAAU,EAAuB,YAAY,EAAY,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AAG5H,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,qBAAa,IAAI;IAEb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAC1C,eAAe,CAAC,MAAM,CAAC,GAAmC,gDAAgD;IAC1G,YAAY,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAK1D;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9H,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;CAYnF"}

package/lib/screenplay/questions/Text.js

@@ -4,131 +4,182 @@ exports.Text = void 0;
 const core_1 = require("@serenity-js/core");
 const io_1 = require("@serenity-js/core/lib/io");
 const models_1 = require("../models");
-const ElementQuestion_1 = require("./ElementQuestion");
 /**
- * @desc
- *  Resolves to the visible (i.e. not hidden by CSS) `innerText` of:
- *  - a given {@link WebElement}, represented by Answerable<{@link @wdio/types~Element}>
- *  - a group of {@link WebElement}s, represented by Answerable<{@link @wdio/types~ElementList}>
- *
- *  The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
- *
- * @example <caption>Example widget</caption>
- *  <h1>Shopping list</h1>
- *  <ul id="shopping-list">
- *    <li>Coffee<li>
- *    <li class="bought">Honey<li>
- *    <li>Chocolate<li>
- *  </ul>
- *
- * @example <caption>Retrieve text of a single element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, Target, Text } from '@serenity-js/webdriverio';
- *
- *  const header = () =>
- *      Target.the('header').located(by.tagName('h1'))
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(Text.of(header()), equals('Shopping list')),
- *      )
- *
- * @example <caption>Retrieve text of a multiple elements</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, Target, Text } from '@serenity-js/webdriverio';
- *
- *  const shoppingListItems = () =>
- *      Target.the('shopping list items').located(by.css('#shopping-list li'))
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(
- *              Text.ofAll(shoppingListItems()),
- *              equals([ 'Coffee', 'Honey', 'Chocolate' ])
- *          ),
- *      )
- *
- * @example <caption>Find element with matching text</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { contain, Ensure } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, CssClasses, Target, Text } from '@serenity-js/webdriverio';
- *
- *  const shoppingListItemCalled = (name: string) =>
- *      Target.the('shopping list items').located(by.css('#shopping-list li'))
- *          .where(Text, equals(name))
- *          .first()
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(
- *              CssClasses.of(shoppingListItemCalled('Honey)),
- *              contain('bought')
- *          ),
- *      )
- *
- * @public
- * @see {@link Target}
+ * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink 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 {@apilink PageElement}
+ * - a group of {@apilink 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 {@apilink 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 {@apilink 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 {@apilink PageElements|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
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink MetaQuestion}
+ * - {@apilink QuestionAdapter}
+ * - {@apilink Question}
+ *
+ * @group Questions
  */
 class Text {
     /**
-     * @desc
-     *  Retrieves text of a single {@link WebElement},
-     *  represented by Answerable<{@link @wdio/types~Element}>.
+     * Instantiates a {@apilink Question} that uses
+     * the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * the text of a single {@apilink PageElement}.
      *
-     * @param {Answerable<PageElement>} element
-     * @returns {Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>>}
+     * #### Learn more
+     * - {@apilink MetaQuestion}
      *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     * @param pageElement
      */
-    static of(element) {
-        return TextOfSingleElement.of(element);
+    static of(pageElement) {
+        return TextOfSingleElement.of(pageElement);
     }
-    static ofAll(elements) {
-        if (elements instanceof models_1.PageElements) {
-            return TextOfMultipleElements.of(elements);
+    static ofAll(pageElements) {
+        if (pageElements instanceof models_1.PageElements) {
+            return TextOfMultipleElements.of(pageElements);
         }
-        return core_1.Question.about((0, core_1.d) `the text of ${elements}`, async (actor) => {
-            const pageElements = await actor.answer(elements);
-            return (0, io_1.asyncMap)(pageElements, element => element.text());
+        return core_1.Question.about((0, core_1.d) `the text of ${pageElements}`, async (actor) => {
+            const elements = await actor.answer(pageElements);
+            return (0, io_1.asyncMap)(elements, element => element.text());
         });
     }
 }
 exports.Text = Text;
-class TextOfSingleElement extends ElementQuestion_1.ElementQuestion {
-    constructor(element) {
-        super(`the text of ${element}`);
-        this.element = element;
-    }
+class TextOfSingleElement extends core_1.Question {
     static of(element) {
         return core_1.Question.createAdapter(new TextOfSingleElement(element));
     }
+    constructor(element) {
+        super();
+        this.element = element;
+        this.subject = (0, core_1.d) `the text of ${element}`;
+    }
     of(parent) {
         return new TextOfSingleElement(models_1.PageElement.of(this.element, parent));
     }
+    /**
+     * @inheritDoc
+     */
     async answeredBy(actor) {
         const element = await actor.answer(this.element);
         return element.text();
     }
-}
-class TextOfMultipleElements extends ElementQuestion_1.ElementQuestion {
-    constructor(elements) {
-        super((0, core_1.d) `the text of ${elements}`);
-        this.elements = elements;
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject) {
+        this.subject = subject;
+        return this;
+    }
+    /**
+     * @inheritDoc
+     */
+    toString() {
+        return this.subject;
     }
+}
+class TextOfMultipleElements extends core_1.Question {
     static of(elements) {
         return core_1.Question.createAdapter(new TextOfMultipleElements(elements));
     }
+    constructor(elements) {
+        super();
+        this.elements = elements;
+        this.subject = (0, core_1.d) `the text of ${elements}`;
+    }
     of(parent) {
         return new TextOfMultipleElements(this.elements.of(parent));
     }
+    /**
+     * @inheritDoc
+     */
     async answeredBy(actor) {
         const elements = await actor.answer(this.elements);
         return (0, io_1.asyncMap)(elements, element => element.text());
     }
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject) {
+        this.subject = subject;
+        return this;
+    }
+    /**
+     * @inheritDoc
+     */
+    toString() {
+        return this.subject;
+    }
 }
 //# sourceMappingURL=Text.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Text.ts"],"names":[],"mappings":";;;AAAA,4CAA4H;AAC5H,iDAAoD;AAEpD,sCAAsD;AACtD,uDAAoD;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAa,IAAI;IAEb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,OAAgC;QAItC,OAAO,mBAAmB,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IAcD,MAAM,CAAC,KAAK,CAAC,QAAkD;QAC3D,IAAI,QAAQ,YAAY,qBAAY,EAAE;YAClC,OAAO,sBAAsB,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;SAC9C;QAED,OAAO,eAAQ,CAAC,KAAK,CAAC,IAAA,QAAC,EAAA,eAAgB,QAAS,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC9D,MAAM,YAAY,GAAkB,MAAM,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAEjE,OAAO,IAAA,aAAQ,EAAC,YAAY,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AA1CD,oBA0CC;AAED,MAAM,mBACF,SAAQ,iCAAgC;IAOxC,YAA6B,OAAgC;QACzD,KAAK,CAAC,eAAgB,OAAQ,EAAE,CAAC,CAAC;QADT,YAAO,GAAP,OAAO,CAAyB;IAE7D,CAAC;IAND,MAAM,CAAC,EAAE,CAAC,OAAgC;QACtC,OAAO,eAAQ,CAAC,aAAa,CAAC,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAqF,CAAC;IACxJ,CAAC;IAMD,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,mBAAmB,CAAC,oBAAW,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEjD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACJ;AAED,MAAM,sBACF,SAAQ,iCAAkC;IAO1C,YAA6B,QAAsB;QAC/C,KAAK,CAAC,IAAA,QAAC,EAAA,eAAgB,QAAS,EAAE,CAAC,CAAC;QADX,aAAQ,GAAR,QAAQ,CAAc;IAEnD,CAAC;IAND,MAAM,CAAC,EAAE,CAAC,QAAsB;QAC5B,OAAO,eAAQ,CAAC,aAAa,CAAC,IAAI,sBAAsB,CAAC,QAAQ,CAAC,CAAyF,CAAC;IAChK,CAAC;IAMD,EAAE,CAAC,MAA+B;QAC9B,OAAO,IAAI,sBAAsB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAuC;QACpD,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAElE,OAAO,IAAA,aAAQ,EAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;CACJ"}
+{"version":3,"file":"Text.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Text.ts"],"names":[],"mappings":"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"}

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

@@ -1,64 +1,97 @@
-import { Answerable, AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, MetaQuestion, Question, QuestionAdapter, UsesAbilities } from '@serenity-js/core';
 import { PageElement } from '../models';
-import { ElementQuestion } from './ElementQuestion';
 /**
- * @desc
- *  Returns the `value` attribute of a given {@link WebElement},
- *  represented by Answerable<{@link @wdio/types~Element}>
+ * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+ * the `value` attribute of a given {@apilink PageElement}.
  *
- * @example <caption>Example widget</caption>
- *  <input type="text" id="username" value="Alice" />
+ * ## Example widget
+ * ```html
+ * <input type="text" id="username" value="Alice" />
+ * ```
  *
- * @example <caption>Retrieve CSS classes of a given WebElement</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, Value, Target } from '@serenity-js/webdriverio';
+ * ## Retrieve the `value` of a given {@apilink PageElement}
  *
- *  const usernameField = () =>
- *      Target.the('username field').located(by.id('username'))
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { By, PageElement, Value } from '@serenity-js/web'
  *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(Value.of(usernameField), equals('Alice')),
- *      )
+ * const usernameField = () =>
+ *   PageElement.located(By.id('username'))
+ *     .describedAs('username field')
  *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(Value.of(usernameField), equals('Alice')),
+ *   )
+ * ```
+ *
+ * ## Using Value as {@apilink 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
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink MetaQuestion}
+ * - {@apilink QuestionAdapter}
+ * - {@apilink Question}
+ *
+ * @group Questions
  */
-export declare class Value extends ElementQuestion<Promise<string>> implements MetaQuestion<Answerable<PageElement>, Promise<string>> {
+export declare class Value extends Question<Promise<string>> implements MetaQuestion<Answerable<PageElement>, Promise<string>> {
     private readonly element;
+    private subject;
     /**
-     * @param {Answerable<PageElement>} element
-     * @returns {Value}
-     */
-    static of(element: Answerable<PageElement>): Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
-    /**
-     * @param {Answerable<PageElement>} element
+     * Instantiates a {@apilink Question} that uses
+     * the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * the `value` attribute of a given {@apilink PageElement}.
+     *
+     * #### Learn more
+     * - {@apilink MetaQuestion}
+     *
+     * @param pageElement
      */
-    constructor(element: Answerable<PageElement>);
+    static of(pageElement: Answerable<PageElement>): QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
+    protected constructor(element: Answerable<PageElement>);
     /**
-     * @desc
-     *  Resolves to the value of a given [`input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
-     *  {@link WebElement}, located in the context of a `parent` element.
+     * Instantiates a {@apilink Question} that uses
+     * the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * the `value` attribute of a given {@apilink PageElement}
+     * located within the `parent` element.
      *
-     * @param {Answerable<PageElement>} parent
-     * @returns {Question<Promise<string>>}
+     * #### Learn more
+     * - {@apilink MetaQuestion}
      *
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     * @param parent
      */
     of(parent: Answerable<PageElement>): Question<Promise<string>>;
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @inheritDoc
      */
     answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string>;
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject: string): this;
+    /**
+     * @inheritDoc
+     */
+    toString(): string;
 }
+//# sourceMappingURL=Value.d.ts.map

package/lib/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,EAAE,UAAU,EAAE,gBAAgB,EAAK,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE5H,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,KACT,SAAQ,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAChC,YAAW,YAAY,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAkB3C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB9C,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAIjI,SAAS,aAA8B,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC;IAKvE;;;;;;;;;;OAUG;IACH,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAI9D;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAM1E;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKlC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGrB"}