@serenity-js/web 3.0.0-rc.0

package/src/screenplay/models/Page.ts

@@ -0,0 +1,147 @@
+import { Adapter, Expectation, ExpectationMet, ExpectationOutcome, LogicError, Question } from '@serenity-js/core';
+import { URL } from 'url';
+
+import { BrowseTheWeb } from '../abilities';
+
+export abstract class Page {
+    static current(): Question<Promise<Page>> & Adapter<Page> {
+        return Question.about<Promise<Page>>('current page', actor => {
+            return BrowseTheWeb.as(actor).currentPage();
+        });
+    }
+
+    static whichName(expectation: Expectation<any, string>): Question<Promise<Page>> & Adapter<Page> {
+        return Question.about(`page which name does ${ expectation }`, async actor => {
+            const pages     = await BrowseTheWeb.as(actor).allPages();
+            const matcher   = await actor.answer(expectation);
+
+            return Page.findMatchingPage(
+                `name does ${ expectation }`,
+                pages,
+                page => page.name().then(matcher)
+            );
+        });
+    }
+
+    static whichTitle(expectation: Expectation<any, string>): Question<Promise<Page>> & Adapter<Page> {
+        return Question.about(`page which title does ${ expectation }`, async actor => {
+            const pages     = await BrowseTheWeb.as(actor).allPages();
+            const matcher   = await actor.answer(expectation);
+
+            return Page.findMatchingPage(
+                `title does ${ expectation }`,
+                pages,
+                page => page.title().then(title => {
+                    return matcher(title);
+                })
+            );
+        });
+    }
+
+    static whichUrl(expectation: Expectation<any, string>): Question<Promise<Page>> & Adapter<Page> {
+        return Question.about(`page which URL does ${ expectation }`, async actor => {
+            const pages     = await BrowseTheWeb.as(actor).allPages();
+            const matcher   = await actor.answer(expectation);
+
+            return Page.findMatchingPage(
+                `url does ${ expectation }`,
+                pages,
+                page => page.url().then(url => matcher(url.toString()))
+            );
+        });
+    }
+
+    private static async findMatchingPage(expectationDescription: string, pages: Page[], matcher: (page: Page) => Promise<ExpectationOutcome<any, any>>): Promise<Page> {
+        for (const page of pages) {
+            const outcome  = await matcher(page);
+
+            if (outcome instanceof ExpectationMet) {
+                return page;
+            }
+        }
+
+        throw new LogicError(`Couldn't find a page which ${ expectationDescription }`);
+    }
+
+    constructor(
+        protected readonly handle: string,
+    ) {
+    }
+
+    /**
+     * @desc
+     *  Retrieves the document title of the current top-level browsing context, equivalent to calling `document.title`.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
+     *
+     * @returns {Promise<string>}
+     */
+    abstract title(): Promise<string>;
+
+    /**
+     * @desc
+     *  Retrieves the URL of the current top-level browsing context.
+     *
+     * @returns {Promise<URL>}
+     */
+    abstract url(): Promise<URL>;
+
+    /**
+     * @desc
+     *  Retrieves the name of the current top-level browsing context.
+     *
+     * @returns {Promise<string>}
+     */
+    abstract name(): Promise<string>;
+
+    /**
+     * @desc
+     *  Checks if a given window / tab / page is open and can be switched to.
+     *
+     * @returns {Promise<string>}
+     */
+    abstract isPresent(): Promise<boolean>;
+
+    /**
+     * @desc
+     *  Returns the actual viewport size available for the given page,
+     *  excluding any scrollbars.
+     *
+     * @returns {Promise<{ width: number, height: number }>}
+     */
+    abstract viewportSize(): Promise<{ width: number, height: number }>;
+
+    /**
+     *
+     * @param size
+     */
+    abstract setViewportSize(size: { width: number, height: number }): Promise<void>;
+
+    /**
+     * @desc
+     *  Switches the current top-level browsing context to the given page
+     *
+     * @returns {Promise<void>}
+     */
+    abstract switchTo(): Promise<void>;
+
+    /**
+     * @desc
+     *  Closes the given page.
+     *
+     * @returns {Promise<void>}
+     */
+    abstract close(): Promise<void>;
+
+    /**
+     * @desc
+     *  Closes any open pages, except for this one.
+     *
+     * @returns {Promise<void>}
+     */
+    abstract closeOthers(): Promise<void>;
+
+    toString(): string {
+        return `page (handle=${ this.handle })`;
+    }
+}

