@serenity-js/webdriverio 2.32.7 → 3.0.0-rc.10

package/src/screenplay/interactions/Navigate.ts

@@ -1,208 +0,0 @@
-import { Answerable, AnswersQuestions, Interaction, TestCompromisedError, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-
-import { BrowseTheWeb } from '../';
-
-/**
- * @desc
- *  Allows the {@link @serenity-js/core/lib/screenplay/actor~Actor} to navigate
- *  to a specific destination, as well as back and forth in the browser history,
- *  or reload the current page.
- */
-export class Navigate {
-
-    /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  to navigate to a given URL.
-     *
-     *  The URL can be:
-     *  - absolute, i.e. `https://example.org/search`
-     *  - relative, i.e. `/search`
-     *
-     *  If the URL is relative, WebdriverIO will append it to `baseUrl` specified in
-     *  the [configuration file](https://webdriver.io/docs/configurationfile/).
-     *
-     * @example <caption>wdio.conf.ts</caption>
-     *  export const config = {
-     *      baseUrl: 'https://example.org',
-     *      // ...
-     *  }
-     *
-     * @example <caption>Navigate to path relative to baseUrl</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
-     *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('/search'),
-     *      );
-     *
-     * @example <caption>Navigate to an absolute URL (overrides baseUrl)</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
-     *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('https://mycompany.org/login'),
-     *      );
-     *
-     * @param {Answerable<string>} url
-     *  An absolute URL or path an {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  should navigate to
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link BrowseTheWeb}
-     */
-    static to(url: Answerable<string>): Interaction {
-        return new NavigateToUrl(url);
-    }
-
-    /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
-     *  navigate back one page in the joint session history of the current top-level browsing context.
-     *
-     * @example <caption>Navigate to path relative to baseUrl</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { Ensure, endsWith } from '@serenity-js/assertions';
-     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
-     *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('/first'),
-     *          Navigate.to('/second'),
-     *
-     *          Navigate.back(),
-     *
-     *          Ensure.that(Website.url(), endsWith('/first')),
-     *      );
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see https://webdriver.io/docs/api/webdriver/#back
-     * @see {@link BrowseTheWeb}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
-     */
-    static back(): Interaction {
-        return Interaction.where(`#actor navigates back in the browser history`, actor =>
-            BrowseTheWeb.as(actor).browser.back(),
-        );
-    }
-
-    /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
-     *  navigate forward one page in the session history.
-     *
-     * @example <caption>Navigate to path relative to baseUrl</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { Ensure, endsWith } from '@serenity-js/assertions';
-     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
-     *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('/first'),
-     *          Navigate.to('/second'),
-     *
-     *          Navigate.back(),
-     *          Navigate.forward(),
-     *
-     *          Ensure.that(Website.url(), endsWith('/second')),
-     *      );
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link BrowseTheWeb}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
-     * @see https://webdriver.io/docs/api/webdriver/#forward
-     */
-    static forward(): Interaction {
-        return Interaction.where(`#actor navigates forward in the browser history`, actor =>
-            BrowseTheWeb.as(actor).browser.forward(),
-        );
-    }
-
-    /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
-     *  reload the current page.
-     *
-     * @example <caption>Navigate to path relative to baseUrl</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { Ensure, endsWith } from '@serenity-js/assertions';
-     *  import { Navigate, BrowseTheWeb, DeleteCookies } from '@serenity-js/webdriverio';
-     *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('/login'),
-     *          DeleteCookies.called('session_id'),
-     *          Navigate.reloadPage(),
-     *      );
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link BrowseTheWeb}
-     * @see {@link DeleteCookies}
-     * @see {@link @serenity-js/assertions~Ensure}
-     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
-     */
-    static reloadPage(): Interaction {
-        return Interaction.where(`#actor reloads the page`, actor =>
-            BrowseTheWeb.as(actor).browser.refresh(),
-        );
-    }
-}
-
-/**
- * @package
- */
-class NavigateToUrl extends Interaction {
-    constructor(private readonly url: Answerable<string>) {
-        super();
-    }
-
-    /**
-     * @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}
-     */
-    performAs(actor: UsesAbilities & AnswersQuestions): PromiseLike<void> {
-        return actor.answer(this.url)
-            .then(url =>
-                BrowseTheWeb.as(actor)
-                    .get(url)
-                    .catch(error => {
-                        throw new TestCompromisedError(`Couldn't navigate to ${ url }`, error);
-                    })
-            )
-    }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return formatted `#actor navigates to ${ this.url }`;
-    }
-}

package/src/screenplay/interactions/Press.ts

