@serenity-js/web 3.0.0-rc.13 → 3.0.0-rc.14

package/src/screenplay/questions/Text.ts

@@ -2,13 +2,12 @@ import { Answerable, AnswersQuestions, d, MetaQuestion, Question, QuestionAdapte
 import { asyncMap } from '@serenity-js/core/lib/io';
 
 import { PageElement, PageElements } from '../models';
-import { ElementQuestion } from './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}>
+ *  - a given {@link PageElement}
+ *  - a group of {@link PageElements}
  *
  *  The result includes the visible text of any sub-elements, without any leading or trailing whitespace.
  *
@@ -23,13 +22,15 @@ import { ElementQuestion } from './ElementQuestion';
  * @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';
+ *  import { By, PageElement, Text } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  const header = () =>
- *      Target.the('header').located(by.tagName('h1'))
+ *      PageElement.located(By.css('h1'))
+ *          .describedAs('header')
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
  *          Ensure.that(Text.of(header()), equals('Shopping list')),
  *      )
@@ -37,13 +38,15 @@ import { ElementQuestion } from './ElementQuestion';
  * @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';
+ *  import { By, PageElement, Text } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  const shoppingListItems = () =>
- *      Target.the('shopping list items').located(by.css('#shopping-list li'))
+ *      PageElements.located(By.css('#shopping-list li'))
+ *         .describedAs('shopping list items')
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
  *          Ensure.that(
  *              Text.ofAll(shoppingListItems()),
@@ -54,15 +57,17 @@ import { ElementQuestion } from './ElementQuestion';
  * @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';
+ *  import { By, CssClasses, PageElement, Text } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  const shoppingListItemCalled = (name: string) =>
- *      Target.the('shopping list items').located(by.css('#shopping-list li'))
+ *      PageElements.located(By.css('#shopping-list li'))
+ *          .describedAs('shopping list items')
  *          .where(Text, equals(name))
  *          .first()
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
  *          Ensure.that(
  *              CssClasses.of(shoppingListItemCalled('Honey)),
@@ -77,11 +82,10 @@ export class Text {
 
     /**
      * @desc
-     *  Retrieves text of a single {@link WebElement},
-     *  represented by Answerable<{@link @wdio/types~Element}>.
+     *  Retrieves text of a single {@link PageElement}.
      *
      * @param {Answerable<PageElement>} element
-     * @returns {Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>>}
+     * @returns {@serenity-js/core/lib/screenplay~QuestionAdapter<string>}
      *
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
@@ -94,11 +98,10 @@ export class Text {
 
     /**
      * @desc
-     *  Retrieves text of a group of {@link WebElement}s,
-     *  represented by Answerable<{@link @wdio/types~ElementList}>
+     *  Retrieves text of a group of {@link PageElements}.
      *
-     * @param {Answerable<PageElement[]>} elements
-     * @returns {Question<Promise<string[]>> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>}
+     * @param {Answerable<PageElements | PageElement[]>} elements
+     * @returns {@serenity-js/core/lib/screenplay~QuestionAdapter<string[]>}
      *
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
@@ -118,15 +121,21 @@ export class Text {
 }
 
 class TextOfSingleElement
-    extends ElementQuestion<Promise<string>>
+    extends Question<Promise<string>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string>>
 {
+    /**
+     * @private
+     */
+    private subject: string;
+
     static of(element: Answerable<PageElement>): QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
         return Question.createAdapter(new TextOfSingleElement(element)) as QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
     }
 
-    constructor(private readonly element: Answerable<PageElement>) {
-        super(`the text of ${ element }`);
+    protected constructor(private readonly element: Answerable<PageElement>) {
+        super();
+        this.subject = d`the text of ${ element }`;
     }
 
     of(parent: Answerable<PageElement>): Question<Promise<string>> {
@@ -138,18 +147,44 @@ class TextOfSingleElement
 
         return element.text();
     }
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @returns {string}
+     *  Returns a human-readable representation of this {@link @serenity-js/core/lib/screenplay~Question}.
+     */
+    toString(): string {
+        return this.subject;
+    }
 }
 
 class TextOfMultipleElements
-    extends ElementQuestion<Promise<string[]>>
+    extends Question<Promise<string[]>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string[]>>
 {
+    /**
+     * @private
+     */
+    private subject: string;
+
     static of(elements: PageElements): QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>> {
         return Question.createAdapter(new TextOfMultipleElements(elements)) as QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>;
     }
 
-    constructor(private readonly elements: PageElements) {
-        super(d`the text of ${ elements }`);
+    protected constructor(private readonly elements: PageElements) {
+        super();
+        this.subject = d`the text of ${ elements }`;
     }
 
     of(parent: Answerable<PageElement>): Question<Promise<string[]>> {
@@ -161,4 +196,24 @@ class TextOfMultipleElements
 
         return asyncMap(elements, element => element.text());
     }
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @returns {string}
+     *  Returns a human-readable representation of this {@link @serenity-js/core/lib/screenplay~Question}.
+     */
+    toString(): string {
+        return this.subject;
+    }
 }

package/src/screenplay/questions/Value.ts

@@ -1,60 +1,87 @@
-import { Answerable, AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, AnswersQuestions, d, 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}>
+ *  Retrieves the `value` attribute of a given {@link PageElement}.
  *
  * @example <caption>Example widget</caption>
  *  <input type="text" id="username" value="Alice" />
  *
- * @example <caption>Retrieve CSS classes of a given WebElement</caption>
+ * @example <caption>Retrieve the `value` of a given PageElement</caption>
  *  import { actorCalled } from '@serenity-js/core';
  *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, Value, Target } from '@serenity-js/webdriverio';
+ *  import { By, PageElement, Value } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  const usernameField = () =>
- *      Target.the('username field').located(by.id('username'))
+ *      PageElement.located(By.id('username')).describedAs('username field')
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
  *          Ensure.that(Value.of(usernameField), equals('Alice')),
  *      )
  *
+ * @example <caption>Using Value as QuestionAdapter</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { By, PageElement, Value } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
+ *
+ *  const usernameField = () =>
+ *      PageElement.located(By.id('username')).describedAs('username field')
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              Value.of(usernameField).toLocaleLowerCase()[0],
+ *              equals('a')  // [a]lice
+ *          ),
+ *      )
+ *
  * @extends {@serenity-js/core/lib/screenplay~Question}
  * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
  */
 export class Value
-    extends ElementQuestion<Promise<string>>
+    extends Question<Promise<string>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string>>
 {
     /**
-     * @param {Answerable<PageElement>} element
-     * @returns {Value}
+     * @private
      */
-    static of(element: Answerable<PageElement>): Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
-        return new Value(element);
+    private subject: string;
+
+    /**
+     * @desc
+     *  Retrieves the `value` attribute of a given {@link PageElement}.
+     *
+     * @param {@serenity-js/core/lib/screenplay~Answerable<PageElement>} element
+     * @returns {@serenity-js/core/lib/screenplay~QuestionAdapter<string>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    static of(element: Answerable<PageElement>): QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
+        return Question.createAdapter(new Value(element)) as QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
     }
 
     /**
      * @param {Answerable<PageElement>} element
      */
     constructor(private readonly element: Answerable<PageElement>) {
-        super(formatted`the value of ${ element }`);
+        super();
+        this.subject = d`the value of ${ element }`;
     }
 
     /**
      * @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.
+     *  Retrieves the `value` attribute of a given {@link PageElement}.
+     *  located within the `parent` element.
      *
-     * @param {Answerable<PageElement>} parent
-     * @returns {Question<Promise<string>>}
+     * @param {@serenity-js/core/lib/screenplay~Answerable<PageElement>} parent
+     * @returns {@serenity-js/core/lib/screenplay~QuestionAdapter<string>}
      *
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
@@ -75,8 +102,28 @@ export class Value
      * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
      */
     async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
-        const element = await this.resolve(actor, this.element);
+        const element = await actor.answer(this.element);
 
         return element.value();
     }
+
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @returns {string}
+     *  Returns a human-readable representation of this {@link @serenity-js/core/lib/screenplay~Question}.
+     */
+    toString(): string {
+        return this.subject;
+    }
 }

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

