@serenity-js/web 3.0.0-rc.0

package/src/expectations/ElementExpectation.ts

@@ -0,0 +1,32 @@
+import { AnswersQuestions, Expectation, ExpectationMet, ExpectationNotMet, ExpectationOutcome } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+
+/**
+ * @access private
+ */
+export class ElementExpectation extends Expectation<any, PageElement> {
+    static forElementTo(message: string, fn: (actual: PageElement) => Promise<boolean>): Expectation<any, PageElement> {
+        return new ElementExpectation(message, fn);
+    }
+
+    constructor(
+        subject: string,
+        private readonly fn: (actual: PageElement) => Promise<boolean>,
+    ) {
+        super(subject);
+    }
+
+    answeredBy(actor: AnswersQuestions): (actual: PageElement) => Promise<ExpectationOutcome<boolean, PageElement>> {
+        return (actual: PageElement) =>
+            this.fn(actual)
+                .then(expectationMet =>
+                    expectationMet
+                        ? new ExpectationMet(this.toString(), undefined, actual)
+                        : new ExpectationNotMet(this.toString(), undefined, actual),
+                )
+                .catch(error => {
+                    return new ExpectationNotMet(`${ this.toString() } (${ error.message })`, undefined, actual);
+                });
+    }
+}

package/src/expectations/index.ts

@@ -0,0 +1,6 @@
+export * from './isActive';
+export * from './isClickable';
+export * from './isEnabled';
+export * from './isPresent';
+export * from './isSelected';
+export * from './isVisible';

package/src/expectations/isActive.ts

@@ -0,0 +1,22 @@
+import { Expectation } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+import { ElementExpectation } from './ElementExpectation';
+
+/**
+ * @desc
+ *  Expectation that the element is active (has focus).
+ *  If the selector matches multiple elements, it will return true if one of the elements has focus.
+ *
+ * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
+ *
+ * @see https://webdriver.io/docs/api/element/isFocused/
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
+ * @see {@link Wait}
+ */
+// todo: isFocused?
+export function isActive(): Expectation<boolean, PageElement> {
+    return ElementExpectation.forElementTo('become active', actual => actual.isActive());
+}
+

package/src/expectations/isClickable.ts

@@ -0,0 +1,32 @@
+import { and } from '@serenity-js/assertions';
+import { Expectation } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+import { ElementExpectation } from './ElementExpectation';
+import { isEnabled } from './isEnabled';
+import { isVisible } from './isVisible';
+
+/**
+ * @desc
+ *  Expectation that an element is clickable, which means:
+ *  - it exists
+ *  - it is visible
+ *  - it is within viewport (if not, try to scroll to it)
+ *  - its center is not overlapped with another element
+ *  - it is not disabled
+ *  otherwise return false.
+ *
+ * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
+ *
+ * @see https://webdriver.io/docs/api/element/isClickable/
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
+ * @see {@link Wait}
+ */
+export function isClickable(): Expectation<boolean, PageElement> {
+    return Expectation.to<PageElement>('become clickable').soThatActual(and(
+        isVisible(),
+        isEnabled(),
+        ElementExpectation.forElementTo('become clickable', actual => actual.isClickable())
+    ));
+}

package/src/expectations/isEnabled.ts

@@ -0,0 +1,19 @@
+import { Expectation } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+import { ElementExpectation } from './ElementExpectation';
+
+/**
+ * @desc
+ *  Expectation that the element is enabled.
+ *
+ * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
+ *
+ * @see https://webdriver.io/docs/api/element/isEnabled/
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
+ * @see {@link Wait}
+ */
+export function isEnabled(): Expectation<boolean, PageElement> {
+    return ElementExpectation.forElementTo('become enabled', actual => actual.isEnabled());
+}

package/src/expectations/isPresent.ts

@@ -0,0 +1,21 @@
+import { Expectation } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+import { ElementExpectation } from './ElementExpectation';
+
+/**
+ * @desc
+ *  Expectation that the element is present in the DOM of a page.
+ *  Please note that this does not necessarily mean that the element is visible.
+ *
+ * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
+ *
+ * @see https://webdriver.io/docs/api/element/isExisting/
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
+ * @see {@link Wait}
+ */
+// todo: make it generic isPresent: Promise<boolean> | boolean
+export function isPresent(): Expectation<boolean, PageElement> {
+    return ElementExpectation.forElementTo('become present', actual => actual.isPresent());
+}

package/src/expectations/isSelected.ts

