@serenity-js/protractor 2.33.1 → 3.0.0-rc.11

package/src/screenplay/models/ProtractorCookie.ts

@@ -0,0 +1,41 @@
+import { Timestamp } from '@serenity-js/core';
+import { Cookie, CookieData, CookieMissingError } from '@serenity-js/web';
+import { ProtractorBrowser } from 'protractor';
+import { ensure, isDefined } from 'tiny-types';
+
+import { promised } from '../promised';
+
+export class ProtractorCookie extends Cookie {
+
+    constructor(private readonly browser: ProtractorBrowser, cookieName: string) {
+        super(cookieName);
+        ensure('browser', browser, isDefined());
+    }
+
+    delete(): Promise<void> {
+        return promised(this.browser.manage().deleteCookie(this.cookieName));
+    }
+
+    /**
+     * @protected
+     */
+    protected async read(): Promise<CookieData> {
+        const cookie = await this.browser.manage().getCookie(this.cookieName);
+
+        if (! cookie) {
+            throw new CookieMissingError(`Cookie '${ this.cookieName }' not set`);
+        }
+
+        return {
+            name:       cookie.name,
+            value:      cookie.value,
+            domain:     cookie.domain,
+            path:       cookie.path,
+            expiry:     cookie.expiry !== undefined
+                ? Timestamp.fromTimestampInSeconds(Math.round(cookie.expiry))
+                : undefined,
+            httpOnly:   cookie.httpOnly,
+            secure:     cookie.secure,
+        }
+    }
+}

package/src/screenplay/models/ProtractorFrame.ts

@@ -0,0 +1,44 @@
+import { LogicError } from '@serenity-js/core';
+import { Frame, Locator } from '@serenity-js/web';
+import { ElementFinder, ProtractorBrowser, WebElement } from 'protractor';
+
+export class ProtractorFrame extends Frame<ElementFinder> {
+    constructor(
+        private readonly browser: ProtractorBrowser,
+        locator: Locator<ElementFinder>
+    ) {
+        super(locator);
+    }
+
+    async isPresent(): Promise<boolean> {
+        const element: ElementFinder = await this.locator.nativeElement();
+
+        return element.isPresent();
+    }
+
+    async switchTo(): Promise<{ switchBack(): Promise<void> }> {
+        const element: ElementFinder = await this.locator.nativeElement()
+
+        let webElement: WebElement;
+
+        try {
+            // https://github.com/angular/protractor/issues/1846#issuecomment-82634739;
+            webElement = await element.getWebElement();
+        } catch (error) {
+            throw new LogicError(`Couldn't locate frame ${ this.locator }`, error);
+        }
+
+        try {
+            await this.browser.switchTo().frame(webElement);
+
+            return {
+                switchBack: async (): Promise<void> => {
+                    await this.browser.driver.switchToParentFrame();
+                }
+            }
+        }
+        catch (error) {
+            throw new LogicError(`Couldn't switch to a frame located ${ this.locator }`, error);
+        }
+    }
+}

package/src/screenplay/models/ProtractorModalDialog.ts

@@ -0,0 +1,49 @@
+import { ModalDialog } from '@serenity-js/web';
+import { ProtractorBrowser } from 'protractor';
+import { error as errors } from 'selenium-webdriver';
+
+import { promised } from '../promised';
+
+export class ProtractorModalDialog extends ModalDialog {
+
+    constructor(private readonly browser: ProtractorBrowser) {
+        super();
+    }
+
+    accept(): Promise<void> {
+        return promised(this.browser.switchTo().alert().accept());
+    }
+
+    dismiss(): Promise<void> {
+        return promised(this.browser.switchTo().alert().dismiss());
+    }
+
+    text(): Promise<string> {
+        return promised(this.browser.switchTo().alert().getText());
+    }
+
+    async enterValue(value: string | number | (string | number)[]): Promise<void> {
+        const text = [].concat(value).join('');
+        await promised(this.browser.switchTo().alert().sendKeys(text));
+        await promised(this.browser.switchTo().alert().accept());
+    }
+
+    // todo: remove in favour of auto-wait in the above methods
+    isPresent(): Promise<boolean> {
+        return promised(this.browser.switchTo().alert())
+            .then(() => true, error => {
+
+                // Based on:
+                // https://github.com/SeleniumHQ/selenium/blob/941dc9c6b2e2aa4f701c1b72be8de03d4b7e996a/javascript/node/selenium-webdriver/lib/until.js#L107
+                return error instanceof Error &&
+                    ! (
+                        error.name === errors.NoSuchAlertError.name
+                        // XXX: Workaround for GeckoDriver error `TypeError: can't convert null
+                        // to object`. For more details, see
+                        // https://github.com/SeleniumHQ/selenium/pull/2137
+                        || (error.name === errors.WebDriverError.name
+                            && error.message === `can't convert null to object`)
+                    );
+            });
+    }
+}