package/src/screenplay/models/PageElement.ts

@@ -0,0 +1,95 @@
+import { Adapter, Answerable, format, LogicError, Question } from '@serenity-js/core';
+
+import { BrowseTheWeb } from '../abilities';
+
+const d = format({ markQuestions: false });
+const f = format({ markQuestions: true });
+
+export abstract class PageElement<NativeElementContext = any, NativeElement = any> {
+    static of(childElement: Answerable<PageElement>, parentElement: Answerable<PageElement>): Question<Promise<PageElement>> & Adapter<PageElement> {
+        return Question.about(d`${ childElement } of ${ parentElement })`, async actor => {
+            const child     = await actor.answer(childElement);
+            const parent    = await actor.answer(parentElement);
+
+            return child.of(parent);
+        });
+    }
+
+    static locatedByCss(selector: Answerable<string>): Question<Promise<PageElement>> & Adapter<PageElement> {
+        return Question.about(f`page element located by css (${selector})`, async actor => {
+            const cssSelector = await actor.answer(selector);
+
+            return BrowseTheWeb.as(actor).findByCss(cssSelector);
+        });
+    }
+
+    static locatedByCssContainingText(selector: Answerable<string>, text: Answerable<string>): Question<Promise<PageElement>> & Adapter<PageElement> {
+        return Question.about(f`page element located by css (${selector}) containing text ${ text }`, async actor => {
+            const cssSelector = await actor.answer(selector);
+            const desiredText = await actor.answer(text);
+
+            return BrowseTheWeb.as(actor).findByCssContainingText(cssSelector, desiredText);
+        });
+    }
+
+    static locatedById(selector: Answerable<string>): Question<Promise<PageElement>> & Adapter<PageElement> {
+        return Question.about(f`page element located by id (${selector})`, async actor => {
+            const idSelector = await actor.answer(selector);
+
+            return BrowseTheWeb.as(actor).findById(idSelector);
+        });
+    }
+
+    static locatedByTagName(tagName: Answerable<string>): Question<Promise<PageElement>> & Adapter<PageElement> {
+        return Question.about(f`page element located by tag name (${tagName})`, async actor => {
+            const tagNameSelector = await actor.answer(tagName);
+
+            return BrowseTheWeb.as(actor).findByTagName(tagNameSelector);
+        });
+    }
+
+    static locatedByXPath(selector: Answerable<string>): Question<Promise<PageElement>> & Adapter<PageElement> {
+        return Question.about(f`page element located by xpath (${selector})`, async actor => {
+            const xpathSelector = await actor.answer(selector);
+
+            return BrowseTheWeb.as(actor).findByXPath(xpathSelector);
+        });
+    }
+
+    constructor(
+        protected readonly context: () => Promise<NativeElementContext> | NativeElementContext,
+        protected readonly locator: (root: NativeElementContext) => Promise<NativeElement> | NativeElement
+    ) {
+    }
+
+    abstract of(parent: PageElement): PageElement;
+
+    async nativeElement(): Promise<NativeElement> {
+        try {
+            const context = await this.context();
+            return this.locator(context);
+        }
+        catch (error) {
+            throw new LogicError(`Couldn't find element`, error);
+        }
+    }
+
+    abstract enterValue(value: string | number | Array<string | number>): Promise<void>;
+    abstract clearValue(): Promise<void>;
+    abstract click(): Promise<void>;
+    abstract doubleClick(): Promise<void>;
+    abstract scrollIntoView(): Promise<void>;
+    abstract hoverOver(): Promise<void>;
+    abstract rightClick(): Promise<void>;    // todo: should this be a click() call with a parameter?
+
+    abstract attribute(name: string): Promise<string>;
+    abstract text(): Promise<string>;
+    abstract value(): Promise<string>;
+
+    abstract isActive(): Promise<boolean>;
+    abstract isClickable(): Promise<boolean>;
+    abstract isDisplayed(): Promise<boolean>;
+    abstract isEnabled(): Promise<boolean>;
+    abstract isPresent(): Promise<boolean>;
+    abstract isSelected(): Promise<boolean>;
+}

