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

package/src/screenplay/models/index.ts

@@ -1,8 +1,15 @@
+export * from './BrowserCapabilities';
+export * from './BrowsingSession';
 export * from './Cookie';
 export * from './CookieData';
+export * from './dialogs';
+export * from './Key';
 export * from './Locator';
-export * from './ModalDialog';
 export * from './Page';
 export * from './PageElement';
 export * from './PageElements';
+export * from './RootLocator';
+export * from './SelectOption';
 export * from './selectors';
+export * from './Switchable';
+export * from './SwitchableOrigin';

package/src/screenplay/models/selectors/By.ts

@@ -2,11 +2,21 @@ import { Answerable, f, Question } from '@serenity-js/core';
 
 import { ByCss } from './ByCss';
 import { ByCssContainingText } from './ByCssContainingText';
+import { ByDeepCss } from './ByDeepCss';
 import { ById } from './ById';
 import { ByTagName } from './ByTagName';
 import { ByXPath } from './ByXPath';
 
+/**
+ * @group Models
+ */
 export class By {
+
+    /**
+     * Locates a {@apilink PageElement} using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).
+     *
+     * @param selector
+     */
     static css(selector: Answerable<string>): Question<Promise<ByCss>> {
         return Question.about(f`by css (${selector})`, async actor => {
             const bySelector = await actor.answer(selector);
@@ -14,6 +24,13 @@ export class By {
         });
     }
 
+    /**
+     * Locates a {@apilink PageElement} with a given [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
+     * using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).
+     *
+     * @param selector
+     * @param text
+     */
     static cssContainingText(selector: Answerable<string>, text: Answerable<string>): Question<Promise<ByCssContainingText>> {
         return Question.about(f`by css (${selector}) containing text ${ text }`, async actor => {
             const bySelector = await actor.answer(selector);
@@ -22,6 +39,24 @@ export class By {
         });
     }
 
+    /**
+     * Locates a {@apilink PageElement} using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors)
+     * capable of piercing [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)-piercing
+     *
+     * @param selector
+     */
+    static deepCss(selector: Answerable<string>): Question<Promise<ByCss>> {
+        return Question.about(f`by deep css (${selector})`, async actor => {
+            const bySelector = await actor.answer(selector);
+            return new ByDeepCss(bySelector);
+        });
+    }
+
+    /**
+     * Locates a {@apilink PageElement} using its [id](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors).
+     *
+     * @param selector
+     */
     static id(selector: Answerable<string>): Question<Promise<ById>> {
         return Question.about(f`by id (${selector})`, async actor => {
             const bySelector = await actor.answer(selector);
@@ -29,6 +64,11 @@ export class By {
         });
     }
 
+    /**
+     * Locates a {@apilink PageElement} using the name of its [HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
+     *
+     * @param selector
+     */
     static tagName(selector: Answerable<string>): Question<Promise<ByTagName>> {
         return Question.about(f`by tag name (${selector})`, async actor => {
             const bySelector = await actor.answer(selector);
@@ -36,6 +76,11 @@ export class By {
         });
     }
 
+    /**
+     * Locates a {@apilink PageElement} using an [XPath selector](https://developer.mozilla.org/en-US/docs/Web/XPath).
+     *
+     * @param selector
+     */
     static xpath(selector: Answerable<string>): Question<Promise<ByXPath>> {
         return Question.about(f`by xpath (${selector})`, async actor => {
             const bySelector = await actor.answer(selector);

package/src/screenplay/models/selectors/ByCss.ts

@@ -1,5 +1,12 @@
 import { Selector } from './Selector';
 
+/**
+ * Locates a {@apilink PageElement} using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).
+ *
+ * **Pro tip:** Instantiate using {@apilink By.css}
+ *
+ * @group Models
+ */
 export class ByCss extends Selector {
     constructor(public readonly value: string) {
         super();

package/src/screenplay/models/selectors/ByCssContainingText.ts

@@ -1,5 +1,13 @@
 import { Selector } from './Selector';
 
+/**
+ * Locates a {@apilink PageElement} with a given [`innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText)
+ * using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors).
+ *
+ * **Pro tip:** Instantiate using {@apilink By.cssContainingText}
+ *
+ * @group Models
+ */
 export class ByCssContainingText extends Selector {
     constructor(public readonly value: string, public readonly text: string) {
         super();

package/src/screenplay/models/selectors/ByDeepCss.ts

@@ -0,0 +1,15 @@
+import { Selector } from './Selector';
+
+/**
+ * Locates a {@apilink PageElement} using a [CSS selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors)
+ * capable of piercing [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)-piercing
+ *
+ * **Pro tip:** Instantiate using {@apilink By.deepCss}
+ *
+ * @group Models
+ */
+export class ByDeepCss extends Selector {
+    constructor(public readonly value: string) {
+        super();
+    }
+}

package/src/screenplay/models/selectors/ById.ts

@@ -1,5 +1,12 @@
 import { Selector } from './Selector';
 
+/**
+ * Locates a {@apilink PageElement} using its [id](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors).
+ *
+ * **Pro tip:** Instantiate using {@apilink By.id}
+ *
+ * @group Models
+ */
 export class ById extends Selector {
     constructor(public readonly value: string) {
         super();

package/src/screenplay/models/selectors/ByTagName.ts

@@ -1,5 +1,12 @@
 import { Selector } from './Selector';
 
+/**
+ * Locates a {@apilink PageElement} using the name of its [HTML tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
+ *
+ * **Pro tip:** Instantiate using {@apilink By.tagName}
+ *
+ * @group Models
+ */
 export class ByTagName extends Selector {
     constructor(public readonly value: string) {
         super();

package/src/screenplay/models/selectors/ByXPath.ts

@@ -1,5 +1,12 @@
 import { Selector } from './Selector';
 
+/**
+ * Locates a {@apilink PageElement} using an [XPath selector](https://developer.mozilla.org/en-US/docs/Web/XPath).
+ *
+ * **Pro tip:** Instantiate using {@apilink By.xpath}
+ *
+ * @group Models
+ */
 export class ByXPath extends Selector {
     constructor(public readonly value: string) {
         super();

package/src/screenplay/models/selectors/Selector.ts

@@ -1,9 +1,14 @@
 import { f } from '@serenity-js/core';
 
+/**
+ * Describes a selector you use to identify a {@apilink PageElement} or a group of {@apilink PageElements}.
+ *
+ * @group Models
+ */
 export abstract class Selector {
 
     toString(): string {
-        const selectorDescription   = this.constructor.name.replace(/([a-z]+)([A-Z])/g, '$1 $2').toLowerCase();
+        const selectorDescription   = this.constructor.name.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
         const parametersDescription = Object.keys(this).map(field => f`${this[field]}`).join(', ');
 
         return `${ selectorDescription } (${ parametersDescription })`;

package/src/screenplay/models/selectors/index.ts

@@ -1,6 +1,7 @@
 export * from './By';
 export * from './ByCss';
 export * from './ByCssContainingText';
+export * from './ByDeepCss';
 export * from './ById';
 export * from './ByTagName';
 export * from './ByXPath';

package/src/screenplay/questions/Attribute.ts

@@ -1,112 +1,173 @@
-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}>
- *
- * @example <caption>Example widget</caption>
- *  <ul id="shopping-list" data-items-left="2">
- *    <li data-state="bought">Coffee<li>
- *    <li data-state="buy">Honey<li>
- *    <li data-state="buy">Chocolate<li>
- *  </ul>
- *
- * @example <caption>Retrieve a HTML attribute of a given WebElement</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *  import { Attribute, by, BrowseTheWeb, Target } from '@serenity-js/webdriverio';
+ * Uses the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+ * the value of the specified HTML attribute of a given {@apilink PageElement}.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <ul id="shopping-list" data-items-left="2">
+ *   <li data-state="bought">Coffee<li>
+ *   <li data-state="buy">Honey<li>
+ *   <li data-state="buy">Chocolate<li>
+ * </ul>
+ * ```
+ *
+ * ## Retrieve an HTML attribute of a given {@apilink PageElement}
+ *
+ * ```ts
+ *  import { actorCalled } from '@serenity-js/core'
+ *  import { Ensure, equals } from '@serenity-js/assertions'
+ *  import { Attribute, By, PageElement } from '@serenity-js/web'
  *
  *  const shoppingList = () =>
- *      Target.the('shopping list').located(by.id('shopping-list'))
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(Attribute.called('data-items-left').of(shoppingList()), equals('2')),
- *      )
- *
- * @example <caption>Find WebElements 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';
- *
- *  class ShoppingList {
- *      static items = () =>
- *          Target.all('items')
- *              .located(by.css('#shopping-list li'))
- *
- *      static outstandingItems = () =>
- *          ShoppingList.items
- *              .where(Attribute.called('data-state'), includes('buy'))
- *  }
- *
- *  actorCalled('Lisa')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(
- *              Text.ofAll(ShoppingList.outstandingItems()),
- *              equals([ 'Honey', 'Chocolate' ])
- *          ),
- *      )
- *
- * @extends {ElementQuestion}
- * @implements {@serenity-js/core/lib/screenplay/questions~MetaQuestion}
+ *    PageElement.located(By.id('shopping-list'))
+ *      .describedAs('shopping list')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       Attribute.called('data-items-left').of(shoppingList()),
+ *       equals('2')
+ *     ),
+ *   )
+ * ```
+ *
+ * ## Using `Attribute` as {@apilink QuestionAdapter}
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Attribute, By, PageElement } from '@serenity-js/web'
+ *
+ * const shoppingList = () =>
+ *   PageElement.located(By.css('#shopping-list'))
+ *     .describedAs('shopping list')
+ *
+ * await actorCalled('Lisa')
+ *   .attemptsTo(
+ *     Ensure.that(
+ *       Attribute.called('id').of(shoppingList()).toLocaleUpperCase(),
+ *       equals('SHOPPING-LIST')
+ *     ),
+ * )
+ * ```
+ *
+ * ## Using as filter in {@apilink PageElements|Page Element Query Language}
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, includes } from '@serenity-js/assertions'
+ * import { Attribute, By, PageElements } from '@serenity-js/web'
+ *
+ * class ShoppingList {
+ *   static items = () =>
+ *     PageElements.located(By.css('#shopping-list li'))
+ *       .describedAs('items')
+ *
+ *   static outstandingItems = () =>
+ *     ShoppingList.items()
+ *       .where(
+ *         Attribute.called('data-state'),
+ *         includes('buy')
+ *       )
+ * }
+ *
+ * await actorCalled('Lisa')
+ * .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ * .attemptsTo(
+ *   Ensure.that(
+ *     Text.ofAll(ShoppingList.outstandingItems()),
+ *     equals([ 'Honey', 'Chocolate' ])
+ *   ),
+ * )
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink MetaQuestion}
+ * - {@apilink QuestionAdapter}
+ * - {@apilink Question}
+ *
+ * @group Questions
  */
 export class Attribute
-    extends ElementQuestion<Promise<string>>
+    extends Question<Promise<string>>
     implements MetaQuestion<Answerable<PageElement>, Promise<string>>
 {
+    private subject: string;
+
     /**
-     * @param {Answerable<string>} name
-     * @returns {Attribute}
+     * Instantiates a {@apilink Question} that uses
+     * the {@apilink Actor|actor's} {@apilink Ability|ability} to {@apilink BrowseTheWeb} to retrieve
+     * the value of the specified HTML attribute of a given {@apilink PageElement}.
+     *
+     * @param name
+     *  The name of the attribute to retrieve
      */
     static called(name: Answerable<string>): Attribute {
         return new Attribute(name);
     }
 
-    /**
-     * @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 `pageElement`.
      *
-     * @param {Answerable<PageElement>} parent
-     * @returns {Question<Promise<string[]>>}
+     * #### Learn more
+     * - {@apilink MetaQuestion}
      *
-     * @see {@link Target.all}
-     * @see {@link @serenity-js/core/lib/screenplay/questions~MetaQuestion}
+     * @param pageElement
      */
-    of(parent: Answerable<PageElement>): Question<Promise<string>> {
-        return new Attribute(
-            this.name,
-            this.element
-                ? PageElement.of(this.element, parent)
-                : parent
-        );
+    of(pageElement: Answerable<PageElement>): QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>> {
+        return Question.createAdapter(
+            new Attribute(
+                this.name,
+                this.element
+                    ? PageElement.of(this.element, pageElement)
+                    : pageElement
+            )
+        ) as QuestionAdapter<string> & MetaQuestion<Answerable<PageElement>, Promise<string>>;
     }
 
+    /**
+     * @inheritDoc
+     */
     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);
     }
+
+    /**
+     * @inheritDoc
+     */
+    describedAs(subject: string): this {
+        this.subject = subject;
+        return this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    toString(): string {
+        return this.subject;
+    }
 }