@@ -1,172 +0,0 @@
-import { Activity, Answerable, AnswersQuestions, Interaction, Question, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { Element } from 'webdriverio';
-
-import { Key } from '../../input';
-import { BrowseTheWeb } from '../abilities';
-import { PressBuilder } from './PressBuilder';
-import { WebElementInteraction } from './WebElementInteraction';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  send a key press or a sequence of keys to a Web element.
- *
- *  *Please note*: On macOS, some keyboard shortcuts might not work with the [`devtools` protocol](https://webdriver.io/docs/automationProtocols/#devtools-protocol).
- *
- *  For example:
- *  - to *copy*, instead of `Meta+C`, use `Control+Insert`
- *  - to *cut*, instead of `Meta+X`, use `Control+Delete`
- *  - to *paste*, instead of `Meta+V`, use `Shift+Insert`
- *
- * @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>Pressing keys</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Key, Press, Value } from '@serenity-js/webdriverio';
- *  import { Ensure, equals } from '@serenity-js/assertions';
- *
- *  actorCalled('Priyanka')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Press.the('H', 'i', '!', Key.ENTER).in(Form.exampleInput),
- *          Ensure.that(Value.of(Form.exampleInput), equals('Hi!')),
- *      );
- *
- * @see {@link Key}
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link @serenity-js/assertions/lib/expectations~equals}
- *
- * @extends {WebElementInteraction}
- */
-export class Press extends WebElementInteraction {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {...keys: Array<Answerable<Key | string | Key[] | string[]>>} keys
-     *  A sequence of one or more keys to press
-     *
-     * @returns {PressBuilder}
-     */
-    static  the(...keys: Array<Answerable<Key | string | Key[] | string[]>>): Activity & PressBuilder {
-        return new Press(KeySequence.of(keys));
-    }
-
-    in(field: Answerable<Element<'async'>> /* | Question<AlertPromise> | AlertPromise */): Interaction {
-        return new PressKeyInField(this.keys, field)
-    }
-
-    /**
-     * @param {Answerable<Array<Key | string>>} keys
-     *  A sequence of one or more keys to press
-     */
-    constructor(
-        private readonly keys: Answerable<Array<Key | string>>
-    ) {
-        super(formatted `#actor presses ${ keys }`);
-    }
-
-    /**
-     * @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 keys  = await actor.answer(this.keys);
-
-        return BrowseTheWeb.as(actor).sendKeys(keys);
-    }
-}
-
-class PressKeyInField extends WebElementInteraction {
-    /**
-     * @param {Answerable<Array<Key | string>>} keys
-     *  A sequence of one or more keys to press
-     *
-     * @param {Answerable<Element<'async'>>} field
-     *  Web element to send the keys to
-     */
-    constructor(
-        private readonly keys: Answerable<Array<Key | string>>,
-        private readonly field: Answerable<Element<'async'>> /* todo | Question<AlertPromise> | AlertPromise */,
-    ) {
-        super(formatted `#actor presses ${ keys } in ${ field }`);
-    }
-
-    async performAs(actor: UsesAbilities & AnswersQuestions): Promise<void> {
-        const field = await this.resolve(actor, this.field);
-        const keys  = await actor.answer(this.keys);
-
-        await BrowseTheWeb.as(actor).browser.execute(
-            /* istanbul ignore next */
-            function focus(element: any) {  // todo: fix type
-                element.focus();
-            },
-            field,
-        );
-
-        return BrowseTheWeb.as(actor).sendKeys(keys);
-    }
-}
-
-/**
- * @package
- */
-class KeySequence extends Question<Promise<Array<Key | string>>> {
-    static of(keys: Array<Answerable<Key | string | Key[] | string[]>>) {
-        return new KeySequence(keys);
-    }
-
-    constructor(private readonly keys: Array<Answerable<Key | string | Key[] | string[]>>) {
-        super(KeySequence.describe(keys));
-    }
-
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Array<string | Key>> {
-        return Promise.all(
-            this.keys.map(part => actor.answer(part))
-        ).then(keys => keys.flat().filter(key => !! key))
-    }
-
-    private static describe(keys: Array<Answerable<Key | string | Key[] | string[]>>): string {
-        const prefix = keys.length === 1 ? 'key' : 'keys';
-
-        const description = keys.reduce((acc, key, index) => {
-            const separator = Key.isKey(key) && key.isModifier
-                ? '-'
-                : acc.separator;
-
-            return {
-                description: index === 0
-                    ? `${ key }`
-                    : `${ acc.description }${acc.separator}${ key }`,
-                separator,
-            }
-        }, { description: '', separator: ', ' }).description;
-
-        return `${ prefix } ${ description }`;
-    }
-}

