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

package/src/expectations/isVisible.ts

@@ -5,7 +5,10 @@ import { ElementExpectation } from './ElementExpectation';
 
 /**
  * @desc
- *  Expectation that the element is present in the DOM of the page and visible.
+ *  Expectation that the element is present in the DOM of the page and:
+ *  - is not hidden, so doesn't have `display: none`, `visibility: hidden` or `opacity: 0`
+ *  - is within the browser viewport
+ *  - doesn't have its centre covered by other elements
  *
  * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
  *

package/src/screenplay/models/PageElement.ts

@@ -16,9 +16,8 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
         });
     }
 
-    // todo: review usages and consider removing if not used
     static of<NET>(childElement: Answerable<PageElement<NET>>, parentElement: Answerable<PageElement<NET>>): QuestionAdapter<PageElement<NET>> {
-        return Question.about(d`${ childElement } of ${ parentElement })`, async actor => {
+        return Question.about(d`${ childElement } of ${ parentElement }`, async actor => {
             const child     = await actor.answer(childElement);
             const parent    = await actor.answer(parentElement);
 
@@ -83,5 +82,15 @@ export abstract class PageElement<Native_Element_Type = any> implements Optional
     abstract isPresent(): Promise<boolean>;
 
     abstract isSelected(): Promise<boolean>;
+
+    /**
+     * @desc
+     *  Checks if the PageElement:
+     *  - is not hidden, so doesn't have CSS style like `display: none`, `visibility: hidden` or `opacity: 0`
+     *  - is within the browser viewport
+     *  - doesn't have its centre covered by other elements
+     *
+     * @returns {Promise<boolean>}
+     */
     abstract isVisible(): Promise<boolean>;
 }

package/src/screenplay/models/PageElements.ts

@@ -1,4 +1,4 @@
-import { Answerable, f, List, MetaQuestion, Question } from '@serenity-js/core';
+import { Answerable, List, MetaQuestion, Question } from '@serenity-js/core';
 
 import { BrowseTheWeb } from '../abilities';
 import { Locator } from './Locator';
@@ -22,7 +22,7 @@ export class PageElements<Native_Element_Type = any>
 
     of(parent: Answerable<PageElement<Native_Element_Type>>): PageElements<Native_Element_Type> {
         return new PageElements<Native_Element_Type>(relativeToParent(this.locator, parent))
-            .describedAs(`<<${this.toString()}>>` + f`.of(${ parent })`);
+            .describedAs(`${ this.toString() } of ${ parent }`);
     }
 }
 
