@serenity-js/webdriverio-8 3.31.0

package/src/screenplay/models/WebdriverProtocolErrorCode.ts

@@ -0,0 +1,38 @@
+/**
+ * https://developer.mozilla.org/en-US/docs/Web/WebDriver/Errors#table_of_errors
+ * https://github.com/SeleniumHQ/selenium/blob/e70e22390000a65a6b706fbb33bbff8913555670/javascript/node/selenium-webdriver/lib/error.js#L441
+ *
+ * @package
+ */
+export enum WebdriverProtocolErrorCode {
+    WebDriverError = 'unknown error',
+    DetachedShadowRootError = 'detached shadow root',
+    ElementClickInterceptedError = 'element click intercepted',
+    ElementNotInteractableError = 'element not interactable',
+    ElementNotSelectableError = 'element not selectable',
+    InsecureCertificateError = 'insecure certificate',
+    InvalidArgumentError = 'invalid argument',
+    InvalidCookieDomainError = 'invalid cookie domain',
+    InvalidCoordinatesError = 'invalid coordinates',
+    InvalidElementStateError = 'invalid element state',
+    InvalidSelectorError = 'invalid selector',
+    NoSuchSessionError = 'invalid session id',
+    JavascriptError = 'javascript error',
+    MoveTargetOutOfBoundsError = 'move target out of bounds',
+    NoSuchAlertError = 'no such alert',
+    NoSuchCookieError = 'no such cookie',
+    NoSuchElementError = 'no such element',
+    NoSuchFrameError = 'no such frame',
+    NoSuchShadowRootError = 'no such shadow root',
+    NoSuchWindowError = 'no such window',
+    ScriptTimeoutError = 'script timeout',
+    SessionNotCreatedError = 'session not created',
+    StaleElementReferenceError = 'stale element reference',
+    TimeoutError = 'timeout',
+    UnableToSetCookieError = 'unable to set cookie',
+    UnableToCaptureScreenError = 'unable to capture screen',
+    UnexpectedAlertOpenError = 'unexpected alert open',
+    UnknownCommandError = 'unknown command',
+    UnknownMethodError = 'unknown method',
+    UnsupportedOperationError = 'unsupported operation',
+}

package/src/screenplay/models/index.ts

@@ -0,0 +1,4 @@
+export * from './WebdriverIOBrowsingSession.js';
+export * from './WebdriverIOCookie.js';
+export * from './WebdriverIOPage.js';
+export * from './WebdriverIOPageElement.js';

package/src/screenplay/models/locators/WebdriverIOLocator.ts

