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

package/src/screenplay/models/WebdriverIOBrowsingSession.ts

@@ -0,0 +1,171 @@
+import { LogicError } from '@serenity-js/core';
+import { CorrelationId } from '@serenity-js/core/lib/model';
+import { BrowsingSession, ModalDialogHandler } from '@serenity-js/web';
+import type { Page } from 'puppeteer-core/lib/cjs/puppeteer/api/Page';
+import * as wdio from 'webdriverio';
+
+import { WebdriverIOPage } from '../models';
+import { WebdriverIOErrorHandler } from './WebdriverIOErrorHandler';
+import { WebdriverIOModalDialogHandler } from './WebdriverIOModalDialogHandler';
+import { WebdriverIOPuppeteerModalDialogHandler } from './WebdriverIOPuppeteerModalDialogHandler';
+
+/**
+ * WebdriverIO-specific implementation of {@apilink BrowsingSession}.
+ *
+ * @group Models
+ */
+export class WebdriverIOBrowsingSession extends BrowsingSession<WebdriverIOPage> {
+
+    constructor(protected readonly browser: wdio.Browser<'async'>) {
+        super();
+
+        if (! browser.$ || ! browser.$$) {
+            throw new LogicError(`WebdriverIO browser object is not initialised yet, so can't be assigned to an actor. Are you trying to instantiate an actor outside of a test or a test hook?`)
+        }
+    }
+
+    async allPages(): Promise<Array<WebdriverIOPage>> {
+        // scan all the active window handles and add any newly opened windows if needed
+        const windowHandles: string[] = await this.browser.getWindowHandles();
+
+        // remove pages that are no longer open
+        const closedPageIds = this.registeredPageIds()
+            .filter(id => ! windowHandles.includes(id.value));
+
+        this.deregister(...closedPageIds);
+
+        // add any new pages that might have been opened (e.g. popup windows)
+        const registeredWindowHandles   = new Set(this.registeredPageIds().map(id => id.value));
+        const newlyOpenedWindowHandles  = windowHandles.filter(windowHandle => ! registeredWindowHandles.has(windowHandle));
+
+        for (const newlyOpenedWindowHandle of newlyOpenedWindowHandles) {
+            const errorHandler = new WebdriverIOErrorHandler();
+            this.register(
+                new WebdriverIOPage(
+                    this,
+                    this.browser,
+                    await this.modalDialogHandlerFor(newlyOpenedWindowHandle, errorHandler),
+                    errorHandler,
+                    new CorrelationId(newlyOpenedWindowHandle)
+                )
+            );
+        }
+
+        return super.allPages();
+    }
+
+    /**
+     * @override
+     * @param page
+     */
+    async changeCurrentPageTo(page: WebdriverIOPage): Promise<void> {
+        const currentPage = await this.currentPage();
+
+        // are we already on this page?
+        if (currentPage.id.equals(page.id)) {
+            return void 0;
+        }
+
+        // does the new page exist, or has it been closed in the meantime by user action, script, or similar?
+        if (! await page.isPresent()) {
+            return void 0;
+        }
+
+        // the page seems to be legit, switch to it
+        await this.browser.switchToWindow(page.id.value);
+
+        // and update the cached reference
+        await super.changeCurrentPageTo(page);
+    }
+
+    private async activeWindowHandle(): Promise<string> {
+        try {
+            return await this.browser.getWindowHandle();
+        }
+        catch (error) {
+            // If the window is closed by user action Webdriver will still hold the reference to the closed window.
+            if (['NoSuchWindowError', 'no such window'].includes(error.name)) {
+                const allHandles = await this.browser.getWindowHandles();
+                if (allHandles.length > 0) {
+                    const handle = allHandles[allHandles.length - 1];
+                    await this.browser.switchToWindow(handle);
+
+                    return handle;
+                }
+            }
+            throw error;
+        }
+    }
+
+    override async currentPage(): Promise<WebdriverIOPage> {
+        const actualCurrentPageHandle   = await this.activeWindowHandle();
+        const actualCurrentPageId       = CorrelationId.fromJSON(actualCurrentPageHandle);
+
+        if (this.currentBrowserPage && this.currentBrowserPage.id.equals(actualCurrentPageId)) {
+            return this.currentBrowserPage;
+        }
+
+        // Looks like the actual current page is not what we thought the current page was.
+        // Is it one of the pages we are aware of?
+
+        const allPages = await this.allPages();
+        const found = allPages.find(page => page.id.equals(actualCurrentPageId));
+        if (found) {
+            this.currentBrowserPage = found;
+            return this.currentBrowserPage;
+        }
+
+        // OK, so that's a handle that we haven't seen before, let's register it and set as current page.
+        this.currentBrowserPage = await this.registerCurrentPage();
+
+        return this.currentBrowserPage;
+    }
+
+    protected async registerCurrentPage(): Promise<WebdriverIOPage> {
+        const windowHandle = await this.browser.getWindowHandle();
+
+        const errorHandler = new WebdriverIOErrorHandler();
+
+        const page = new WebdriverIOPage(
+            this,
+            this.browser,
+            await this.modalDialogHandlerFor(windowHandle, errorHandler),
+            errorHandler,
+            new CorrelationId(windowHandle)
+        );
+
+        this.register(page)
+
+        return page;
+    }
+
+    private async modalDialogHandlerFor(windowHandle: string, errorHandler: WebdriverIOErrorHandler): Promise<ModalDialogHandler> {
+        return this.browser.isDevTools
+            ? new WebdriverIOPuppeteerModalDialogHandler(await this.puppeteerPageFor(windowHandle))
+            : new WebdriverIOModalDialogHandler(this.browser, errorHandler);
+    }
+
+    private async puppeteerPageFor(windowHandle: string): Promise<Page>  {
+        const puppeteer = await this.browser.getPuppeteer();
+        const pages = await puppeteer.pages();
+
+        const handles = await this.browser.getWindowHandles();
+
+        if (handles.length !== pages.length) {
+            throw new LogicError(`The number of registered Puppeteer pages doesn't match WebdriverIO window handles.`)
+        }
+
+        const index = handles.indexOf(windowHandle);
+
+        // We cast to `unknown` first because the version of Page in Puppeteer-core
+        // might be slightly out-of-sync with what the WebdriverIO uses.
+        // This doesn't really matter since we're only using it to work with Dialogs.
+        const page = pages[index] as unknown as Page;
+
+        if (! page) {
+            throw new LogicError(`Couldn't find Puppeteer page for WebdriverIO window handle ${ windowHandle }.`)
+        }
+
+        return page;
+    }
+}