@@ -40,7 +40,7 @@ function relativeToDocumentRoot<Native_Element_Type>(selector: Answerable<Select
  * @package
  */
 function relativeToParent<Native_Element_Type>(relativeLocator: Answerable<Locator<Native_Element_Type>>, parent: Answerable<PageElement<Native_Element_Type>>): Question<Promise<Locator<Native_Element_Type>>> {
-    return Question.about(relativeLocator.toString() + f`.of${ parent }`, async actor => {
+    return Question.about(`${ relativeLocator.toString() } of ${ parent }`, async actor => {
         const locator: Locator<Native_Element_Type>             = await actor.answer(relativeLocator);
         const parentElement: PageElement<Native_Element_Type>   = await actor.answer(parent);
 

package/src/screenplay/questions/Attribute.ts

@@ -1,12 +1,10 @@
-import { Answerable, AnswersQuestions, LogicError, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
+import { Answerable, AnswersQuestions, d, LogicError, MetaQuestion, Question, QuestionAdapter, UsesAbilities } from '@serenity-js/core';
 
 import { PageElement } from '../models';
-import { ElementQuestion } from './ElementQuestion';
 
 /**
  * @desc
- *  Returns the value of the given HTML attribute of a given {@link WebElement},
- *  represented by Answerable<{@link @wdio/types~Element}>
+ *  Returns the value of the specified HTML attribute of a given {@link PageElement}.
  *
  * @example <caption>Example widget</caption>
  *  <ul id="shopping-list" data-items-left="2">
@@ -15,37 +13,60 @@ import { ElementQuestion } from './ElementQuestion';
  *    <li data-state="buy">Chocolate<li>
  *  </ul>
  *
- * @example <caption>Retrieve a HTML attribute of a given WebElement</caption>
+ * @example <caption>Retrieve an HTML attribute of a given PageElement</caption>
  *  import { actorCalled } from '@serenity-js/core';
  *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { Attribute, by, BrowseTheWeb, Target } from '@serenity-js/webdriverio';
+ *  import { Attribute, By, PageElement } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  const shoppingList = () =>
- *      Target.the('shopping list').located(by.id('shopping-list'))
+ *      PageElement.located(By.id('shopping-list')).describedAs('shopping list');
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
- *          Ensure.that(Attribute.called('data-items-left').of(shoppingList()), equals('2')),
+ *          Ensure.that(
+ *              Attribute.called('data-items-left').of(shoppingList()),
+ *              equals('2')
+ *          ),
+ *      )
+ *
+ * @example <caption>Using Attribute as QuestionAdapter</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { Attribute, By, PageElement } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingList = () =>
+ *      PageElement.located(By.css('#shopping-list')).describedAs('shopping list')
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              Attribute.called('id').of(shoppingList()).toLocaleUpperCase(),
+ *              equals('SHOPPING-LIST')
+ *          ),
  *      )
  *
- * @example <caption>Find WebElements with a given attribute</caption>
+ * @example <caption>Find PageElements with a given attribute</caption>
  *  import { actorCalled } from '@serenity-js/core';
  *  import { Ensure, includes } from '@serenity-js/assertions';
- *  import { Attribute, BrowseTheWeb, by, Target } from '@serenity-js/webdriverio';
+ *  import { Attribute, By, PageElements } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  class ShoppingList {
  *      static items = () =>
- *          Target.all('items')
- *              .located(by.css('#shopping-list li'))
+ *          PageElements.located(By.css('#shopping-list li'))
+ *              .describedAs('items');
  *
  *      static outstandingItems = () =>
- *          ShoppingList.items
- *              .where(Attribute.called('data-state'), includes('buy'))
+ *          ShoppingList.items()
+ *              .where(Attribute.called('data-state'), includes('buy'));
  *  }
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
  *          Ensure.that(
  *              Text.ofAll(ShoppingList.outstandingItems()),
@@ -53,13 +74,18 @@ import { ElementQuestion } from './ElementQuestion';
  *          ),
  *      )
  *
- * @extends {ElementQuestion}
+ * @extends {@serenity-js/core/lib/screenplay~Question}
  * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
  */
 export class Attribute
-    extends ElementQuestion<Promise<string>>
+    extends Question<Promise<string>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string>>
 {
+    /**
+     * @private
+     */
+    private subject: string;
+
     /**
      * @param {Answerable<string>} name
      * @returns {Attribute}
@@ -72,41 +98,66 @@ export class Attribute
      * @param {Answerable<string>} name
      * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} [element]
      */
-    constructor(
+    protected constructor(
         private readonly name: Answerable<string>,
         private readonly element?: Answerable<PageElement>,
     ) {
-        super(`"${ name }" attribute of ${ element }`);
+        super();
+        this.subject = element
+            ? d`${ name } attribute of ${ element }`
+            : d`${ name } attribute`
     }
 
     /**
      * @desc
-     *  Resolves to the value of a HTML attribute of the `target` element,
-     *  located in the context of a `parent` element.
+     *  Resolves to the value of an HTML attribute of the `target` element,
+     *  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 Target.all}
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
-    of(parent: Answerable<PageElement>): Question<Promise<string>> {
-        return new Attribute(
-            this.name,
-            this.element
-                ? PageElement.of(this.element, parent)
-                : parent
-        );
+    of(parent: Answerable<PageElement>): QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
+        return Question.createAdapter(
+            new Attribute(
+                this.name,
+                this.element
+                    ? PageElement.of(this.element, parent)
+                    : parent
+            )
+        ) as QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
     }
 
     async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
+        const name = await actor.answer(this.name);
+
         if (! this.element) {
-            throw new LogicError(`Target not specified`);   // todo: better error message?
+            throw new LogicError(d`Couldn't read attribute ${ name } of an unspecified page element.`);
         }
 
         const element = await actor.answer(this.element);
-        const name    = await actor.answer(this.name);
 
         return element.attribute(name);
     }
+
+    /**
+     * @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/CssClasses.ts

@@ -1,13 +1,11 @@
-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
  *  Resolves to an array of [CSS classes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-class)
- *  of a given {@link WebElement}, represented by Answerable<{@link @wdio/types~Element}>.
+ *  of a given {@link PageElement}.
  *
  * @example <caption>Example widget</caption>
  *  <ul id="shopping-list" class="active favourite">
@@ -16,37 +14,64 @@ import { ElementQuestion } from './ElementQuestion';
  *    <li class="buy">Chocolate<li>
  *  </ul>
  *
- * @example <caption>Retrieve CSS classes of a given WebElement</caption>
+ * @example <caption>Retrieve CSS classes of a given PageElement</caption>
  *  import { actorCalled } from '@serenity-js/core';
  *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, CssClasses, Target } from '@serenity-js/webdriverio';
+ *  import { By, CssClasses, PageElement } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  const shoppingList = () =>
- *      Target.the('shopping list').located(by.id('shopping-list'))
+ *      PageElement.located(By.css('#shopping-list')).describedAs('shopping list')
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
- *          Ensure.that(CssClasses.of(shoppingList()), equals([ 'active', 'favourite' ])),
+ *          Ensure.that(
+ *              CssClasses.of(shoppingList()),
+ *              equals([ 'active', 'favourite' ])
+ *          ),
+ *      )
+ *
+ * @example <caption>Using CssClasses as QuestionAdapter</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *  import { By, CssClasses, PageElement } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingList = () =>
+ *      PageElement.located(By.css('#shopping-list')).describedAs('shopping list')
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(
+ *              CssClasses.of(shoppingList()).length,
+ *              equals(2)
+ *          ),
+ *          Ensure.that(
+ *              CssClasses.of(shoppingList())[0],
+ *              equals('active')
+ *          ),
  *      )
  *
- * @example <caption>Find WebElements with a given class</caption>
+ * @example <caption>Find PageElements with a given class</caption>
  *  import { actorCalled } from '@serenity-js/core';
  *  import { Ensure, contain } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, by, CssClasses, Target } from '@serenity-js/webdriverio';
+ *  import { By, CssClasses, PageElement } from '@serenity-js/web';
+ *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
  *
  *  class ShoppingList {
  *      static items = () =>
- *          Target.all('items')
- *              .located(by.css('#shopping-list li'))
+ *          PageElements.located(By.css('#shopping-list li'))
+ *              .describedAs('items')
  *
  *      static outstandingItems = () =>
- *          ShoppingList.items
+ *          ShoppingList.items()
  *              .where(CssClasses, contain('buy'))
  *  }
  *
  *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
+ *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  *      .attemptsTo(
  *          Ensure.that(
  *              Text.ofAll(ShoppingList.outstandingItems()),
@@ -54,41 +79,48 @@ import { ElementQuestion } from './ElementQuestion';
  *          ),
  *      )
  *
- * @extends {ElementQuestion}
+ * @extends {@serenity-js/core/lib/screenplay~Question}
  * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
  */
 export class CssClasses
-    extends ElementQuestion<Promise<string[]>>
+    extends Question<Promise<string[]>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string[]>>
 {
     /**
-     * @param {Question<PageElement> | PageElement} target
-     * @returns {CssClasses}
+     * @private
      */
-    static of(target: Answerable<PageElement>): CssClasses {
-        return new CssClasses(target);
+    private subject: string;
+
+    /**
+     * @param {@serenity-js/core/lib/screenplay~Answerable<PageElement>} pageElement
+     * @returns {@serenity-js/core/lib/screenplay~QuestionAdapter<string[]>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     */
+    static of(pageElement: Answerable<PageElement>): QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>> {
+        return Question.createAdapter(new CssClasses(pageElement)) as QuestionAdapter<string[]> & MetaQuestion<Answerable<PageElement>, Promise<string[]>>;
     }
 
     /**
-     * @param {Question<PageElement> | PageElement} target
+     * @param {@serenity-js/core/lib/screenplay~Answerable<PageElement>} pageElement
      */
-    constructor(private readonly target: Answerable<PageElement>) {
-        super(formatted `CSS classes of ${ target}`);
+    protected constructor(private readonly pageElement: Answerable<PageElement>) {
+        super();
+        this.subject = d`CSS classes of ${ pageElement}`;
     }
 
     /**
      * @desc
-     *  Resolves to an array of CSS classes of the `target` element,
-     *  located in the context of a `parent` element.
+     *  Resolves to an array of CSS classes of the `pageElement`,
+     *  located within the `parent` element.
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} parent
+     * @param {@serenity-js/core/lib/screenplay~Answerable<PageElement>} parent
      * @returns {Question<Promise<string[]>>}
      *
-     * @see {@link Target.all}
      * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
      */
     of(parent: Answerable<PageElement>): Question<Promise<string[]>> {
-        return new CssClasses(PageElement.of(this.target, parent));
+        return new CssClasses(PageElement.of(this.pageElement, parent));
     }
 
     /**
@@ -104,7 +136,7 @@ export class CssClasses
      * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
      */
     async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
-        const element = await this.resolve(actor, this.target);
+        const element = await actor.answer(this.pageElement);
 
         return element.attribute('class')
             .then(attribute => attribute ?? '')
@@ -115,4 +147,24 @@ export class CssClasses
                 .filter(cssClass => !! cssClass),
             );
     }
+
+    /**
+     * @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/Selected.ts

@@ -1,4 +1,4 @@
-import { Answerable, Question } from '@serenity-js/core';
+import { Answerable, List, Question } from '@serenity-js/core';
 import { formatted } from '@serenity-js/core/lib/io';
 
 import { By, PageElement, PageElements } from '../models';
@@ -99,15 +99,15 @@ export class Selected {
      * @param {Answerable<PageElement>} pageElement
      *  A {@link Target} identifying the `<select>` element of interest
      *
-     * @returns {Question<Promise<string[]>>}
+     * @returns {@serenity-js/core/lib/screenplay/questions~List<string>}
      *
      * @see {@link Select.values}
      */
-    static valuesOf(pageElement: Answerable<PageElement>): Question<Promise<string[]>> {
+    static valuesOf(pageElement: Answerable<PageElement>): List<string> {
         return PageElements.located(By.css('option:checked'))
             .of(pageElement)
             .eachMappedTo(Value)
-            .describedAs(formatted `values selected in ${ pageElement }`) as Question<Promise<string[]>>;
+            .describedAs(formatted `values selected in ${ pageElement }`);
     }
 
     /**
@@ -201,14 +201,14 @@ export class Selected {
      * @param {Answerable<PageElement>} pageElement
      *  A {@link Target} identifying the `<select>` element of interest
      *
-     * @returns {Question<Promise<string[]>>}
+     * @returns {@serenity-js/core/lib/screenplay/questions~List<string>}
      *
      * @see {@link Select.options}
      */
-    static optionsIn(pageElement: Answerable<PageElement>): Question<Promise<string[]>> {
+    static optionsIn(pageElement: Answerable<PageElement>): List<string> {
         return PageElements.located(By.css('option:checked'))
             .of(pageElement)
             .eachMappedTo(Text)
-            .describedAs(formatted `options selected in ${ pageElement }`) as Question<Promise<string[]>>;
+            .describedAs(formatted `options selected in ${ pageElement }`);
     }
 }