@serenity-js/webdriverio-8 3.31.0

package/src/screenplay/models/WebdriverIOPage.ts

@@ -0,0 +1,311 @@
+import 'webdriverio';
+
+import { List, LogicError } from '@serenity-js/core';
+import type { CorrelationId } from '@serenity-js/core/lib/model/index.js';
+import type { Cookie, CookieData, ModalDialogHandler, PageElements, Selector } from '@serenity-js/web';
+import { ArgumentDehydrator, BrowserWindowClosedError, ByCss, Key, Page, PageElement, PageElementsLocator } from '@serenity-js/web';
+import * as scripts from '@serenity-js/web/lib/scripts/index.js';
+import { URL } from 'url';
+
+import { WebdriverIOExistingElementLocator, WebdriverIOLocator, WebdriverIORootLocator } from './locators/index.js';
+import type { WebdriverIOBrowsingSession } from './WebdriverIOBrowsingSession.js';
+import { WebdriverIOCookie } from './WebdriverIOCookie.js';
+import type { WebdriverIOErrorHandler } from './WebdriverIOErrorHandler.js';
+import { WebdriverIOPageElement } from './WebdriverIOPageElement.js';
+
+/**
+ * WebdriverIO-specific implementation of [`Page`](https://serenity-js.org/api/web/class/Page/).
+ *
+ * @group Models
+ */
+export class WebdriverIOPage extends Page<WebdriverIO.Element> {
+
+    private lastScriptExecutionSummary: LastScriptExecutionSummary;
+
+    /* eslint-disable unicorn/consistent-function-scoping */
+    private dehydrator: ArgumentDehydrator<PageElement<WebdriverIO.Element>, WebdriverIO.Element> = new ArgumentDehydrator(
+        (item: any): item is PageElement<WebdriverIO.Element> => item instanceof PageElement,
+        (item: PageElement<WebdriverIO.Element>) => item.nativeElement(),
+    );
+    /* eslint-enable */
+
+    constructor(
+        session: WebdriverIOBrowsingSession,
+        private readonly browser: WebdriverIO.Browser,
+        modalDialogHandler: ModalDialogHandler,
+        private readonly errorHandler: WebdriverIOErrorHandler,
+        pageId: CorrelationId,
+    ) {
+        super(
+            session,
+            new WebdriverIORootLocator(browser),
+            modalDialogHandler,
+            pageId,
+        );
+    }
+
+    createPageElement(nativeElement: WebdriverIO.Element): PageElement<WebdriverIO.Element> {
+        return new WebdriverIOPageElement(
+            new WebdriverIOExistingElementLocator(
+                this.rootLocator,
+                new ByCss(String(nativeElement.selector)),
+                this.errorHandler,
+                nativeElement
+            )
+        );
+    }
+
+    locate(selector: Selector): PageElement<WebdriverIO.Element> {
+        return new WebdriverIOPageElement(
+            new WebdriverIOLocator(this.rootLocator, selector, this.errorHandler)
+        )
+    }
+
+    locateAll(selector: Selector): PageElements<WebdriverIO.Element> {
+        return List.of(
+            new PageElementsLocator(
+                new WebdriverIOLocator(this.rootLocator, selector, this.errorHandler)
+            )
+        );
+    }
+
+    async navigateTo(destination: string): Promise<void> {
+        await this.inContextOfThisPage(() => this.browser.url(destination));
+    }
+
+    async navigateBack(): Promise<void> {
+        await this.inContextOfThisPage(() => this.browser.back());
+    }
+
+    async navigateForward(): Promise<void> {
+        await this.inContextOfThisPage(() => this.browser.forward());
+    }
+
+    async reload(): Promise<void> {
+        await this.inContextOfThisPage(() => this.browser.refresh());
+    }
+
+    async sendKeys(keys: Array<Key | string>): Promise<void> {
+        const keySequence = keys.map(key => {
+            if (! Key.isKey(key)) {
+                return key;
+            }
+
+            return key.utf16codePoint;
+        });
+
+        await this.inContextOfThisPage(() => this.browser.keys(keySequence));
+    }
+
+    async executeScript<Result, InnerArguments extends any[]>(
+        script: string | ((...parameters: InnerArguments) => Result),
+        ...args: InnerArguments
+    ): Promise<Result> {
+
+        const serialisedScript = typeof script === 'function'
+            ? String(script)
+            : String(`function script() { ${ script } }`);
+
+        const executableScript = new Function(`
+            var parameters = (${ scripts.rehydrate }).apply(null, arguments);
+            return (${ serialisedScript }).apply(null, parameters);
+        `);
+
+        const result = await this.inContextOfThisPage<Result>(async () => {
+
+            const dehydratedArguments = await this.dehydrator.dehydrate(args);
+
+            return await this.browser.execute(executableScript as any, ...dehydratedArguments);
+        });
+
+        this.lastScriptExecutionSummary = new LastScriptExecutionSummary(result);
+
+        return result;
+    }
+
+    async executeAsyncScript<Result, Parameters extends any[]>(
+        script: string | ((...args: [...parameters: Parameters, callback: (result: Result) => void]) => void),
+        ...args: Parameters
+    ): Promise<Result> {
+
+        const serialisedScript = typeof script === 'function'
+            ? String(script)
+            : String(`function script() { ${ script } }`);
+
+        const executableScript = new Function(`
+            var args = Array.prototype.slice.call(arguments, 0, -1);
+            var callback = arguments[arguments.length - 1];
+            var parameters = (${ scripts.rehydrate }).apply(null, args);
+            (${ serialisedScript }).apply(null, parameters.concat(callback));
+        `);
+
+        const result = await this.inContextOfThisPage<Result>(async () => {
+
+            const dehydratedArguments = await this.dehydrator.dehydrate(args);
+
+            return this.browser.executeAsync<Result, [ { argsCount: number, refsCount: number }, ...any[] ]>(
+                executableScript as (...args: [ { argsCount: number, refsCount: number }, ...any[], callback: (result: Result) => void ]) => void,
+                ...dehydratedArguments as [ { argsCount: number, refsCount: number }, ...any[] ],
+            );
+        });
+
+        this.lastScriptExecutionSummary = new LastScriptExecutionSummary(result);
+
+        return result;
+    }
+
+    lastScriptExecutionResult<Result = any>(): Result {
+        if (! this.lastScriptExecutionSummary) {
+            throw new LogicError(`Make sure to execute a script before checking on the result`);
+        }
+
+        // Selenium returns `null` when the script it executed returns `undefined`
+        // so we're mapping the result back.
+        return this.lastScriptExecutionSummary.result === null
+            ? undefined
+            : this.lastScriptExecutionSummary.result;
+    }
+
+    async takeScreenshot(): Promise<string> {
+        return await this.inContextOfThisPage(async () => {
+            try {
+                return await this.browser.takeScreenshot();
+            }
+            catch (error) {
+
+                if (error.name === 'ProtocolError' && error.message.includes('Target closed')) {
+                    throw new BrowserWindowClosedError(
+                        `Couldn't take screenshot since the browser window is already closed`,
+                        error
+                    );
+                }
+
+                throw error;
+            }
+        });
+    }
+
+    async cookie(name: string): Promise<Cookie> {
+        return new WebdriverIOCookie(this.browser, name);
+    }
+
+    async setCookie(cookieData: CookieData): Promise<void> {
+        return await this.inContextOfThisPage(() => {
+            return this.browser.setCookies({
+                name:       cookieData.name,
+                value:      cookieData.value,
+                path:       cookieData.path,
+                domain:     cookieData.domain,
+                secure:     cookieData.secure,
+                httpOnly:   cookieData.httpOnly,
+                expiry:     cookieData.expiry
+                    ? cookieData.expiry.toSeconds()
+                    : undefined,
+                sameSite:   cookieData.sameSite,
+            });
+        });
+    }
+
+    async deleteAllCookies(): Promise<void> {
+        return await this.inContextOfThisPage(() => {
+            return this.browser.deleteCookies() as Promise<void>;
+        });
+    }
+
+    async title(): Promise<string> {
+        return await this.inContextOfThisPage(() => this.browser.execute(`return document.title`));
+    }
+
+    async name(): Promise<string> {
+        return await this.inContextOfThisPage(() => this.browser.execute(`return window.name`));
+    }
+
+    async url(): Promise<URL> {
+        return await this.inContextOfThisPage(async () => {
+            return new URL(await this.browser.execute(`return window.location.href`));
+        });
+    }
+
+    async viewportSize(): Promise<{ width: number, height: number }> {
+        return await this.inContextOfThisPage(async () => {
+            if (! this.browser.isDevTools) {
+                const calculatedViewportSize = await this.browser.execute(`
+                    return {
+                        width:  Math.max(document.documentElement.clientWidth,  window.innerWidth || 0),
+                        height: Math.max(document.documentElement.clientHeight, window.innerHeight || 0),
+                    }
+                `) as { width: number, height: number };
+
+                // Chrome headless hard-codes window.innerWidth and window.innerHeight to 0
+                if (calculatedViewportSize.width > 0 && calculatedViewportSize.height > 0) {
+                    return calculatedViewportSize;
+                }
+            }
+
+            return this.browser.getWindowSize();
+        });
+    }
+
+    async setViewportSize(size: { width: number, height: number }): Promise<void> {
+        return await this.inContextOfThisPage(async () => {
+            let desiredWindowSize = size;
+
+            if (! this.browser.isDevTools) {
+                desiredWindowSize = await this.browser.execute(`
+                    var currentViewportWidth  = Math.max(document.documentElement.clientWidth, window.innerWidth || 0)
+                    var currentViewportHeight = Math.max(document.documentElement.clientHeight, window.innerHeight || 0)
+                    
+                    return {
+                        width:  Math.max(window.outerWidth  - currentViewportWidth  + ${ size.width },  ${ size.width }),
+                        height: Math.max(window.outerHeight - currentViewportHeight + ${ size.height }, ${ size.height }),
+                    };
+                `);
+            }
+
+            return this.browser.setWindowSize(desiredWindowSize.width, desiredWindowSize.height);
+        });
+    }
+
+    async close(): Promise<void> {
+        await this.inContextOfThisPage(() => this.browser.closeWindow());
+    }
+
+    async closeOthers(): Promise<void> {
+        await this.session.closePagesOtherThan(this);
+    }
+
+    async isPresent(): Promise<boolean> {
+        const allPages = await this.session.allPages();
+        for (const page of allPages) {
+            if (page === this) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private async inContextOfThisPage<T>(action: () => Promise<T> | T): Promise<T> {
+        let originalCurrentPage;
+
+        try {
+            originalCurrentPage = await this.session.currentPage();
+
+            await this.session.changeCurrentPageTo(this);
+
+            return await action();
+        }
+        catch (error) {
+            return await this.errorHandler.executeIfHandled(error, action);
+        }
+        finally {
+            await this.session.changeCurrentPageTo(originalCurrentPage);
+        }
+    }
+}
+
+/**
+ * @package
+ */
+class LastScriptExecutionSummary<Result = any> {
+    constructor(public readonly result: Result) {}
+}

package/src/screenplay/models/WebdriverIOPageElement.ts

@@ -0,0 +1,280 @@
+import 'webdriverio';
+
+import { LogicError } from '@serenity-js/core';
+import type { SwitchableOrigin } from '@serenity-js/web';
+import { Key, PageElement, SelectOption } from '@serenity-js/web';
+import * as scripts from '@serenity-js/web/lib/scripts/index.js';
+
+import type { WebdriverIOLocator } from './locators/index.js';
+import { WebdriverProtocolErrorCode } from './WebdriverProtocolErrorCode.js';
+
+/**
+ * WebdriverIO-specific implementation of [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * @group Models
+ */
+export class WebdriverIOPageElement extends PageElement<WebdriverIO.Element> {
+    of(parent: WebdriverIOPageElement): WebdriverIOPageElement {
+        return new WebdriverIOPageElement(this.locator.of(parent.locator))
+    }
+
+    closestTo(child: WebdriverIOPageElement): WebdriverIOPageElement {
+        return new WebdriverIOPageElement(this.locator.closestTo(child.locator))
+    }
+
+    async clearValue(): Promise<void> {
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        function times(length: number, key: string) {
+            return Array.from({ length }).map(() => key);
+        }
+
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        async function removeCharactersFrom(browser: WebdriverIO.Browser, inputElement: WebdriverIO.Element, numberOfCharacters: number): Promise<void> {
+            await browser.execute(
+                /* c8 ignore next */
+                function focusOn(element: any) {
+                    element.focus();
+                },
+                element
+            );
+            await browser.keys([
+                Key.Home.utf16codePoint,
+                ...times(numberOfCharacters, Key.Delete.utf16codePoint),
+            ]);
+        }
+
+        const element   = await this.nativeElement();
+        const value     = await this.value();
+        const hasValue  = value !== null && value !== undefined && value.length > 0;
+        const browser   = await this.browserFor(element);
+
+        if (hasValue) {
+            return await removeCharactersFrom(browser, element, value.length);
+        }
+
+        const contentEditable = await element.getAttribute('contenteditable');
+        const hasContentEditable = contentEditable !== null && contentEditable !== undefined && contentEditable !== 'false';
+
+        if (hasContentEditable) {
+            const text = await element.getText();
+            return await removeCharactersFrom(browser, element, text.length);
+        }
+    }
+
+    async click(): Promise<void> {
+        const element = await this.nativeElement();
+        await element.click();
+    }
+
+    async doubleClick(): Promise<void> {
+        const element = await this.nativeElement();
+        await element.doubleClick();
+    }
+
+    async enterValue(value: string | number | Array<string | number>): Promise<void> {
+        const text      = Array.isArray(value) ? value.join('') : value;
+        const element   = await this.nativeElement();
+
+        await element.addValue(text);
+    }
+
+    async scrollIntoView(): Promise<void> {
+        const element = await this.nativeElement();
+        await element.scrollIntoView();
+    }
+
+    async hoverOver(): Promise<void> {
+        const element = await this.nativeElement();
+        await element.moveTo();
+    }
+
+    async rightClick(): Promise<void> {
+        const element = await this.nativeElement();
+        await element.click({ button: 'right' });
+    }
+
+    async selectOptions(...options: SelectOption[]): Promise<void> {
+        const element = await this.nativeElement();
+
+        for (const option of options) {
+            if (option.value) {
+                await element.selectByAttribute('value', option.value);
+            }
+            else if (option.label) {
+                await element.selectByVisibleText(option.label);
+            }
+        }
+    }
+
+    async selectedOptions(): Promise<SelectOption[]> {
+        const element = await this.nativeElement();
+        const browser = await this.browserFor(element);
+
+        const options = await browser.execute(
+            /* c8 ignore start */
+            (select: HTMLSelectElement) => {
+                const options = [];
+                select.querySelectorAll('option').forEach((option: HTMLOptionElement) => {
+                    options.push({
+                        selected:   option.selected,
+                        disabled:   option.disabled,
+                        label:      option.label,
+                        value:      option.value,
+                    });
+                });
+
+                return options;
+            },
+            element as unknown
+            /* c8 ignore stop */
+        );
+
+        return options.map(option =>
+            new SelectOption(option.label, option.value, option.selected, option.disabled)
+        );
+    }
+
+    async attribute(name: string): Promise<string> {
+        const element = await this.nativeElement();
+        return await element.getAttribute(name);
+    }
+
+    async text(): Promise<string> {
+        const element = await this.nativeElement();
+        return await element.getText();
+    }
+
+    async value(): Promise<string> {
+        const element = await this.nativeElement();
+        return await element.getValue();
+    }
+
+    async html(): Promise<string> {
+        const element = await this.nativeElement();
+        return await element.getHTML(true);
+    }
+
+    async switchTo(): Promise<SwitchableOrigin> {
+        try {
+            const element: WebdriverIO.Element = await this.locator.nativeElement()
+
+            if (element.error) {
+                throw element.error;
+            }
+
+            const tagName = await element.getTagName();
+
+            const browser = await this.browserFor(element);
+
+            if ([ 'iframe', 'frame' ].includes(tagName)) {
+                const locator = (this.locator as WebdriverIOLocator);
+
+                await locator.switchToFrame(element);
+
+                return {
+                    switchBack: async (): Promise<void> => {
+                        try {
+                            await locator.switchToParentFrame();
+                        }
+                        catch {
+                            // switchToParentFrame doesn't work on iOS devices, so we need a workaround
+                            // https://github.com/appium/appium/issues/14882#issuecomment-1693326102
+                            await locator.switchToFrame(null);  // eslint-disable-line unicorn/no-null
+                        }
+                    }
+                }
+            }
+            else {
+                // focus on element
+                const previouslyFocusedElement = await browser.execute(
+                    /* c8 ignore next */
+                    function focusOn(element: any) {
+                        const currentlyFocusedElement = document.activeElement;
+                        element.focus();
+                        return currentlyFocusedElement;
+                    },
+                    element
+                );
+
+                return {
+                    switchBack: async (): Promise<void> => {
+                        await browser.execute(
+                            /* c8 ignore next */
+                            function focusOn(element: any) {
+                                element.focus();
+                            },
+                            previouslyFocusedElement
+                        );
+                    }
+                }
+            }
+        }
+        catch(error) {
+            throw new LogicError(`Couldn't switch to page element located ${ this.locator }`, error);
+        }
+    }
+
+    async isActive(): Promise<boolean> {
+        const element = await this.nativeElement();
+        return await element.isFocused();
+    }
+
+    async isClickable(): Promise<boolean> {
+        const element = await this.nativeElement();
+        return await element.isClickable();
+    }
+
+    async isEnabled(): Promise<boolean> {
+        const element = await this.nativeElement();
+        return await element.isEnabled();
+    }
+
+    async isPresent(): Promise<boolean> {
+        const element = await this.nativeElement();
+        return await element.isExisting();
+    }
+
+    async isSelected(): Promise<boolean> {
+        const element = await this.nativeElement();
+        return await element.isSelected();
+    }
+
+    async isVisible(): Promise<boolean> {
+        try {
+            const element = await this.nativeElement();
+
+            if (! await element.isDisplayed()) {
+                return false;
+            }
+
+            if (! await element.isDisplayedInViewport()) {
+                return false;
+            }
+
+            const browser = await this.browserFor(element);
+
+            return await browser.execute(scripts.isVisible, element as unknown as HTMLElement);
+        }
+        catch (error) {
+            // an element that doesn't exist is treated as not visible
+            if (
+                error.name === WebdriverProtocolErrorCode.NoSuchElementError ||
+                error.error === WebdriverProtocolErrorCode.NoSuchElementError ||
+                /element.*not found/i.test(error.message)
+            ) {
+                return false;
+            }
+
+            throw error;
+        }
+    }
+
+    // based on https://github.com/webdriverio/webdriverio/blob/dec6da76b0e218af935dbf39735ae3491d5edd8c/packages/webdriverio/src/utils/index.ts#L98
+
+    private async browserFor(nativeElement: WebdriverIO.Element | WebdriverIO.Browser): Promise<WebdriverIO.Browser> {
+        const element = nativeElement as WebdriverIO.Element;
+        return element.parent
+            ? this.browserFor(element.parent)
+            : nativeElement as WebdriverIO.Browser
+    }
+}

package/src/screenplay/models/WebdriverIOPuppeteerModalDialogHandler.ts

@@ -0,0 +1,100 @@
+import type {
+    ModalDialog} from '@serenity-js/web';
+import {
+    AbsentModalDialog,
+    AcceptedModalDialog,
+    DismissedModalDialog,
+    ModalDialogHandler
+} from '@serenity-js/web';
+import type { Dialog, Page } from 'puppeteer-core';
+
+/**
+ * WebdriverIO-specific implementation of [`ModalDialogHandler`](https://serenity-js.org/api/web/class/ModalDialogHandler/), applicable when WebdriverIO
+ * uses [Puppeteer](https://developer.chrome.com/docs/puppeteer/).
+ *
+ * Automatically handles any simple JavaScript modal dialog windows, such as
+ * those opened by [`window.alert()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert),
+ * [`window.confirm()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm),
+ * or [`window.prompt()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt).
+ *
+ * This helps to avoid Puppeteer hanging when there's an interaction pending
+ * and a dialog is already open, see https://github.com/puppeteer/puppeteer/issues/2481
+ */
+export class WebdriverIOPuppeteerModalDialogHandler extends ModalDialogHandler {
+
+    private dialogHandlingInProgress = false;
+
+    private readonly defaultHandler: (dialog: Dialog) => Promise<ModalDialog> =
+        async (dialog: Dialog) => {
+            await dialog.dismiss();
+            return new DismissedModalDialog(dialog.message());
+        }
+
+    private currentHandler: (dialog: Dialog) => Promise<ModalDialog>;
+
+    constructor(private readonly page: Page) {
+        super();
+
+        this.currentHandler = this.defaultHandler;
+
+        // remove the default WebdriverIO handler because it makes any other listeners hang
+        // https://github.com/webdriverio/webdriverio/blob/518c56a61353b2f65436b83c618117021da7e622/packages/devtools/src/devtoolsdriver.ts#L69
+        this.page.removeAllListeners('dialog');
+
+        // register Serenity/JS handler instead
+        this.page.on('dialog', async (dialog: Dialog) => {
+            // Puppeteer doesn't seem to synchronise async handlers correctly,
+            // hence the handleModalDialog wrapper and the `dialogHandlingInProgress` lock.
+            await this.handleModalDialog(() => this.currentHandler(dialog));
+        });
+    }
+
+    async acceptNext(): Promise<void> {
+        this.currentHandler = async (dialog: Dialog) => {
+            await dialog.accept(dialog.defaultValue());
+            return new AcceptedModalDialog(dialog.message());
+        }
+    }
+
+    async acceptNextWithValue(text: string | number): Promise<void> {
+        this.currentHandler = async (dialog: Dialog) => {
+            await dialog.accept(String(text));
+            return new AcceptedModalDialog(dialog.message());
+        }
+    }
+
+    async dismissNext(): Promise<void> {
+        this.currentHandler = async (dialog: Dialog) => {
+            await dialog.dismiss();
+            return new DismissedModalDialog(dialog.message());
+        }
+    }
+
+    async reset(): Promise<void> {
+        this.modalDialog = new AbsentModalDialog();
+        this.currentHandler = this.defaultHandler;
+    }
+
+    async discard(): Promise<void> {
+        this.page.off('dialog', this.currentHandler);
+    }
+
+    async last(): Promise<ModalDialog> {
+        return new Promise((resolve, reject) => {
+            const interval = setInterval(() => {
+                if (!this.dialogHandlingInProgress) {
+                    clearInterval(interval);
+                    resolve(this.modalDialog);
+                }
+            }, 25);
+        });
+    }
+
+    private async handleModalDialog(handler: () => Promise<ModalDialog> | ModalDialog): Promise<void> {
+        this.dialogHandlingInProgress = true;
+
+        this.modalDialog = await handler();
+
+        this.dialogHandlingInProgress = false;
+    }
+}