@serenity-js/webdriverio-8 3.31.0

package/src/adapter/reporter/TagPrinter.ts

@@ -0,0 +1,69 @@
+import type { Tag } from '@serenity-js/core/lib/model/index.js';
+import { BrowserTag, PlatformTag } from '@serenity-js/core/lib/model/index.js';
+import type { Capabilities } from '@wdio/types';
+
+/**
+ * @package
+ */
+export class TagPrinter {
+    tagsFor(capability: Capabilities.DesiredCapabilities | Capabilities.W3CCapabilities): Tag[] {
+        const desiredCapabilities = this.desired(capability);
+
+        return [
+            this.browserTagFor(desiredCapabilities),
+            this.platformTagFor(desiredCapabilities),
+        ];
+    }
+
+    private browserTagFor(capabilities: Capabilities.DesiredCapabilities): Tag {
+        return new BrowserTag(
+            this.browserNameFrom(capabilities),
+            this.browserVersionFrom(capabilities),
+        );
+    }
+
+    private platformTagFor(capabilities: Capabilities.DesiredCapabilities): Tag {
+        return new PlatformTag(
+            this.platformNameFrom(capabilities),
+            this.platformVersionFrom(capabilities),
+        );
+    }
+
+    private browserNameFrom(capabilities: Capabilities.DesiredCapabilities): string {
+        return capabilities.browserName
+            || capabilities.browser
+            || (capabilities['appium:app'] && capabilities['appium:app'].replace('sauce-storage:', ''))
+            || 'unknown';
+    }
+
+    private browserVersionFrom(capabilities: Capabilities.DesiredCapabilities): string | undefined {
+        return capabilities.deviceName          // mobile web
+            || capabilities['appium:deviceName']
+            || capabilities.browserVersion      // W3C format
+            || capabilities.version             // JSONWP format
+            || capabilities.browser_version;    // BrowserStack
+    }
+
+    private platformNameFrom(capabilities: Capabilities.DesiredCapabilities): string {
+        return capabilities.platformName
+            || capabilities['appium:platformName']
+            || capabilities.platform
+            || capabilities.os
+            || 'unknown';
+    }
+
+    private platformVersionFrom(capabilities: Capabilities.DesiredCapabilities): string | undefined {
+        return capabilities['appium:platformVersion']
+            || capabilities.os_version;
+    }
+
+    private desired(capabilities: Capabilities.RemoteCapability): Capabilities.DesiredCapabilities {
+        return this.isW3C(capabilities)
+            ? capabilities.alwaysMatch
+            : capabilities;
+    }
+
+    private isW3C(capabilities: Capabilities.RemoteCapability): capabilities is Capabilities.W3CCapabilities {
+        return !!(capabilities as Capabilities.W3CCapabilities).alwaysMatch;
+    }
+}

package/src/adapter/reporter/index.ts

@@ -0,0 +1,5 @@
+export * from './BrowserCapabilitiesReporter.js';
+export * from './InitialisesReporters.js';
+export * from './OutputStreamBuffer.js';
+export * from './ProvidesWriteStream.js';
+export * from './TagPrinter.js';

package/src/api.ts

@@ -0,0 +1,2 @@
+export { WebdriverIOConfig } from './config/index.js';
+export * from './screenplay/index.js';

package/src/config/WebdriverIOConfig.ts