@@ -1,33 +0,0 @@
-import { Answerable, AnswersQuestions, Question } from '@serenity-js/core';
-/**
- * @desc
- *  A base class for questions about {@link PageElement}s.
- *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- */
-export declare abstract class ElementQuestion<T> extends Question<T> {
-    protected subject: string;
-    constructor(subject: string);
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject: string): this;
-    toString(): string;
-    /**
-     * @desc
-     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
-     *  if the element is `undefined`.
-     *
-     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
-     * @param {@serenity-js/core/lib/screenplay~Answerable<Element|ElementList>} element
-     *
-     * @returns {Promise<PageElement|PageElements>}
-     *
-     * @protected
-     */
-    protected resolve<T>(actor: AnswersQuestions, element: Answerable<T>): Promise<T>;
-}

package/lib/screenplay/questions/ElementQuestion.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ElementQuestion = void 0;
-const core_1 = require("@serenity-js/core");
-const io_1 = require("@serenity-js/core/lib/io");
-/**
- * @desc
- *  A base class for questions about {@link PageElement}s.
- *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- */
-// todo: remove
-class ElementQuestion extends core_1.Question {
-    constructor(subject) {
-        super();
-        this.subject = subject;
-    }
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject) {
-        this.subject = subject;
-        return this;
-    }
-    toString() {
-        return this.subject;
-    }
-    /**
-     * @desc
-     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
-     *  if the element is `undefined`.
-     *
-     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
-     * @param {@serenity-js/core/lib/screenplay~Answerable<Element|ElementList>} element
-     *
-     * @returns {Promise<PageElement|PageElements>}
-     *
-     * @protected
-     */
-    async resolve(actor, element) {
-        const resolved = await actor.answer(element);
-        if (!resolved) {
-            throw new core_1.LogicError((0, io_1.formatted) `Couldn't find ${element}`);
-        }
-        return resolved;
-    }
-}
-exports.ElementQuestion = ElementQuestion;
-//# sourceMappingURL=ElementQuestion.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"ElementQuestion.js","sourceRoot":"","sources":["../../../src/screenplay/questions/ElementQuestion.ts"],"names":[],"mappings":";;;AAAA,4CAAuF;AACvF,iDAAqD;AAErD;;;;;GAKG;AACH,eAAe;AACf,MAAsB,eAClB,SAAQ,eAAW;IAEnB,YAAsB,OAAe;QACjC,KAAK,EAAE,CAAC;QADU,YAAO,GAAP,OAAO,CAAQ;IAErC,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,OAAO,CACnB,KAAuB,EACvB,OAAsB;QAEtB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAE7C,IAAI,CAAE,QAAQ,EAAE;YACZ,MAAM,IAAI,iBAAU,CAAC,IAAA,cAAS,EAAC,iBAAkB,OAAQ,EAAE,CAAC,CAAC;SAChE;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;CACJ;AA/CD,0CA+CC"}