@@ -0,0 +1,176 @@
+import 'webdriverio';
+
+import { f, LogicError } from '@serenity-js/core';
+import type { PageElement, RootLocator, Selector } from '@serenity-js/web';
+import { ByCss, ByCssContainingText, ByDeepCss, ById, ByTagName, ByXPath, Locator } from '@serenity-js/web';
+
+import type { WebdriverIOErrorHandler } from '../WebdriverIOErrorHandler.js';
+import { WebdriverIOPageElement } from '../WebdriverIOPageElement.js';
+import type { WebdriverIORootLocator } from './WebdriverIORootLocator.js';
+
+/**
+ * WebdriverIO-specific implementation of [`Locator`](https://serenity-js.org/api/web/class/Locator/).
+ *
+ * @group Models
+ */
+export class WebdriverIOLocator extends Locator<WebdriverIO.Element, string> {
+
+    constructor(
+        parent: RootLocator<WebdriverIO.Element>,
+        selector: Selector,
+        private readonly errorHandler: WebdriverIOErrorHandler,
+    ) {
+        super(parent, selector);
+    }
+
+    // todo: refactor; replace with a map and some more generic lookup mechanism
+    protected nativeSelector(): string {
+        if (this.selector instanceof ByCss) {
+            return this.selector.value;
+        }
+
+        if (this.selector instanceof ByDeepCss) {
+            return `>>> ${ this.selector.value }`;
+        }
+
+        if (this.selector instanceof ByCssContainingText) {
+            return `${ this.selector.value }*=${ this.selector.text }`;
+        }
+
+        if (this.selector instanceof ById) {
+            return `#${ this.selector.value }`;
+        }
+
+        if (this.selector instanceof ByTagName) {
+            return `<${ this.selector.value } />`;
+        }
+
+        if (this.selector instanceof ByXPath) {
+            return this.selector.value;
+        }
+
+        throw new LogicError(f `${ this.selector } is not supported by ${ this.constructor.name }`);
+    }
+
+    async isPresent(): Promise<boolean> {
+        try {
+            const element = await this.resolveNativeElement();
+            return Boolean(element);
+        }
+        catch {
+            return false;
+        }
+    }
+
+    async nativeElement(): Promise<WebdriverIO.Element> {
+        try {
+            return await this.resolveNativeElement();
+        }
+        catch (error) {
+            return await this.errorHandler.executeIfHandled(error, () => this.resolveNativeElement());
+        }
+    }
+
+    protected async resolveNativeElement(): Promise<WebdriverIO.Element> {
+        const parent = await this.parent.nativeElement();
+
+        if (parent.error) {
+            throw parent.error;
+        }
+
+        const element = await parent.$(this.nativeSelector());
+
+        if (element.error) {
+            throw element.error;
+        }
+
+        return element;
+    }
+
+    async allNativeElements(): Promise<Array<WebdriverIO.Element>> {
+        const parent = await this.parent.nativeElement();
+        return parent.$$(this.nativeSelector()) as unknown as Promise<Array<WebdriverIO.Element>>;
+    }
+
+    of(parent: WebdriverIOLocator): Locator<WebdriverIO.Element, string> {
+        return new WebdriverIOLocator(parent, this.selector, this.errorHandler);
+    }
+
+    closestTo(child: WebdriverIOLocator): Locator<WebdriverIO.Element, string> {
+        return new WebdriverIOParentElementLocator(this.parent, this.selector, child, this.errorHandler);
+    }
+
+    locate(child: WebdriverIOLocator): Locator<WebdriverIO.Element, string> {
+        return new WebdriverIOLocator(this, child.selector, this.errorHandler);
+    }
+
+    element(): PageElement<WebdriverIO.Element> {
+        return new WebdriverIOPageElement(this);
+    }
+
+    async allElements(): Promise<Array<PageElement<WebdriverIO.Element>>> {
+        const elements = await this.allNativeElements();
+
+        return elements.map(childElement =>
+            new WebdriverIOPageElement(
+                new WebdriverIOExistingElementLocator(
+                    this.parent as WebdriverIORootLocator,
+                    this.selector,
+                    this.errorHandler,
+                    childElement
+                )
+            )
+        );
+    }
+}
+
+/**
+ * @internal
+ */
+export class WebdriverIOExistingElementLocator extends WebdriverIOLocator {
+    constructor(
+        parentRoot: RootLocator<WebdriverIO.Element>,
+        selector: Selector,
+        errorHandler: WebdriverIOErrorHandler,
+        private readonly existingNativeElement: WebdriverIO.Element,
+    ) {
+        super(parentRoot, selector, errorHandler);
+    }
+
+    async nativeElement(): Promise<WebdriverIO.Element> {
+        return this.existingNativeElement;
+    }
+
+    async allNativeElements(): Promise<Array<WebdriverIO.Element>> {
+        return [ this.existingNativeElement ];
+    }
+}
+
+class WebdriverIOParentElementLocator extends WebdriverIOLocator {
+    constructor(
+        parentRoot: RootLocator<WebdriverIO.Element>,
+        selector: Selector,
+        private readonly child: WebdriverIOLocator,
+        errorHandler: WebdriverIOErrorHandler
+    ) {
+        super(parentRoot, selector, errorHandler);
+    }
+
+    protected override async resolveNativeElement(): Promise<WebdriverIO.Element> {
+        const cssSelector = this.asCssSelector(this.selector);
+        const child = await this.child.nativeElement();
+
+        if (child.error)  {
+            throw child.error;
+        }
+
+        return child.$(
+            /* c8 ignore next */
+            new Function(`return this.closest(\`${ cssSelector.value }\`)`) as () => HTMLElement
+        );
+    }
+
+    override async allNativeElements(): Promise<Array<WebdriverIO.Element>> {
+        return [ await this.nativeElement() ];
+    }
+}

package/src/screenplay/models/locators/WebdriverIORootLocator.ts

@@ -0,0 +1,34 @@
+import 'webdriverio';
+
+import { RootLocator } from '@serenity-js/web';
+
+/**
+ * WebdriverIO-specific implementation of [`RootLocator`](https://serenity-js.org/api/web/class/RootLocator/).
+ *
+ * @group Models
+ */
+export class WebdriverIORootLocator extends RootLocator<WebdriverIO.Browser> {
+    constructor(private readonly browser: WebdriverIO.Browser) {
+        super();
+    }
+
+    async isPresent(): Promise<boolean> {
+        return true;
+    }
+
+    async nativeElement(): Promise<Pick<WebdriverIO.Browser, '$' | '$$'>> {
+        return this.browser;
+    }
+
+    async switchToFrame(frame: Element | object): Promise<void> {
+        await this.browser.switchToFrame(frame);
+    }
+
+    async switchToParentFrame(): Promise<void> {
+        await this.browser.switchToParentFrame();
+    }
+
+    async switchToMainFrame(): Promise<void> {
+        await this.browser.switchToFrame(null); // eslint-disable-line unicorn/no-null
+    }
+}

package/src/screenplay/models/locators/index.ts

@@ -0,0 +1,2 @@
+export * from './WebdriverIOLocator.js';
+export * from './WebdriverIORootLocator.js';