package/src/screenplay/models/WebdriverIOCookie.ts

@@ -3,6 +3,11 @@ import { Cookie, CookieData, CookieMissingError } from '@serenity-js/web';
 import { ensure, isDefined } from 'tiny-types';
 import * as wdio from 'webdriverio';
 
+/**
+ * WebdriverIO-specific implementation of {@apilink Cookie}.
+ *
+ * @group Models
+ */
 export class WebdriverIOCookie extends Cookie {
 
     constructor(
@@ -14,7 +19,7 @@ export class WebdriverIOCookie extends Cookie {
     }
 
     async delete(): Promise<void> {
-        return this.browser.deleteCookies(this.cookieName) as Promise<void>;
+        await this.browser.deleteCookies(this.cookieName);
     }
 
     protected async read(): Promise<CookieData> {
@@ -34,7 +39,7 @@ export class WebdriverIOCookie extends Cookie {
             value:      cookie.value,
             domain:     cookie.domain,
             path:       cookie.path,
-            expiry:     expiry !== undefined
+            expiry:     typeof expiry === 'number' && expiry >= 0
                 ? Timestamp.fromTimestampInSeconds(Math.round(expiry))
                 : undefined,
             httpOnly:   cookie.httpOnly,

package/src/screenplay/models/WebdriverIOErrorHandler.ts

@@ -0,0 +1,25 @@
+import { WebdriverProtocolErrorCode } from './WebdriverProtocolErrorCode';
+
+export class WebdriverIOErrorHandler {
+
+    constructor(private readonly handlers: Map<WebdriverProtocolErrorCode, (error: Error) => Promise<void> | void> = new Map()) {
+    }
+
+    async executeIfHandled<T>(error: Error, action: () => Promise<T> | T): Promise<T> {
+        if (! this.handlers.has(error.name as WebdriverProtocolErrorCode)) {
+            throw error;
+        }
+
+        await this.handlers.get(error.name as WebdriverProtocolErrorCode)(error);
+
+        return action();
+    }
+
+    setHandlerFor(errorType: WebdriverProtocolErrorCode, handler: (error: Error) => Promise<void> | void): void {
+        this.handlers.set(errorType, handler);
+    }
+
+    unsetHandlerFor(errorType: WebdriverProtocolErrorCode): void {
+        this.handlers.delete(errorType);
+    }
+}

package/src/screenplay/models/WebdriverIOModalDialogHandler.ts

@@ -0,0 +1,100 @@
+import { AbsentModalDialog, AcceptedModalDialog, DismissedModalDialog, ModalDialog, ModalDialogHandler } from '@serenity-js/web';
+import * as wdio from 'webdriverio';
+
+import { WebdriverIOErrorHandler } from './WebdriverIOErrorHandler';
+import { WebdriverProtocolErrorCode } from './WebdriverProtocolErrorCode';
+
+/**
+ * WebdriverIO-specific implementation of {@apilink ModalDialogHandler},
+ * used with the [WebDriver protocol](https://webdriver.io/docs/api/webdriver).
+ *
+ * ## Learn more
+ * - {@apilink WebdriverIOPuppeteerModalDialogHandler}
+ *
+ * @group Models
+ */
+export class WebdriverIOModalDialogHandler extends ModalDialogHandler {
+
+    private readonly defaultHandler: () => Promise<void> =
+        async () => {
+            const message = await this.browser.getAlertText();
+
+            await this.browser.dismissAlert();
+
+            this.modalDialog = new DismissedModalDialog(message);
+        }
+
+    private currentHandler: () => Promise<void>;
+
+    constructor(
+        private readonly browser: wdio.Browser<'async'>,
+        private readonly errorHandler: WebdriverIOErrorHandler,
+    ) {
+        super();
+
+        this.currentHandler = this.defaultHandler;
+
+        this.errorHandler.setHandlerFor(WebdriverProtocolErrorCode.UnexpectedAlertOpenError, error_ => this.tryToHandleDialog());
+    }
+
+    async tryToHandleDialog(): Promise<void> {
+        try {
+            await this.currentHandler()
+        }
+        catch (error) {
+            if (error.name === WebdriverProtocolErrorCode.NoSuchAlertError) {
+                this.modalDialog = new AbsentModalDialog();
+                return;
+            }
+            throw error;
+        }
+    }
+
+    async acceptNext(): Promise<void> {
+        this.currentHandler = async () => {
+            const message = await this.browser.getAlertText();
+
+            await this.browser.acceptAlert();
+
+            this.modalDialog = new AcceptedModalDialog(message);
+        };
+    }
+
+    async acceptNextWithValue(text: string | number): Promise<void> {
+        this.currentHandler = async () => {
+            await this.browser.sendAlertText(String(text));
+            const message = await this.browser.getAlertText();
+
+            await this.browser.acceptAlert();
+
+            this.modalDialog = new AcceptedModalDialog(message);
+        };
+    }
+
+    async dismissNext(): Promise<void> {
+        this.currentHandler = async () => {
+            const message = await this.browser.getAlertText();
+
+            await this.browser.dismissAlert();
+
+            this.modalDialog = new DismissedModalDialog(message);
+        }
+    }
+
+    async reset(): Promise<void> {
+        this.modalDialog = new AbsentModalDialog();
+        this.currentHandler = this.defaultHandler;
+    }
+
+    /**
+     * @override
+     */
+    async last(): Promise<ModalDialog> {
+
+        if (this.modalDialog instanceof AbsentModalDialog) {
+            await this.tryToHandleDialog();
+        }
+
+        return this.modalDialog;
+    }
+}

package/src/screenplay/models/WebdriverIOPage.ts

@@ -1,37 +1,203 @@
-import { Page } from '@serenity-js/web';
+import { LogicError } from '@serenity-js/core';
+import { CorrelationId } from '@serenity-js/core/lib/model';
+import { BrowserWindowClosedError, Cookie, CookieData, Key, ModalDialogHandler, Page, PageElement, PageElements, Selector } from '@serenity-js/web';
 import { URL } from 'url';
 import * as wdio from 'webdriverio';
 
-export class WebdriverIOPage extends Page {
+import { WebdriverIOLocator, WebdriverIORootLocator } from './locators';
+import { WebdriverIOBrowsingSession } from './WebdriverIOBrowsingSession';
+import { WebdriverIOCookie } from './WebdriverIOCookie';
+import { WebdriverIOErrorHandler } from './WebdriverIOErrorHandler';
+import { WebdriverIOPageElement } from './WebdriverIOPageElement';
+
+/**
+ * WebdriverIO-specific implementation of {@apilink Page}.
+ *
+ * @group Models
+ */
+export class WebdriverIOPage extends Page<wdio.Element<'async'>> {
+
+    private lastScriptExecutionSummary: LastScriptExecutionSummary;
+
     constructor(
+        session: WebdriverIOBrowsingSession,
         private readonly browser: wdio.Browser<'async'>,
-        handle: string
+        modalDialogHandler: ModalDialogHandler,
+        private readonly errorHandler: WebdriverIOErrorHandler,
+        pageId: CorrelationId,
     ) {
-        super(handle);
+        super(
+            session,
+            new WebdriverIORootLocator(browser),
+            modalDialogHandler,
+            pageId,
+        );
+    }
+
+    locate(selector: Selector): PageElement<wdio.Element<'async'>> {
+        return new WebdriverIOPageElement(
+            new WebdriverIOLocator(this.rootLocator, selector, this.errorHandler)
+        )
+    }
+
+    locateAll(selector: Selector): PageElements<wdio.Element<'async'>> {
+        return new PageElements(
+            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;
+            }
+
+            if (this.browser.isDevTools) {
+                return key.devtoolsName;
+            }
+
+            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 innerArguments = [] as InnerArguments;
+        for (const arg of args) {
+            const innerArgument = arg instanceof WebdriverIOPageElement
+                ? await arg.nativeElement()
+                : arg;
+
+            innerArguments.push(innerArgument);
+        }
+
+        const result = await this.inContextOfThisPage<Result>(() => {
+            return this.browser.execute(script, ...innerArguments);
+        });
+
+        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 parameters = [] as Parameters;
+        for (const arg of args) {
+            const parameter = arg instanceof WebdriverIOPageElement
+                ? await arg.nativeElement()
+                : arg;
+
+            parameters.push(parameter);
+        }
+
+        const result = await this.inContextOfThisPage<Result>(() => {
+            return this.browser.executeAsync<Result, Parameters>(script, ...parameters);
+        });
+
+        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;
     }
 
-    title(): Promise<string> {
-        return this.switchToAndPerform(async browser => {
-            return browser.getTitle();
+    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;
+            }
         });
     }
 
-    name(): Promise<string> {
-        return this.switchToAndPerform(async browser => {
-            return browser.execute(`return window.name`);
+    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.getTitle());
+    }
+
+    async name(): Promise<string> {
+        return await this.inContextOfThisPage(() => this.browser.execute(`return window.name`));
+    }
+
     async url(): Promise<URL> {
-        return this.switchToAndPerform(async browser => {
-            return new URL(await browser.getUrl());
+        return await this.inContextOfThisPage(async () => {
+            return new URL(await this.browser.getUrl());
         });
     }
 
     async viewportSize(): Promise<{ width: number, height: number }> {
-        return this.switchToAndPerform(async browser => {
-            if (! browser.isDevTools) {
-                const calculatedViewportSize = await browser.execute(`
+        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),
@@ -44,77 +210,70 @@ export class WebdriverIOPage extends Page {
                 }
             }
 
-            return browser.getWindowSize();
+            return this.browser.getWindowSize();
         });
     }
 
-    setViewportSize(size: { width: number, height: number }): Promise<void> {
-        return this.switchToAndPerform(async browser => {
+    async setViewportSize(size: { width: number, height: number }): Promise<void> {
+        return await this.inContextOfThisPage(async () => {
             let desiredWindowSize = size;
 
-            if (! browser.isDevTools) {
-                desiredWindowSize = await 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 }),
-                };
-            `);
+            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 browser.setWindowSize(desiredWindowSize.width, desiredWindowSize.height);
+            return this.browser.setWindowSize(desiredWindowSize.width, desiredWindowSize.height);
         });
     }
 
     async close(): Promise<void> {
-        return this.switchToAndPerform(browser => browser.closeWindow());
+        await this.inContextOfThisPage(() => this.browser.closeWindow());
     }
 
     async closeOthers(): Promise<void> {
-        const windowHandles = await this.browser.getWindowHandles();
+        await this.session.closePagesOtherThan(this);
+    }
 
-        for (const handle of windowHandles) {
-            if (handle !== this.handle) {
-                await this.browser.switchToWindow(handle);
-                await this.browser.closeWindow();
+    async isPresent(): Promise<boolean> {
+        const allPages = await this.session.allPages();
+        for (const page of allPages) {
+            if (page === this) {
+                return true;
             }
         }
-
-        await this.browser.switchToWindow(this.handle);
+        return false;
     }
 
-    async isPresent(): Promise<boolean> {
-        const currentPageHandle = await this.browser.getWindowHandle();
-        const desiredPageHandle = this.handle;
+    private async inContextOfThisPage<T>(action: () => Promise<T> | T): Promise<T> {
+        let originalCurrentPage;
 
-        const isOpen = await this.browser.switchToWindow(desiredPageHandle).then(() => true, _error => false);
+        try {
+            originalCurrentPage = await this.session.currentPage();
 
-        await this.browser.switchToWindow(currentPageHandle);
+            await this.session.changeCurrentPageTo(this);
 
-        return isOpen;
-    }
-
-    async switchTo(): Promise<void> {
-        await this.browser.switchToWindow(this.handle);
-    }
-
-    private async switchToAndPerform<T>(action: (browser: wdio.Browser<'async'>) => Promise<T> | T): Promise<T> {
-        const currentPageHandle = await this.browser.getWindowHandle();
-        const desiredPageHandle = this.handle;
-        const shouldSwitch      = currentPageHandle !== desiredPageHandle;
-
-        if (shouldSwitch) {
-            await this.browser.switchToWindow(desiredPageHandle);
+            return await action();
         }
-
-        const result = await action(this.browser);
-
-        if (shouldSwitch) {
-            await this.browser.switchToWindow(currentPageHandle);
+        catch (error) {
+            return await this.errorHandler.executeIfHandled(error, action);
+        }
+        finally {
+            await this.session.changeCurrentPageTo(originalCurrentPage);
         }
-
-        return result;
     }
 }
+
+/**
+ * @package
+ */
+class LastScriptExecutionSummary<Result = any> {
+    constructor(public readonly result: Result) {}
+}