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

package/src/screenplay/questions/Text.ts

@@ -2,163 +2,228 @@ 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}>
- *
- *  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 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>):
+    static of(pageElement: Answerable<PageElement>):
         QuestionAdapter<string> &                                 // eslint-disable-line @typescript-eslint/indent
         MetaQuestion<Answerable<PageElement>, Promise<string>>    // eslint-disable-line @typescript-eslint/indent
     {
-        return TextOfSingleElement.of(element);
+        return TextOfSingleElement.of(pageElement);
     }
 
     /**
-     * @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(elements: PageElements | Answerable<PageElement[]>): QuestionAdapter<string[]> {
-        if (elements instanceof PageElements) {
-            return TextOfMultipleElements.of(elements);
+    static ofAll(pageElements: PageElements): QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>
+    static ofAll(pageElements: Answerable<PageElement[]>): QuestionAdapter<string[]>
+    static ofAll(pageElements: PageElements | Answerable<PageElement[]>): QuestionAdapter<string[]> {
+        if (pageElements instanceof PageElements) {
+            return TextOfMultipleElements.of(pageElements);
         }
 
-        return Question.about(d`the text of ${ elements }`, async actor => {
-            const pageElements: PageElement[] = await actor.answer(elements);
+        return Question.about(d`the text of ${ pageElements }`, async actor => {
+            const elements: PageElement[] = await actor.answer(pageElements);
 
-            return asyncMap(pageElements, element => element.text());
+            return asyncMap(elements, element => element.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>> {
         return new TextOfSingleElement(PageElement.of(this.element, parent));
     }
 
+    /**
+     * @inheritDoc
+     */
     async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
         const element = await actor.answer(this.element);
 
         return element.text();
     }
+
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    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[]>> {
         return new TextOfMultipleElements(this.elements.of(parent));
     }
 
+    /**
+     * @inheritDoc
+     */
     async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
         const elements: PageElement[] = await actor.answer(this.elements);
 
         return asyncMap(elements, element => element.text());
     }
+
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    toString(): string {
+        return this.subject;
+    }
 }

package/src/screenplay/questions/Value.ts

@@ -1,82 +1,122 @@
-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}>
+ * 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 class Value
-    extends ElementQuestion<Promise<string>>
+    extends Question<Promise<string>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string>>
 {
+    private subject: string;
+
     /**
-     * @param {Answerable<PageElement>} element
-     * @returns {Value}
+     * 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
      */
-    static of(element: Answerable<PageElement>): Question<Promise<string>> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
-        return new Value(element);
+    static of(pageElement: Answerable<PageElement>): QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
+        return Question.createAdapter(new Value(pageElement)) as QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
     }
 
-    /**
-     * @param {Answerable<PageElement>} element
-     */
-    constructor(private readonly element: Answerable<PageElement>) {
-        super(formatted`the value of ${ element }`);
+    protected constructor(private readonly element: Answerable<PageElement>) {
+        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.
+     * 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>> {
         return new Value(PageElement.of(this.element, parent));
     }
 
     /**
-     * @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
      */
     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();
     }
+
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    toString(): string {
+        return this.subject;
+    }
 }

package/src/scripts/index.ts

@@ -0,0 +1 @@
+export * from './isVisible';

package/src/scripts/isVisible.ts

@@ -0,0 +1,113 @@
+/* eslint-disable unicorn/no-for-loop,unicorn/consistent-function-scoping */
+/* istanbul ignore next */
+export function isVisible(domNode: HTMLElement): boolean {
+
+    const style = window.getComputedStyle(domNode);
+
+    if (style.opacity === '0') {
+        return false;
+    }
+
+    if (style.visibility === 'hidden') {
+        return false;
+    }
+
+    if (style.display === 'none') {
+        return false;
+    }
+
+    if (!domNode.getBoundingClientRect || !domNode.scrollIntoView || !domNode.contains || !domNode.getClientRects || !document.elementFromPoint) {
+        return false
+    }
+
+    // Edge before switching to Chromium
+    const isOldEdge = !!window['StyleMedia']
+
+    // get overlapping element
+    function getOverlappingElement (element: HTMLElement, context?: Document) {
+        context = context || document
+        const dimensions = element.getBoundingClientRect()
+        const x = dimensions.left + (element.clientWidth / 2)
+        const y = dimensions.top + (element.clientHeight / 2)
+        return context.elementFromPoint(x, y)
+    }
+
+    // get overlapping element rects (currently only the first)
+    // applicable if element's text is multiline.
+    function getOverlappingRects (element: HTMLElement, context?: Document) {
+        context = context || document
+        const elements = []
+
+        const rects = element.getClientRects()
+        // webdriver clicks on center of the first element's rect (line of text), it might change in future
+        const rect = rects[0]
+        const x = rect.left + (rect.width / 2)
+        const y = rect.top + (rect.height / 2)
+        elements.push(context.elementFromPoint(x, y))
+
+        return elements
+    }
+
+    // get overlapping elements
+    function getOverlappingElements (element: HTMLElement, context?: Document) {
+        return [getOverlappingElement(element, context)].concat(getOverlappingRects(element, context))
+    }
+
+    // is a node a descendant of a given node
+    function nodeContains (element: HTMLElement, otherNode: HTMLElement) {
+        // Edge doesn't support neither Shadow Dom nor contains if ShadowRoot polyfill is used
+        if (isOldEdge) {
+            let tempElement = otherNode as HTMLElement | ShadowRoot | Element
+            while (tempElement) {
+                if (tempElement === element) {
+                    return true
+                }
+
+                tempElement = tempElement.parentNode as ShadowRoot
+                // DocumentFragment / ShadowRoot polyfill like ShadyRoot
+                if (tempElement && tempElement.nodeType === 11 && tempElement.host) {
+                    tempElement = tempElement.host
+                }
+            }
+            return false
+        }
+
+        return element.contains(otherNode)
+    }
+
+    // is one of overlapping elements the `elem` or one of its child
+    function isOverlappingElementMatch (elementsFromPoint: HTMLElement[], element: HTMLElement): boolean {
+        if (elementsFromPoint.some(function (elementFromPoint) {
+            return elementFromPoint === element || nodeContains(element, elementFromPoint)
+        })) {
+            return true
+        }
+
+        // shadow root
+        // filter unique elements with shadowRoot
+        const elementsWithShadowRoot = [].concat(elementsFromPoint).filter(function (x: HTMLElement) {
+            return x && x.shadowRoot && x.shadowRoot.elementFromPoint
+        })
+
+        // getOverlappingElements of every element with shadowRoot
+        let shadowElementsFromPoint: HTMLElement[] = []
+        for (let i = 0; i < elementsWithShadowRoot.length; ++i) {
+            const shadowElement = elementsWithShadowRoot[i]
+            shadowElementsFromPoint = shadowElementsFromPoint.concat(
+                getOverlappingElements(element, (shadowElement as HTMLElement).shadowRoot as any) as any
+            )
+        }
+        // remove duplicates and parents
+        shadowElementsFromPoint = [].concat(shadowElementsFromPoint).filter(function (x) {
+            return !elementsFromPoint.includes(x)
+        })
+
+        if (shadowElementsFromPoint.length === 0) {
+            return false
+        }
+
+        return isOverlappingElementMatch(shadowElementsFromPoint, element)
+    }
+
+    return isOverlappingElementMatch(getOverlappingElements(domNode) as any as HTMLElement[], domNode)
+}