package/src/screenplay/interactions/PressBuilder.ts

@@ -1,28 +0,0 @@
-import { Answerable } from '@serenity-js/core';
-import { Interaction } from '@serenity-js/core/lib/screenplay';
-import { Element } from 'webdriverio';
-
-/**
- * @desc
- *  Fluent interface to make the instantiation of
- *  the {@link @serenity-js/core/lib/screenplay~Interaction}
- *  to {@link Press} more readable.
- *
- * @see {@link Press}
- *
- * @interface
- */
-export interface PressBuilder {
-
-    /**
-     * @desc
-     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  to {@link Press}.
-     *
-     * @param {Question<ElementFinder> | ElementFinder | Question<AlertPromise> | AlertPromise} field
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @see {@link Target}
-     */
-    in: (field: Answerable<Element<'async'>> /* | Question<AlertPromise> | AlertPromise */) => Interaction;
-}

package/src/screenplay/interactions/RightClick.ts

@@ -1,100 +0,0 @@
-import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { Element } from 'webdriverio';
-
-import { WebElementInteraction } from './WebElementInteraction';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  perfom a right click on a given Web element.
- *
- *  This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
- *  on a given Web element, since it's not possible to interact with the standard context menu offered by your browser
- *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" id="field"
- *      oncontextmenu="showMenu(); return false;" />
- *
- *    <div id="context-menu" style="display:none">
- *      Custom context menu
- *    </div>
- *  </form>
- *
- *  <script>
- *    function showMenu() {
- *      document.getElementById("context-menu").style.display = 'block';
- *    }
- *  </script>
- *
- * @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'));
- *      static exampleContextMenu = Target.the('example context menu')
- *          .located(by.id('context-menu'));
- *  }
- *
- * @example <caption>Right-click on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, RightClick, isVisible } from '@serenity-js/webdriverio';
- *  import { Ensure } from '@serenity-js/assertions';
- *
- *  actorCalled('Chloé')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          RightClick.on(Form.exampleInput),
- *          Ensure.that(Form.exampleContextMenu, isVisible()),
- *      );
- *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link isVisible}
- *
- * @extends {WebElementInteraction}
- */
-export class RightClick extends WebElementInteraction {
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Answerable<Element<'async'>>} target
-     *  The element to be right-clicked on
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static on(target: Answerable<Element<'async'>>): Interaction {
-        return new RightClick(target);
-    }
-
-    /**
-     * @param {Answerable<Element<'async'>>} target
-     *  The element to be right-clicked on
-     */
-    constructor(private readonly target: Answerable<Element<'async'>>) {
-        super(formatted `#actor right-clicks on ${ target }`);
-    }
-
-    /**
-     * @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.target);
-        return element.click({ button: 'right' });
-    }
-}

package/src/screenplay/interactions/Scroll.ts

@@ -1,87 +0,0 @@
-import { Answerable, AnswersQuestions, Interaction,  UsesAbilities } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
-import { Element } from 'webdriverio';
-
-import { WebElementInteraction } from './WebElementInteraction';
-
-/**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  scroll until a given Web element comes into view.
- *
- * @example <caption>Example widget</caption>
- *  <!--
- *      an element somewhere at the bottom of the page,
- *      outside of the visible area
- *  -->
- *  <input type="submit" id="submit" />
- *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
- *
- *  class Form {
- *      static submitButton = Target.the('submit button')
- *          .located(by.id('submit'));
- *  }
- *
- * @example <caption>Scrolling to element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { Ensure } from '@serenity-js/assertions';
- *  import { BrowseTheWeb, Scroll, isVisible } from '@serenity-js/webdriverio';
- *
- *  actorCalled('Sara')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Scroll.to(Form.submitButton),
- *          Ensure.that(Form.submitButton, isVisible()),
- *      );
- *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link isVisible}
- * @see {@link @serenity-js/assertions~Ensure}
- *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
- */
-export class Scroll extends WebElementInteraction {
-
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Answerable<Element<'async'>>} target
-     *  The element to be scrolled to
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static to(target: Answerable<Element<'async'>>) : Interaction {
-        return new Scroll(target);
-    }
-
-    /**
-     * @param {Answerable<Element<'async'>>} target
-     *  The element to be scrolled to
-     */
-    constructor(private readonly target: Answerable<Element<'async'>>) {
-        super(formatted `#actor scrolls to ${ target }`);
-    }
-
-    /**
-     * @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.target);
-        return element.scrollIntoView();
-    }
-}