package/src/screenplay/models/PageElements.ts

@@ -0,0 +1,70 @@
+import { Adapter, Answerable, format, LogicError, Question } from '@serenity-js/core';
+
+import { BrowseTheWeb } from '../abilities';
+import { PageElement } from './PageElement';
+
+const d = format({ markQuestions: false });
+const f = format({ markQuestions: true });
+
+export abstract class PageElements<NativeElementContext = any, NativeElementList = any, NativeElement = any>
+// todo: implements List (Attribute.spec.ts)
+{
+    static of(childElements: Answerable<PageElements>, parentElement: Answerable<PageElement>): Question<Promise<PageElements>> & Adapter<PageElements> {
+        return Question.about(d `${ childElements } of ${ parentElement })`, async actor => {
+            const children  = await actor.answer(childElements);
+            const parent    = await actor.answer(parentElement);
+
+            return children.of(parent);
+        });
+    }
+
+    static locatedByCss(selector: Answerable<string>): Question<Promise<PageElements>> & Adapter<PageElements> {
+        return Question.about(f `page elements located by css (${selector})`, async actor => {
+            const value = await actor.answer(selector);
+            return BrowseTheWeb.as(actor).findAllByCss(value);
+        });
+    }
+
+    static locatedByTagName(selector: Answerable<string>): Question<Promise<PageElements>> & Adapter<PageElements> {
+        return Question.about(f `page elements located by tag name (${selector})`, async actor => {
+            const tagNameSelector = await actor.answer(selector);
+            return BrowseTheWeb.as(actor).findAllByTagName(tagNameSelector);
+        });
+    }
+
+    static locatedByXPath(selector: Answerable<string>): Question<Promise<PageElements>> & Adapter<PageElements> {
+        return Question.about(f `page elements located by xpath (${selector})`, async actor => {
+            const xpathSelector = await actor.answer(selector);
+            return BrowseTheWeb.as(actor).findAllByXPath(xpathSelector);
+        });
+    }
+
+    constructor(
+        protected readonly context: () => Promise<NativeElementContext> | NativeElementContext,
+        protected readonly locator: (root: NativeElementContext) => Promise<NativeElementList> | NativeElementList
+    ) {
+    }
+
+    abstract of(parent: PageElement): PageElements;
+
+    async nativeElementList(): Promise<NativeElementList> {
+        try {
+            const context = await this.context();
+            return this.locator(context);
+        }
+        catch (error) {
+            throw new LogicError(`Couldn't find elements`, error);
+        }
+    }
+
+    abstract count(): Promise<number>;
+    abstract first(): Promise<PageElement<NativeElementContext, NativeElement>>;
+    abstract last(): Promise<PageElement<NativeElementContext, NativeElement>>;
+    abstract get(index: number): Promise<PageElement<NativeElementContext, NativeElement>>;
+
+    abstract map<O>(fn: (element: PageElement, index?: number, elements?: PageElements) => Promise<O> | O): Promise<O[]>;
+
+    abstract filter(fn: (element: PageElement, index?: number) => Promise<boolean> | boolean): PageElements;
+
+    abstract forEach(fn: (element: PageElement, index?: number) => Promise<void> | void): Promise<void>;
+}

package/src/screenplay/models/index.ts

@@ -0,0 +1,6 @@
+export * from './Cookie';
+export * from './CookieData';
+export * from './ModalDialog';
+export * from './Page';
+export * from './PageElement';
+export * from './PageElements';

package/src/screenplay/questions/Attribute.ts