package/src/screenplay/models/ProtractorPage.ts

@@ -0,0 +1,124 @@
+import { Page } from '@serenity-js/web';
+import { ProtractorBrowser } from 'protractor';
+import { URL } from 'url';
+
+import { promised } from '../promised';
+
+export class ProtractorPage extends Page {
+    constructor(
+        private readonly browser: ProtractorBrowser,
+        handle: string
+    ) {
+        super(handle);
+    }
+
+    title(): Promise<string> {
+        return this.switchToAndPerform(async browser => {
+            return promised(browser.getTitle());
+        });
+    }
+
+    name(): Promise<string> {
+        return this.switchToAndPerform(async browser => {
+            return promised(browser.executeScript('return window.name'));
+        });
+    }
+
+    url(): Promise<URL> {
+        return this.switchToAndPerform(async browser => {
+            return new URL(await promised(browser.getCurrentUrl()));
+        });
+    }
+
+    async viewportSize(): Promise<{ width: number, height: number }> {
+        return this.switchToAndPerform(async browser => {
+            const calculatedViewportSize = await promised(browser.executeScript(
+                `return {
+                    width:  Math.max(document.documentElement.clientWidth,  window.innerWidth || 0),
+                    height: Math.max(document.documentElement.clientHeight, window.innerHeight || 0)
+                };`
+            )) as { width: number, height: number };
+
+            if (calculatedViewportSize.width > 0 && calculatedViewportSize.height > 0) {
+                return calculatedViewportSize;
+            }
+
+            // Chrome headless hard-codes window.innerWidth and window.innerHeight to 0
+            return promised(browser.manage().window().getSize());
+        });
+    }
+
+    async setViewportSize(size: { width: number, height: number }): Promise<void> {
+        return this.switchToAndPerform(async browser => {
+            const desiredWindowSize: { width: number, height: number } = await promised(browser.executeScript(`
+                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 promised(browser.manage().window().setSize(desiredWindowSize.width, desiredWindowSize.height));
+        });
+    }
+
+    async close(): Promise<void> {
+        return this.switchToAndPerform(browser => promised(browser.close()));
+    }
+
+    async closeOthers(): Promise<void> {
+        const windowHandles = await this.browser.getAllWindowHandles();
+
+        for (const handle of windowHandles) {
+            if (handle !== this.handle) {
+                await this.browser.switchTo().window(handle);
+                await this.browser.close();
+            }
+        }
+
+        await this.browser.switchTo().window(this.handle);
+    }
+
+    async isPresent(): Promise<boolean> {
+        const currentPageHandle = await this.browser.getWindowHandle();
+        const desiredPageHandle = this.handle;
+
+        const isOpen = await this.browser.switchTo().window(desiredPageHandle).then(() => true, _error => false);
+
+        await this.browser.switchTo().window(currentPageHandle);
+
+        return isOpen;
+    }
+
+    async switchTo(): Promise<{ switchBack(): Promise<void> }> {
+        const originalWindowHandle = await this.browser.getWindowHandle();
+
+        await this.browser.switchTo().window(this.handle);
+
+        return {
+            switchBack: async (): Promise<void> => {
+                await this.browser.switchTo().window(originalWindowHandle);
+            }
+        }
+    }
+
+    private async switchToAndPerform<T>(action: (browser: ProtractorBrowser) => Promise<T> | T): Promise<T> {
+        const originalPageHandle  = await this.browser.getWindowHandle();
+        const desiredPageHandle   = this.handle;
+        const shouldSwitch        = originalPageHandle !== desiredPageHandle;
+
+        if (shouldSwitch) {
+            await this.browser.switchTo().window(desiredPageHandle);
+        }
+
+        const result = await action(this.browser);
+
+        if (shouldSwitch) {
+            await this.browser.switchTo().window(originalPageHandle);
+        }
+
+        return result;
+    }
+}

package/src/screenplay/models/ProtractorPageElement.ts

@@ -0,0 +1,285 @@
+import { PageElement } from '@serenity-js/web';
+import { ElementFinder, protractor } from 'protractor';
+import { WebElement } from 'selenium-webdriver';
+
+import { promised } from '../promised';
+
+export class ProtractorPageElement
+    extends PageElement<ElementFinder>
+{
+    of(parent: ProtractorPageElement): PageElement<ElementFinder> {
+        return new ProtractorPageElement(this.locator.of(parent.locator));
+    }
+
+    async clearValue(): Promise<void> {
+        function removeCharactersFrom(elf: ElementFinder, numberOfCharacters: number): PromiseLike<void> {
+            return numberOfCharacters === 0
+                ? Promise.resolve(void 0)
+                : elf.sendKeys(
+                    protractor.Key.END,
+                    ...times(numberOfCharacters, protractor.Key.BACK_SPACE),
+                );
+        }
+
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        function times(length: number, key: string) {
+            return Array.from({ length }).map(() => key);
+        }
+
+        const currentValue = await this.value();
+
+        if (currentValue !== null && currentValue !== undefined) {
+            const element = await this.nativeElement();
+            return removeCharactersFrom(element, currentValue.length);
+        }
+    }
+
+    async click(): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.click();
+    }
+
+    async doubleClick(): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+        const webElement: WebElement = await element.getWebElement();
+
+        return promised(
+            webElement.getDriver().actions()
+                .mouseMove(webElement)
+                .doubleClick()
+                .perform()
+        );
+    }
+
+    async enterValue(value: string | number | Array<string | number>): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.sendKeys(
+            [].concat(value).join('')
+        );
+    }
+
+    async scrollIntoView(): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+        const webElement: WebElement = await element.getWebElement();
+
+        return promised(
+            webElement.getDriver().executeScript('arguments[0].scrollIntoView(true);', webElement)
+        );
+    }
+
+    async hoverOver(): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+        const webElement: WebElement = await element.getWebElement();
+
+        return promised(
+            webElement.getDriver().actions()
+                .mouseMove(webElement)
+                .perform()
+        );
+    }
+
+    async rightClick(): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+        const webElement: WebElement = await element.getWebElement();
+
+        return promised(
+            webElement.getDriver().actions()
+                .mouseMove(webElement)
+                .click(protractor.Button.RIGHT)
+                .perform()
+        );
+    }
+
+    async attribute(name: string): Promise<string> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.getAttribute(name);
+    }
+
+    async text(): Promise<string> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.getText();
+    }
+
+    async value(): Promise<string> {
+        const element: ElementFinder = await this.nativeElement();
+        const webElement: WebElement = await element.getWebElement();
+
+        return promised(webElement.getDriver().executeScript(
+            /* istanbul ignore next */
+            function getValue(webElement) {
+                return webElement.value;
+            },
+            webElement,
+        ));
+    }
+
+    async isActive(): Promise<boolean> {
+        const element: ElementFinder = await this.nativeElement();
+        const webElement: WebElement = await element.getWebElement();
+
+        return webElement.getDriver().switchTo().activeElement().then((active: WebElement) =>
+            element.equals(active),
+        );
+    }
+
+    async isClickable(): Promise<boolean> {
+        return this.isEnabled();
+    }
+
+    async isEnabled(): Promise<boolean> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.isEnabled();
+    }
+
+    async isPresent(): Promise<boolean> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.isPresent();
+    }
+
+    async isSelected(): Promise<boolean> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.isSelected();
+    }
+
+    async isVisible(): Promise<boolean> {
+        const element: ElementFinder = await this.nativeElement();
+
+        if (! await element.isDisplayed()) {
+            return false;
+        }
+
+        const webElement: WebElement = await element.getWebElement();
+
+        // get element at cx/cy and see if the element we found is our element, and therefore it's visible.
+        return promised(webElement.getDriver().executeScript(
+            `
+            var element = arguments[0];
+            
+            if (!element.getBoundingClientRect || !element.scrollIntoView || !element.contains || !element.getClientRects || !document.elementFromPoint) {
+                return false
+            }
+
+            // Edge before switching to Chromium
+            const isOldEdge = !!window['StyleMedia']
+            // returns true for Chrome and Firefox and false for Safari, Edge and IE
+            const scrollIntoViewFullSupport = !(window.safari || isOldEdge)
+
+            // get overlapping element
+            function getOverlappingElement (elem, context) {
+                context = context || document
+                const elemDimension = elem.getBoundingClientRect()
+                const x = elemDimension.left + (elem.clientWidth / 2)
+                const y = elemDimension.top + (elem.clientHeight / 2)
+                return context.elementFromPoint(x, y)
+            }
+
+            // get overlapping element rects (currently only the first)
+            // applicable if element's text is multiline.
+            function getOverlappingRects (elem, context) {
+                context = context || document
+                const elems = []
+
+                const rects = elem.getClientRects()
+                // webdriver clicks on center of the first element's rect (line of text), it might change in future
+                const rect = rects[0]
+                const x = rect.left + (rect.width / 2)
+                const y = rect.top + (rect.height / 2)
+                elems.push(context.elementFromPoint(x, y))
+
+                return elems
+            }
+
+            // get overlapping elements
+            function getOverlappingElements (elem, context) {
+                return [getOverlappingElement(elem, context)].concat(getOverlappingRects(elem, context))
+            }
+
+            // is a node a descendant of a given node
+            function nodeContains (elem, otherNode) {
+                // Edge doesn't support neither Shadow Dom nor contains if ShadowRoot polyfill is used
+                if (isOldEdge) {
+                    let tmpElement = otherNode
+                    while (tmpElement) {
+                        if (tmpElement === elem) {
+                            return true
+                        }
+
+                        tmpElement = tmpElement.parentNode
+                        // DocumentFragment / ShadowRoot polyfill like ShadyRoot
+                        if (tmpElement && tmpElement.nodeType === 11 && tmpElement.host) {
+                            tmpElement = tmpElement.host
+                        }
+                    }
+                    return false
+                }
+
+                return elem.contains(otherNode)
+            }
+
+            // is one of overlapping elements the \`elem\` or one of its child
+            function isOverlappingElementMatch (elementsFromPoint, elem) {
+                if (elementsFromPoint.some(function (elementFromPoint) {
+                    return elementFromPoint === elem || nodeContains(elem, elementFromPoint)
+                })) {
+                    return true
+                }
+
+                // shadow root
+                // filter unique elements with shadowRoot
+                // @ts-ignore
+                let elemsWithShadowRoot = [].concat(elementsFromPoint)
+                elemsWithShadowRoot = elemsWithShadowRoot.filter(function (x) {
+                    return x && x.shadowRoot && x.shadowRoot.elementFromPoint
+                })
+
+                // getOverlappingElements of every element with shadowRoot
+                let shadowElementsFromPoint = []
+                for (let i = 0; i < elemsWithShadowRoot.length; ++i) {
+                    let shadowElement = elemsWithShadowRoot[i]
+                    shadowElementsFromPoint = shadowElementsFromPoint.concat(
+                        getOverlappingElements(elem, shadowElement.shadowRoot)
+                    )
+                }
+                // remove duplicates and parents
+                // @ts-ignore
+                shadowElementsFromPoint = [].concat(shadowElementsFromPoint)
+                shadowElementsFromPoint = shadowElementsFromPoint.filter(function (x) {
+                    return !elementsFromPoint.includes(x)
+                })
+
+                if (shadowElementsFromPoint.length === 0) {
+                    return false
+                }
+
+                return isOverlappingElementMatch(shadowElementsFromPoint, elem)
+            }
+
+            function isElementInViewport (elem) {
+                if (!elem.getBoundingClientRect) {
+                    return false
+                }
+        
+                const rect = elem.getBoundingClientRect()
+        
+                const windowHeight = (window.innerHeight || document.documentElement.clientHeight)
+                const windowWidth = (window.innerWidth || document.documentElement.clientWidth)
+        
+                const vertInView = (rect.top <= windowHeight) && ((rect.top + rect.height) > 0)
+                const horInView = (rect.left <= windowWidth) && ((rect.left + rect.width) > 0)
+        
+                return (vertInView && horInView)
+            }
+
+            return isElementInViewport(element) && isOverlappingElementMatch(getOverlappingElements(element), element);
+            `,
+            webElement,
+        ));
+    }
+}

package/src/screenplay/models/index.ts

@@ -0,0 +1,6 @@
+export * from './ProtractorCookie';
+export * from './ProtractorFrame';
+export * from './ProtractorModalDialog';
+export * from './ProtractorPage';
+export * from './ProtractorPageElement';
+

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

@@ -0,0 +1,50 @@
+import { Locator, PageElement, Selector } from '@serenity-js/web';
+import { ElementFinder, Locator as ProtractorNativeLocator, ProtractorBrowser } from 'protractor';
+
+import { unpromisedWebElement } from '../../unpromisedWebElement';
+import { ProtractorPageElement } from '../ProtractorPageElement';
+import { ProtractorNativeElementRoot } from './ProtractorNativeElementRoot';
+
+export class ProtractorLocator<Selector_Type extends Selector> extends Locator<ElementFinder, ProtractorNativeElementRoot, Selector_Type> {
+
+    static createRootLocator<ST extends Selector>(browser: ProtractorBrowser, selector: ST, protractorBy: ProtractorNativeLocator): ProtractorLocator<ST> {
+        const parentRoot: ProtractorNativeElementRoot = {
+            element: browser.element.bind(browser),
+            all: browser.element.all.bind(browser),
+        }
+
+        return new ProtractorLocator(
+            () => parentRoot,
+            selector,
+            (root: ProtractorNativeElementRoot) => unpromisedWebElement(root.element(protractorBy)),
+            async (root: ProtractorNativeElementRoot) => root.all(protractorBy)
+        );
+    }
+
+    of(parent: ProtractorLocator<unknown>): Locator<ElementFinder, ProtractorNativeElementRoot, Selector_Type> {
+        return new ProtractorLocator(
+            () => parent.nativeElement(),
+            this.selector,
+            (parentRoot: ProtractorNativeElementRoot) => this.locateElement(parentRoot),
+            (parentRoot: ProtractorNativeElementRoot) => this.locateAllElements(parentRoot),
+        );
+    }
+
+    element(): PageElement<ElementFinder> {
+        return new ProtractorPageElement(this);
+    }
+
+    async allElements(): Promise<Array<PageElement<ElementFinder>>> {
+        const parentRoot    = await this.parentRoot()
+        const elements      = await this.locateAllElements(parentRoot);
+
+        return Promise.all(elements.map(childElement =>
+            new ProtractorPageElement(new ProtractorLocator(
+                this.parentRoot,
+                this.selector,
+                () => unpromisedWebElement(childElement),
+                () => [ unpromisedWebElement(childElement) ],
+            ))
+        ));
+    }
+}

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

@@ -0,0 +1,6 @@
+import { ElementArrayFinder, ElementFinder, Locator } from 'protractor';
+
+export interface ProtractorNativeElementRoot {
+    element(selector: Locator): ElementFinder;
+    all(selector: Locator): ElementArrayFinder;
+}

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

@@ -0,0 +1,2 @@
+export * from './ProtractorLocator';
+export * from './ProtractorNativeElementRoot';

package/src/{promiseOf.ts → screenplay/promised.ts}

@@ -7,7 +7,7 @@
  * @param promiseLike
  * @returns {Promise<T>}
  */
-export function promiseOf<T>(promiseLike: PromiseLike<T>): Promise<T> {
+export function promised<T>(promiseLike: PromiseLike<T>): Promise<T> {
     return new Promise((resolve, reject) => {
         promiseLike.then(resolve, reject);
     });