@@ -0,0 +1,24 @@
+import { and } from '@serenity-js/assertions';
+import { Expectation } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+import { ElementExpectation } from './ElementExpectation';
+import { isPresent } from './isPresent';
+
+/**
+ * @desc
+ *  Expectation that an `<option>` or `<input>` element of type checkbox or radio is currently selected.
+ *
+ * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
+ *
+ * @see https://webdriver.io/docs/api/element/isSelected/
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
+ * @see {@link Wait}
+ */
+export function isSelected(): Expectation<boolean, PageElement> {
+    return Expectation.to<PageElement>('become selected').soThatActual(and(
+        isPresent(),
+        ElementExpectation.forElementTo('become selected', actual => actual.isSelected()),
+    ));
+}

package/src/expectations/isVisible.ts

@@ -0,0 +1,28 @@
+import { and } from '@serenity-js/assertions';
+import { Expectation } from '@serenity-js/core';
+
+import { PageElement } from '../screenplay';
+import { ElementExpectation } from './ElementExpectation';
+import { isPresent } from './isPresent';
+
+/**
+ * @desc
+ *  Expectation that the element is present in the DOM of the page and visible.
+ *
+ * @returns {@serenity-js/core/lib/screenplay/questions~Expectation<boolean, Element<'async'>>}
+ *
+ * @see https://webdriver.io/docs/api/element/isDisplayed/
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/core/lib/screenplay/questions~Check}
+ * @see {@link Wait}
+ */
+export function isVisible(): Expectation<boolean, PageElement> {
+    return Expectation.to<PageElement>('become visible').soThatActual(and(
+        isPresent(),
+        isDisplayed(),
+    ));
+}
+
+function isDisplayed(): Expectation<any, PageElement> {
+    return ElementExpectation.forElementTo('become displayed', actual => actual.isDisplayed());
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './errors';
+export * from './expectations';
+export * from './input';
+export * from './screenplay';
+export * from './stage';

package/src/input/Key.ts

@@ -0,0 +1,83 @@
+/**
+ * @desc
+ *  Represents pressable keys that aren't text to be used with {@link Press}.
+ *
+ *  Note that modifier like Shift, Alt and Meta (a.k.a. Command on Mac) will stay pressed
+ *
+ * @enum {string}
+ * @see {@link Press}
+ * @see https://w3c.github.io/webdriver/webdriver-spec.html#keyboard-actions
+ * @see https://github.com/puppeteer/puppeteer/blob/v7.1.0/src/common/USKeyboardLayout.ts
+ * @see https://github.com/SeleniumHQ/selenium/blob/trunk/javascript/node/selenium-webdriver/lib/input.js#L46
+ * @see https://github.com/webdriverio/webdriverio/blob/main/packages/wdio-utils/src/constants.ts#L5
+ */
+export class Key {
+    public static Alt = new Key('Alt', '\uE00A', true);
+    public static ArrowDown = new Key('ArrowDown', '\uE015');
+    public static ArrowLeft = new Key('ArrowLeft', '\uE012');
+    public static ArrowRight = new Key('ArrowRight', '\uE014');
+    public static ArrowUp = new Key('ArrowUp', '\uE013');
+    public static Backspace = new Key('Backspace', '\uE003');
+    public static Cancel = new Key('Cancel', '\uE001');
+    public static Clear = new Key('Clear', '\uE005');
+    public static Control = new Key('Control', '\uE009', true);
+    public static Delete = new Key('Delete', '\uE017');
+    public static End = new Key('End', '\uE010');
+    public static Enter = new Key('Enter', '\uE007');
+    public static Escape = new Key('Escape', '\uE00C');
+    public static F1 = new Key('F1', '\uE031');
+    public static F2 = new Key('F2', '\uE032');
+    public static F3 = new Key('F3', '\uE033');
+    public static F4 = new Key('F4', '\uE034');
+    public static F5 = new Key('F5', '\uE035');
+    public static F6 = new Key('F6', '\uE036');
+    public static F7 = new Key('F7', '\uE037');
+    public static F8 = new Key('F8', '\uE038');
+    public static F9 = new Key('F9', '\uE039');
+    public static F10 = new Key('F10', '\uE03A');
+    public static F11 = new Key('F11', '\uE03B');
+    public static F12 = new Key('F12', '\uE03C');
+    public static Help = new Key('Help', '\uE002');
+    public static Home = new Key('Home', '\uE011');
+    public static Insert = new Key('Insert', '\uE016');
+    public static Meta = new Key('Meta', '\uE03D', true);
+    public static Numpad0 = new Key('Numpad0', '\uE01A');
+    public static Numpad1 = new Key('Numpad1', '\uE01B');
+    public static Numpad2 = new Key('Numpad2', '\uE01C');
+    public static Numpad3 = new Key('Numpad3', '\uE01D');
+    public static Numpad4 = new Key('Numpad4', '\uE01E');
+    public static Numpad5 = new Key('Numpad5', '\uE01F');
+    public static Numpad6 = new Key('Numpad6', '\uE020');
+    public static Numpad7 = new Key('Numpad7', '\uE021');
+    public static Numpad8 = new Key('Numpad8', '\uE022');
+    public static Numpad9 = new Key('Numpad9', '\uE023');
+    public static NumpadAdd = new Key('NumpadAdd', '\uE025');
+    public static NumpadDecimal = new Key('NumpadDecimal', '\uE028');
+    public static NumpadDivide = new Key('NumpadDivide', '\uE029');
+    public static NumpadEqual = new Key('NumpadEqual', '\uE019');
+    public static NumpadMultiply = new Key('NumpadMultiply', '\uE024');
+    public static NumpadSubtract = new Key('NumpadSubtract', '\uE027');
+    public static PageDown = new Key('PageDown', '\uE00F');
+    public static PageUp = new Key('PageUp', '\uE00E');
+    public static Pause = new Key('Pause', '\uE00B');
+    public static Semicolon = new Key('Semicolon', '\uE018');
+    public static Shift = new Key('Shift', '\uE008', true);
+    public static Space = new Key('Space', '\uE00D');
+    public static Tab = new Key('Tab', '\uE004');
+
+    public static isKey(maybeKey: unknown): maybeKey is Key {
+        return !! maybeKey
+            && maybeKey instanceof Key;
+    }
+
+    constructor(
+        public readonly devtoolsName: string,
+        public readonly utf16codePoint: string,
+        public readonly isModifier: boolean = false,
+    ) {
+    }
+
+    toString(): string {
+        return this.devtoolsName.replace(/([a-z])([\dA-Z])/g, '$1 $2');
+    }
+}

package/src/input/index.ts

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

package/src/screenplay/abilities/BrowseTheWeb.ts

@@ -0,0 +1,89 @@
+import { Ability, Duration, UsesAbilities } from '@serenity-js/core';
+
+import { Key } from '../../input';
+import { Cookie, CookieData, ModalDialog, Page, PageElement, PageElements } from '../models';
+import { BrowserCapabilities } from './BrowserCapabilities';
+
+export abstract class BrowseTheWeb implements Ability {
+    /**
+     * @desc
+     *  Used to access the Actor's ability to {@link BrowseTheWeb}
+     *  from within the {@link @serenity-js/core/lib/screenplay~Interaction} classes,
+     *  such as {@link Click}.
+     *
+     * @param {@serenity-js/core/lib/screenplay/actor~UsesAbilities} actor
+     * @return {BrowseTheWeb}
+     */
+    static as(actor: UsesAbilities): BrowseTheWeb {
+        return actor.abilityTo(BrowseTheWeb);
+    }
+
+    abstract navigateTo(destination: string): Promise<void>;
+
+    abstract navigateBack(): Promise<void>;
+
+    abstract navigateForward(): Promise<void>;
+
+    abstract reloadPage(): Promise<void>;
+
+    abstract waitFor(duration: Duration): Promise<void>;
+
+    abstract waitUntil(condition: () => boolean | Promise<boolean>, timeout: Duration): Promise<void>;
+
+    abstract findByCss(selector: string): PageElement;
+    abstract findByCssContainingText(selector: string, text: string): PageElement;
+    abstract findById(selector: string): PageElement;
+    abstract findByTagName(selector: string): PageElement;
+    abstract findByXPath(selector: string): PageElement;
+
+    abstract findAllByCss(selector: string): PageElements;
+    abstract findAllByTagName(selector: string): PageElements;
+    abstract findAllByXPath(selector: string): PageElements;
+
+    abstract browserCapabilities(): Promise<BrowserCapabilities>;
+
+    abstract sendKeys(keys: Array<Key | string>): Promise<void>;
+
+    abstract executeScript<Result, InnerArguments extends any[]>(
+        script: string | ((...parameters: InnerArguments) => Result),
+        ...args: InnerArguments
+    ): Promise<Result>;
+
+    abstract executeAsyncScript<Result, Parameters extends any[]>(
+        script: string | ((...args: [ ...parameters: Parameters, callback: (result: Result) => void ]) => void),
+        ...args: Parameters
+    ): Promise<Result>;
+
+    abstract lastScriptExecutionResult<R = any>(): R;
+
+    abstract takeScreenshot(): Promise<string>;
+
+    /**
+     * @desc
+     *  Returns a {@link Page} representing the currently active top-level browsing context.
+     *
+     * @returns {Promise<Page>}
+     */
+    abstract currentPage(): Promise<Page>;
+
+    /**
+     * @desc
+     *  Returns an array of {@link Page} objects representing all the available
+     *  top-level browsing context, e.g. all the open browser tabs.
+     *
+     * @returns {Promise<Array<Page>>}
+     */
+    abstract allPages(): Promise<Array<Page>>;
+
+    abstract cookie(name: string): Promise<Cookie>;
+    abstract setCookie(cookieData: CookieData): Promise<void>;
+    abstract deleteAllCookies(): Promise<void>;
+
+    abstract modalDialog(): Promise<ModalDialog>;
+
+    // todo: remove
+    abstract switchToFrame(targetOrIndex: PageElement | number | string): Promise<void>;
+    abstract switchToParentFrame(): Promise<void>;
+    abstract switchToDefaultContent(): Promise<void>;
+}
+

package/src/screenplay/abilities/BrowserCapabilities.ts

@@ -0,0 +1,5 @@
+export interface BrowserCapabilities {
+    platformName?: string;
+    browserName?: string;
+    browserVersion?: string;
+}

package/src/screenplay/abilities/index.ts

@@ -0,0 +1,2 @@
+export * from './BrowserCapabilities';
+export * from './BrowseTheWeb';

package/src/screenplay/index.ts

@@ -0,0 +1,4 @@
+export * from './abilities';
+export * from './interactions';
+export * from './models';
+export * from './questions';

package/src/screenplay/interactions/Clear.ts

@@ -0,0 +1,102 @@
+import { Answerable, AnswersQuestions, Interaction, LogicError, UsesAbilities } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+import { PageElement } from '../models';
+import { PageElementInteraction } from './PageElementInteraction';
+
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  clear the `value` of a [form `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input).
+ *
+ * @example <caption>Example widget</caption>
+ *  <form>
+ *    <input type="text" name="example" id="example" />
+ *  </form>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Form {
+ *      static exampleInput = Target.the('example input')
+ *          .located(by.id('example'));
+ *  }
+ *
+ * @example <caption>Clearing the value of an input field</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Clear, Enter, Value } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Inés')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Enter.theValue('Hello world!').into(Form.exampleInput),
+ *          Ensure.that(Value.of(Form.exampleInput), equals('Hello world!')),
+ *
+ *          Clear.theValueOf(Form.exampleInput),
+ *          Ensure.that(Value.of(Form.exampleInput), equals('')),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Enter}
+ * @see {@link Value}
+ * @see {@link Target}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+export class Clear extends PageElementInteraction {
+
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} field
+     *  The field to be cleared
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static theValueOf(field: Answerable<PageElement>): Interaction {
+        return new Clear(field);
+    }
+
+    /**
+     * @param {Answerable<PageElement>} field
+     *  The element to be clicked on
+     */
+    constructor(private readonly field: Answerable<PageElement>) {
+        super(formatted `#actor clears the value of ${ field }`);
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @returns {PromiseLike<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
+        const element   = await this.resolve(actor, this.field);
+        const value     = await element.value();
+
+        if (value === null || value === undefined) {
+            throw new LogicError(
+                this.capitaliseFirstLetter(formatted `${ this.field } doesn't seem to have a 'value' attribute that could be cleared.`),
+            );
+        }
+
+        return element.clearValue();
+    }
+
+    private capitaliseFirstLetter(text: string) {
+        return text.charAt(0).toUpperCase() + text.slice(1);
+    }
+}

package/src/screenplay/interactions/Click.ts

@@ -0,0 +1,86 @@
+import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
+import { formatted } from '@serenity-js/core/lib/io';
+
+import { PageElement } from '../models';
+import { PageElementInteraction } from './PageElementInteraction';
+
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  [click](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) on a given Web element.
+ *
+ * @example <caption>Example widget</caption>
+ *  <form>
+ *    <input type="text" name="example" id="example" />
+ *  </form>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Form {
+ *      static exampleInput = Target.the('example input')
+ *          .located(by.id('example'));
+ *  }
+ *
+ * @example <caption>Clicking on an element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Click, isSelected } from '@serenity-js/webdriverio';
+ *  import { Ensure } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Chloé')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Click.on(Form.exampleInput),
+ *          Ensure.that(Form.exampleInput, isSelected()),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link isSelected}
+ *
+ * @extends {ElementInteraction}
+ */
+export class Click extends PageElementInteraction {
+
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} pageElement
+     *  The element to be clicked on
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static on(pageElement: Answerable<PageElement>): Interaction {
+        return new Click(pageElement);
+    }
+
+    /**
+     * @param {Answerable<PageElement>} element
+     *  The element to be clicked on
+     */
+    constructor(private readonly element: Answerable<PageElement>) {
+        super(formatted `#actor clicks on ${ element }`);
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @returns {PromiseLike<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
+        const element = await this.resolve(actor, this.element);
+        await element.scrollIntoView();
+        return element.click();
+    }
+}