@@ -0,0 +1,94 @@
+import type { SerenityConfig } from '@serenity-js/core';
+import type { Options } from '@wdio/types';
+
+/**
+ * [WebdriverIO configuration object](https://webdriver.io/docs/configurationfile/),
+ * with [Serenity/JS-specific additions](https://serenity-js.orgapi/core/class/SerenityConfig/).
+ *
+ * ## Integrating WebdriverIO with Serenity/JS
+ *
+ * ```ts
+ * // wdio.conf.ts
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio-8'
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *   framework: '@serenity-js/webdriverio-8',
+ *
+ *   serenity: {
+ *     runner: 'cucumber',
+ *     // runner: 'mocha',
+ *     // runner: 'jasmine',
+ *
+ *     crew: [
+ *       // Optional, print test execution results to standard output
+ *       '@serenity-js/console-reporter',
+ *
+ *       // Optional, produce Serenity BDD reports
+ *       // and living documentation (HTML)
+ *       '@serenity-js/serenity-bdd',
+ *       [ '@serenity-js/core:ArtifactArchiver', {
+ *           outputDirectory: 'target/site/serenity'
+ *       } ],
+ *
+ *       // Optional, automatically capture screenshots
+ *       // upon interaction failure
+ *       [ '@serenity-js/web:Photographer', {
+ *           strategy: 'TakePhotosOfFailures'
+ *           // strategy: 'TakePhotosOfInteractions'
+ *       } ],
+ *     ]
+ *   },
+ *
+ *   // Configure your Cucumber runner
+ *   cucumberOpts: {
+ *     // see Cucumber configuration options below
+ *   },
+ *
+ *   // ... or Jasmine runner
+ *   jasmineOpts: {
+ *     // see Jasmine configuration options below
+ *   },
+ *
+ *   // ... or Mocha runner
+ *   mochaOpts: {
+ *      // see Mocha configuration options below
+ *   },
+ *
+ *   runner: 'local',
+ *
+ *   specs: [
+ *     './features/*.feature',
+ *
+ *     // or for Mocha/Jasmine
+ *     // './*.spec.ts'
+ *   ],
+ *
+ *   // Any other WebdriverIO configuration
+ * }
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [WebdriverIO configuration file](https://webdriver.io/docs/configurationfile/)
+ * - [`CucumberConfig`](https://serenity-js.org/api/cucumber-adapter/interface/CucumberConfig/)
+ * - [`JasmineConfig`](https://serenity-js.org/api/jasmine-adapter/interface/JasmineConfig/)
+ * - [`MochaConfig`](https://serenity-js.org/api/mocha-adapter/interface/MochaConfig/)
+ *
+ * @group Configuration
+ */
+export interface WebdriverIOConfig extends Options.Testrunner {
+
+    /**
+     * Serenity/JS configuration with an additional `runner` entry
+     * allowing to specify the test runner, such as `cucumber`, `mocha`, or `jasmine`.
+     *
+     * #### Learn more
+     *
+     * - [WebdriverIO configuration file](https://webdriver.io/docs/configurationfile/)
+     * - [`CucumberConfig`](https://serenity-js.org/api/cucumber-adapter/interface/CucumberConfig/)
+     * - [`JasmineConfig`](https://serenity-js.org/api/jasmine-adapter/interface/JasmineConfig/)
+     * - [`MochaConfig`](https://serenity-js.org/api/mocha-adapter/interface/MochaConfig/)
+     */
+    serenity?: SerenityConfig & { runner?: string };
+}

package/src/config/index.ts

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

package/src/index.ts

@@ -0,0 +1,32 @@
+import { serenity } from '@serenity-js/core';
+import { ModuleLoader, Path } from '@serenity-js/core/lib/io/index.js';
+import type { Capabilities } from '@wdio/types';
+import type { EventEmitter } from 'events';
+
+import type { InitialisesReporters, ProvidesWriteStream } from './adapter/reporter/index.js';
+import type { WebdriverIOConfig } from './config/index.js';
+
+/**
+ * WebdriverIO Framework Adapter integrates WebdriverIO with Serenity/JS
+ */
+export default {
+    async init(
+        cid: string,
+        config: WebdriverIOConfig,
+        specs: string[],
+        capabilities: Capabilities.RemoteCapability,
+        reporter: EventEmitter & ProvidesWriteStream & InitialisesReporters
+    ): Promise<{ hasTests: () => boolean, run: () => Promise<number> }> {
+        const { WebdriverIOFrameworkAdapterFactory } = await import('./adapter/index.js');
+
+        const adapterFactory = new WebdriverIOFrameworkAdapterFactory(
+            serenity,
+            new ModuleLoader(process.cwd()),
+            Path.from(process.cwd()),
+        );
+
+        return adapterFactory.init(cid, config, specs, capabilities, reporter);
+    }
+};
+
+export * from './api.js';

package/src/screenplay/abilities/BrowseTheWebWithWebdriverIO.ts

@@ -0,0 +1,46 @@
+import 'webdriverio';
+
+import { BrowseTheWeb } from '@serenity-js/web';
+
+import { WebdriverIOBrowsingSession } from '../models/index.js';
+
+/**
+ * This implementation of the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * enables the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to interact with web front-ends using [WebdriverIO](https://webdriver.io/).
+ *
+ * ## Using WebdriverIO to `BrowseTheWeb`
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio-8'
+ * import { By, Navigate, PageElement, Text } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { browser } from '@wdio/globals'
+ *
+ * const HomePage = {
+ *   title: () =>
+ *     PageElement.located(By.css('h1')).describedAs('title')
+ * }
+ *
+ * await actorCalled('Wendy')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))  // `browser` is global in WebdriverIO tests
+ *   .attemptsTo(
+ *     Navigate.to(`https://serenity-js.org`),
+ *     Ensure.that(Text.of(HomePage.title()), equals('Serenity/JS')),
+ *   );
+ * ```
+ *
+ * ## Learn more
+ * - [WebdriverIO website](https://webdriver.io/)
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`Ability`](https://serenity-js.org/api/core/class/Ability/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ *
+ * @group Abilities
+ */
+export class BrowseTheWebWithWebdriverIO extends BrowseTheWeb<WebdriverIO.Element> {
+
+    static using(browserInstance: WebdriverIO.Browser): BrowseTheWebWithWebdriverIO {
+        return new BrowseTheWebWithWebdriverIO(new WebdriverIOBrowsingSession(browserInstance));
+    }
+}