@@ -0,0 +1,112 @@
+import { Answerable, AnswersQuestions, LogicError, MetaQuestion, Question, 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';
+ *
+ *  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}
+ */
+export class Attribute
+    extends ElementQuestion<Promise<string>>
+    implements MetaQuestion<Answerable<PageElement>, Promise<string>>
+{
+    /**
+     * @param {Answerable<string>} name
+     * @returns {Attribute}
+     */
+    static called(name: Answerable<string>): Attribute {
+        return new Attribute(name);
+    }
+
+    /**
+     * @param {Answerable<string>} name
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} [element]
+     */
+    constructor(
+        private readonly name: Answerable<string>,
+        private readonly element?: Answerable<PageElement>,
+    ) {
+        super(`"${ name }" attribute of ${ element }`);
+    }
+
+    /**
+     * @desc
+     *  Resolves to the value of a HTML attribute of the `target` element,
+     *  located in the context of a `parent` element.
+     *
+     * @param {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 Attribute(
+            this.name,
+            this.element
+                ? PageElement.of(this.element, parent)
+                : parent
+        );
+    }
+
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string> {
+        if (! this.element) {
+            throw new LogicError(`Target not specified`);   // todo: better error message?
+        }
+
+        const element = await actor.answer(this.element);
+        const name    = await actor.answer(this.name);
+
+        return element.attribute(name);
+    }
+}

package/src/screenplay/questions/CssClasses.ts

@@ -0,0 +1,118 @@
+import { Answerable, AnswersQuestions, MetaQuestion, Question, UsesAbilities } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+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}>.
+ *
+ * @example <caption>Example widget</caption>
+ *  <ul id="shopping-list" class="active favourite">
+ *    <li class="bought">Coffee<li>
+ *    <li class="buy">Honey<li>
+ *    <li class="buy">Chocolate<li>
+ *  </ul>
+ *
+ * @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, CssClasses, Target } from '@serenity-js/webdriverio';
+ *
+ *  const shoppingList = () =>
+ *      Target.the('shopping list').located(by.id('shopping-list'))
+ *
+ *  actorCalled('Lisa')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(CssClasses.of(shoppingList()), equals([ 'active', 'favourite' ])),
+ *      )
+ *
+ * @example <caption>Find WebElements 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';
+ *
+ *  class ShoppingList {
+ *      static items = () =>
+ *          Target.all('items')
+ *              .located(by.css('#shopping-list li'))
+ *
+ *      static outstandingItems = () =>
+ *          ShoppingList.items
+ *              .where(CssClasses, contain('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}
+ */
+export class CssClasses
+    extends ElementQuestion<Promise<string[]>>
+    implements MetaQuestion<Answerable<PageElement>, Promise<string[]>>
+{
+    /**
+     * @param {Question<PageElement> | PageElement} target
+     * @returns {CssClasses}
+     */
+    static of(target: Answerable<PageElement>): CssClasses {
+        return new CssClasses(target);
+    }
+
+    /**
+     * @param {Question<PageElement> | PageElement} target
+     */
+    constructor(private readonly target: Answerable<PageElement>) {
+        super(formatted `CSS classes of ${ target}`);
+    }
+
+    /**
+     * @desc
+     *  Resolves to an array of CSS classes of the `target` element,
+     *  located in the context of a `parent` element.
+     *
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element>} 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));
+    }
+
+    /**
+     * @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}
+     */
+    async answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<string[]> {
+        const element = await this.resolve(actor, this.target);
+
+        return element.attribute('class')
+            .then(attribute => attribute ?? '')
+            .then(attribute => attribute
+                .replace(/\s+/, ' ')
+                .trim()
+                .split(' ')
+                .filter(cssClass => !! cssClass),
+            );
+    }
+}

package/src/screenplay/questions/ElementQuestion.ts

@@ -0,0 +1,60 @@
+import { Answerable, AnswersQuestions, LogicError, Question } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+import { PageElement, PageElements } from '../models';
+
+/**
+ * @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=PageElement|PageElements>(
+        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;
+    }
+}

package/src/screenplay/questions/LastScriptExecution.ts

@@ -0,0 +1,21 @@
+import { Question } from '@serenity-js/core';
+
+import { BrowseTheWeb } from '../abilities';
+
+/**
+ * @desc
+ *  Returns the result of last script executed via {@link ExecuteScript}
+ */
+export class LastScriptExecution {
+
+    /**
+     * @desc
+     *  Enables asserting on the result of a function executed via {@link ExecuteScript}.
+     *
+     * @returns {Question<R>}
+     */
+    static result<R>(): Question<R> {
+        return Question.about(`last script execution result`, actor =>
+            BrowseTheWeb.as(actor).lastScriptExecutionResult());
+    }
+}