package/src/screenplay/questions/ElementQuestion.ts

@@ -1,58 +0,0 @@
-import { Answerable, AnswersQuestions, LogicError, Question } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-
-/**
- * @desc
- *  A base class for questions about {@link PageElement}s.
- *
- * @extends {@serenity-js/core/lib/screenplay~Question}
- */
-// todo: remove
-export abstract class ElementQuestion<T>
-    extends Question<T>
-{
-    constructor(protected subject: string) {
-        super();
-    }
-
-    /**
-     * @desc
-     *  Changes the description of this question's subject.
-     *
-     * @param {string} subject
-     * @returns {Question<T>}
-     */
-    describedAs(subject: string): this {
-        this.subject = subject;
-        return this;
-    }
-
-    toString(): string {
-        return this.subject;
-    }
-
-    /**
-     * @desc
-     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
-     *  if the element is `undefined`.
-     *
-     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
-     * @param {@serenity-js/core/lib/screenplay~Answerable<Element|ElementList>} element
-     *
-     * @returns {Promise<PageElement|PageElements>}
-     *
-     * @protected
-     */
-    protected async resolve<T>(
-        actor: AnswersQuestions,
-        element: Answerable<T>,
-    ): Promise<T> {
-        const resolved = await actor.answer(element);
-
-        if (! resolved) {
-            throw new LogicError(formatted `Couldn't find ${ element }`);
-        }
-
-        return resolved;
-    }
-}