package/src/screenplay/abilities/index.ts

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

package/src/screenplay/index.ts

@@ -0,0 +1,2 @@
+export * from './abilities/index.js';
+export * from './models/index.js';

package/src/screenplay/models/WebdriverIOBrowsingSession.ts

@@ -0,0 +1,176 @@
+import 'webdriverio';
+
+import { LogicError } from '@serenity-js/core';
+import { CorrelationId } from '@serenity-js/core/lib/model/index.js';
+import type { BrowserCapabilities, ModalDialogHandler } from '@serenity-js/web';
+import { BrowsingSession } from '@serenity-js/web';
+import type { Page } from 'puppeteer-core';
+
+import { WebdriverIOPage } from '../models/index.js';
+import { WebdriverIOErrorHandler } from './WebdriverIOErrorHandler.js';
+import { WebdriverIOModalDialogHandler } from './WebdriverIOModalDialogHandler.js';
+import { WebdriverIOPuppeteerModalDialogHandler } from './WebdriverIOPuppeteerModalDialogHandler.js';
+
+/**
+ * WebdriverIO-specific implementation of [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/).
+ *
+ * @group Models
+ */
+export class WebdriverIOBrowsingSession extends BrowsingSession<WebdriverIOPage> {
+
+    constructor(protected readonly browser: WebdriverIO.Browser) {
+        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?`)
+        }
+    }
+
+    override 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();
+    }
+
+    /**
+     * @param page
+     */
+    override 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.at(-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 override 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;
+    }
+
+    override browserCapabilities(): Promise<BrowserCapabilities> {
+        return Promise.resolve(this.browser.capabilities as BrowserCapabilities);
+    }
+}

package/src/screenplay/models/WebdriverIOCookie.ts

@@ -0,0 +1,51 @@
+import 'webdriverio';
+
+import { Timestamp } from '@serenity-js/core';
+import type { CookieData} from '@serenity-js/web';
+import { Cookie, CookieMissingError } from '@serenity-js/web';
+import { ensure, isDefined } from 'tiny-types';
+
+/**
+ * WebdriverIO-specific implementation of [`Cookie`](https://serenity-js.org/api/web/class/Cookie/).
+ *
+ * @group Models
+ */
+export class WebdriverIOCookie extends Cookie {
+
+    constructor(
+        private readonly browser: WebdriverIO.Browser,
+        cookieName: string,
+    ) {
+        super(cookieName);
+        ensure('browser', browser, isDefined());
+    }
+
+    async delete(): Promise<void> {
+        await this.browser.deleteCookies(this.cookieName);
+    }
+
+    protected async read(): Promise<CookieData> {
+        const [ cookie ] = await this.browser.getCookies(this.cookieName);
+
+        if (! cookie) {
+            throw new CookieMissingError(`Cookie '${ this.cookieName }' not set`);
+        }
+
+        // There _might_ be a bug in WDIO where the expiry date is set on "expires" rather than the "expiry" key
+        // and possibly another one around deserialising the timestamp, since WDIO seems to add several hundred milliseconds
+        // to the original expiry date
+        const expiry: number | undefined = cookie.expiry || (cookie as any).expires;
+
+        return {
+            name:       cookie.name,
+            value:      cookie.value,
+            domain:     cookie.domain,
+            path:       cookie.path,
+            expiry:     typeof expiry === 'number' && expiry >= 0
+                ? Timestamp.fromTimestampInSeconds(Math.round(expiry))
+                : undefined,
+            httpOnly:   cookie.httpOnly,
+            secure:     cookie.secure,
+        }
+    }
+}

package/src/screenplay/models/WebdriverIOErrorHandler.ts

@@ -0,0 +1,25 @@
+import type { WebdriverProtocolErrorCode } from './WebdriverProtocolErrorCode.js';
+
+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,99 @@
+import 'webdriverio';
+
+import type { ModalDialog} from '@serenity-js/web';
+import { AbsentModalDialog, AcceptedModalDialog, DismissedModalDialog, ModalDialogHandler } from '@serenity-js/web';
+
+import type { WebdriverIOErrorHandler } from './WebdriverIOErrorHandler.js';
+import { WebdriverProtocolErrorCode } from './WebdriverProtocolErrorCode.js';
+
+/**
+ * WebdriverIO-specific implementation of [`ModalDialogHandler`](https://serenity-js.org/api/web/class/ModalDialogHandler/),
+ * used with the [WebDriver protocol](https://webdriver.io/docs/api/webdriver).
+ *
+ * @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: WebdriverIO.Browser,
+        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;
+    }
+}