@serenity-js/protractor 3.0.0-rc.9 → 3.0.1

package/src/screenplay/models/ProtractorPageElement.ts

@@ -1,71 +1,96 @@
-import { PageElement } from '@serenity-js/web';
-import { ElementFinder, protractor } from 'protractor';
-import { WebElement } from 'selenium-webdriver';
+import { LogicError } from '@serenity-js/core';
+import { PageElement, SelectOption, SwitchableOrigin } from '@serenity-js/web';
+import * as scripts from '@serenity-js/web/lib/scripts';
+import { by, ElementFinder, protractor } from 'protractor';
+import { Locator, WebElement } from 'selenium-webdriver';
 
 import { promised } from '../promised';
+import { ProtractorLocator } from './locators';
+
+/**
+ * Protractor-specific implementation of {@apilink PageElement}.
+ *
+ * @group Models
+ */
+export class ProtractorPageElement extends PageElement<ElementFinder> {
 
-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();
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        async function focusOn(element: ElementFinder) {
+            const webElement = await element.getWebElement();
+            await promised(webElement.getDriver().executeScript(`arguments[0].focus()`, webElement));
+        }
 
-        if (currentValue !== null && currentValue !== undefined) {
-            const element = await this.nativeElement();
-            return removeCharactersFrom(element, currentValue.length);
+        // eslint-disable-next-line unicorn/consistent-function-scoping
+        async function removeCharactersFrom(elf: ElementFinder, numberOfCharacters: number): Promise<void> {
+            if (numberOfCharacters > 0) {
+                await focusOn(elf);
+                await elf.sendKeys(
+                    protractor.Key.HOME,
+                    ...times(numberOfCharacters, protractor.Key.DELETE),
+                );
+            }
+        }
+
+        const value = await this.value();
+        const hasValue = value !== null && value !== undefined;
+
+        const element = await this.nativeElement();
+
+        if (hasValue) {
+            return removeCharactersFrom(element, value.length);
+        }
+
+        const contentEditable = await promised(element.getAttribute('contenteditable'));
+        const hasContentEditable = contentEditable !== null && contentEditable !== undefined && contentEditable !== 'false';
+
+        if (hasContentEditable) {
+            const text = await this.text();
+            return removeCharactersFrom(element, text.length);
         }
     }
 
     async click(): Promise<void> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.click();
+        await promised(element.click());
     }
 
     async doubleClick(): Promise<void> {
         const element: ElementFinder = await this.nativeElement();
         const webElement: WebElement = await element.getWebElement();
 
-        return promised(
+        await promised(
             webElement.getDriver().actions()
                 .mouseMove(webElement)
                 .doubleClick()
-                .perform()
+                .perform(),
         );
     }
 
     async enterValue(value: string | number | Array<string | number>): Promise<void> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.sendKeys(
-            [].concat(value).join('')
-        );
+        await promised(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)
+        await promised(
+            webElement.getDriver().executeScript('arguments[0].scrollIntoView(true);', webElement),
         );
     }
 
@@ -73,10 +98,10 @@ export class ProtractorPageElement
         const element: ElementFinder = await this.nativeElement();
         const webElement: WebElement = await element.getWebElement();
 
-        return promised(
+        await promised(
             webElement.getDriver().actions()
                 .mouseMove(webElement)
-                .perform()
+                .perform(),
         );
     }
 
@@ -84,31 +109,74 @@ export class ProtractorPageElement
         const element: ElementFinder = await this.nativeElement();
         const webElement: WebElement = await element.getWebElement();
 
-        return promised(
+        await promised(
             webElement.getDriver().actions()
                 .mouseMove(webElement)
                 .click(protractor.Button.RIGHT)
-                .perform()
+                .perform(),
+        );
+    }
+
+    async selectOptions(...options: SelectOption[]): Promise<void> {
+        const element: ElementFinder = await this.nativeElement();
+
+        for (const option of options) {
+            if (option.value) {
+                await promised(element.element(by.xpath(`//option[@value='${ option.value }']`) as Locator).click());
+            }
+            else if (option.label) {
+                await promised(element.element(by.cssContainingText('option', option.label) as Locator).click());
+            }
+        }
+    }
+
+    async selectedOptions(): Promise<SelectOption[]> {
+        const element: ElementFinder = await this.locator.nativeElement();
+
+        const webElement = await element.getWebElement();
+
+        const browser = element.browser_;
+
+        const options: Array<{ label: string, value: string, selected: boolean, disabled: boolean }> = await browser.executeScript(
+            /* istanbul ignore next */
+            (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;
+            },
+            webElement as unknown
+        );
+
+        return options.map(option =>
+            new SelectOption(option.label, option.value, option.selected, option.disabled)
         );
     }
 
     async attribute(name: string): Promise<string> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.getAttribute(name);
+        return await promised(element.getAttribute(name));
     }
 
     async text(): Promise<string> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.getText();
+        return await promised(element.getText());
     }
 
     async value(): Promise<string> {
         const element: ElementFinder = await this.nativeElement();
         const webElement: WebElement = await element.getWebElement();
 
-        return promised(webElement.getDriver().executeScript(
+        return await promised(webElement.getDriver().executeScript(
             /* istanbul ignore next */
             function getValue(webElement) {
                 return webElement.value;
@@ -117,169 +185,96 @@ export class ProtractorPageElement
         ));
     }
 
+    async switchTo(): Promise<SwitchableOrigin> {
+        const element: ElementFinder = await this.locator.nativeElement();
+
+        try {
+            const tagName = await element.getTagName();
+
+            if ([ 'iframe', 'frame' ].includes(tagName)) {
+                const locator = (this.locator as ProtractorLocator);
+                await locator.switchToFrame(element);
+
+                return {
+                    switchBack: async (): Promise<void> => {
+                        await locator.switchToParentFrame();
+                    },
+                };
+            }
+            else {
+                // https://github.com/angular/protractor/issues/1846#issuecomment-82634739;
+                const webElement = await element.getWebElement();
+
+                // focus on element
+                const previouslyFocusedElement = await promised(webElement.getDriver().switchTo().activeElement());
+
+                await promised(webElement.getDriver().executeScript(`arguments[0].focus()`, webElement));
+
+                return {
+                    switchBack: async (): Promise<void> => {
+                        await promised(webElement.getDriver().executeScript(`arguments[0].focus()`, previouslyFocusedElement));
+                    },
+                };
+            }
+        } catch (error) {
+            throw new LogicError(`Couldn't switch to page element located ${ this.locator }`, error);
+        }
+    }
+
     async isActive(): Promise<boolean> {
         const element: ElementFinder = await this.nativeElement();
         const webElement: WebElement = await element.getWebElement();
 
-        return webElement.getDriver().switchTo().activeElement().then((active: WebElement) =>
+        return await promised(webElement.getDriver().switchTo().activeElement().then((active: WebElement) =>
             element.equals(active),
-        );
+        ));
     }
 
     async isClickable(): Promise<boolean> {
-        return this.isEnabled();
+        return await this.isEnabled();
     }
 
     async isEnabled(): Promise<boolean> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.isEnabled();
+        return await promised(element.isEnabled());
     }
 
     async isPresent(): Promise<boolean> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.isPresent();
+        return await promised(element.isPresent());
     }
 
     async isSelected(): Promise<boolean> {
         const element: ElementFinder = await this.nativeElement();
 
-        return element.isSelected();
+        return await promised(element.isSelected());
     }
 
     async isVisible(): Promise<boolean> {
-        const element: ElementFinder = await this.nativeElement();
-
-        if (! await element.isDisplayed()) {
-            return false;
-        }
+        try {
+            const element: ElementFinder = await this.nativeElement();
 
-        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
+            if (! await element.isDisplayed()) {
+                return false;
             }
 
-            // 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)
-            }
+            const webElement: WebElement = await element.getWebElement();
 
-            // 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)
-            }
+            // get element at cx/cy and see if the element we found is our element, and therefore it's visible.
+            return await promised(webElement.getDriver().executeScript(
+                scripts.isVisible,
+                webElement,
+            ));
+        }
+        catch (error) {
 
-            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)
+            if (error.name === 'NoSuchElementError') {
+                return false;
             }
 
-            return isElementInViewport(element) && isOverlappingElementMatch(getOverlappingElements(element), element);
-            `,
-            webElement,
-        ));
+            throw error;
+        }
     }
 }

package/src/screenplay/models/index.ts

@@ -1,5 +1,5 @@
+export * from './ProtractorBrowsingSession';
 export * from './ProtractorCookie';
-export * from './ProtractorModalDialog';
 export * from './ProtractorPage';
 export * from './ProtractorPageElement';
 

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

@@ -1,50 +1,140 @@
-import { Locator, PageElement, Selector } from '@serenity-js/web';
-import { ElementFinder, Locator as ProtractorNativeLocator, ProtractorBrowser } from 'protractor';
+import { f, LogicError } from '@serenity-js/core';
+import { ByCss, ByCssContainingText, ByDeepCss, ById, ByTagName, ByXPath, Locator, PageElement, RootLocator, Selector } from '@serenity-js/web';
+import * as protractor from 'protractor';
 
 import { unpromisedWebElement } from '../../unpromisedWebElement';
+import { ProtractorErrorHandler } from '../ProtractorErrorHandler';
 import { ProtractorPageElement } from '../ProtractorPageElement';
-import { ProtractorNativeElementRoot } from './ProtractorNativeElementRoot';
+import { ProtractorRootLocator } from './ProtractorRootLocator';
 
-export class ProtractorLocator<Selector_Type extends Selector> extends Locator<ElementFinder, ProtractorNativeElementRoot, Selector_Type> {
+/**
+ * Protractor-specific implementation of {@apilink Locator}.
+ *
+ * @group Models
+ */
+export class ProtractorLocator extends Locator<protractor.ElementFinder, protractor.Locator> {
 
-    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),
+    constructor(
+        parent: RootLocator<protractor.ElementFinder>,
+        selector: Selector,
+        private readonly errorHandler: ProtractorErrorHandler,
+    ) {
+        super(parent, selector);
+    }
+
+    // todo: refactor; replace with a map and some more generic lookup mechanism
+    protected nativeSelector(): protractor.Locator {
+        if (this.selector instanceof ByCss) {
+            return protractor.by.css(this.selector.value);
+        }
+
+        if (this.selector instanceof ByDeepCss) {
+            if (! protractor.by.shadowDomCss) {
+                throw new LogicError(`By.deepCss() requires query-selector-shadow-dom plugin, which Serenity/JS ProtractorFrameworkAdapter registers by default. If you're using Serenity/JS without ProtractorFrameworkAdapter, please register the plugin yourself.`)
+            }
+
+            return protractor.by.shadowDomCss(this.selector.value.replace('>>>', '').trim());
+        }
+
+        if (this.selector instanceof ByCssContainingText) {
+            return protractor.by.cssContainingText(this.selector.value, this.selector.text);
+        }
+
+        if (this.selector instanceof ById) {
+            return protractor.by.id(this.selector.value);
+        }
+
+        if (this.selector instanceof ByTagName) {
+            return protractor.by.tagName(this.selector.value);
+        }
+
+        if (this.selector instanceof ByXPath) {
+            return protractor.by.xpath(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<protractor.ElementFinder> {
+        try {
+            return await this.resolveNativeElement();
+        }
+        catch (error) {
+            return await this.errorHandler.executeIfHandled(error, () => this.resolveNativeElement());
+        }
+    }
+
+    private async resolveNativeElement(): Promise<protractor.ElementFinder> {
+        const parent = await this.parent.nativeElement();
+        const result = await unpromisedWebElement(parent.element(this.nativeSelector()));
+
+        // checks if the element can be interacted with; in particular, throws unexpected alert present if there is one
+        await result.isPresent();
+
+        return result;
+    }
 
-        return new ProtractorLocator(
-            () => parentRoot,
-            selector,
-            (root: ProtractorNativeElementRoot) => unpromisedWebElement(root.element(protractorBy)),
-            async (root: ProtractorNativeElementRoot) => root.all(protractorBy)
-        );
+    async allNativeElements(): Promise<Array<protractor.ElementFinder>> {
+        const parent = await this.parent.nativeElement();
+        return parent.all(this.nativeSelector()) as unknown as Array<protractor.ElementFinder>;
     }
 
-    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),
-        );
+    of(parent: ProtractorLocator): Locator<protractor.ElementFinder, protractor.Locator> {
+        return new ProtractorLocator(parent, this.selector, this.errorHandler);
     }
 
-    element(): PageElement<ElementFinder> {
+    locate(child: ProtractorLocator): Locator<protractor.ElementFinder, any> {
+        return new ProtractorLocator(this, child.selector, this.errorHandler);
+    }
+
+    element(): PageElement<protractor.ElementFinder> {
         return new ProtractorPageElement(this);
     }
 
-    async allElements(): Promise<Array<PageElement<ElementFinder>>> {
-        const parentRoot    = await this.parentRoot()
-        const elements      = await this.locateAllElements(parentRoot);
+    async allElements(): Promise<Array<PageElement<protractor.ElementFinder>>> {
+        const elements      = await this.allNativeElements();
 
         return Promise.all(elements.map(childElement =>
-            new ProtractorPageElement(new ProtractorLocator(
-                this.parentRoot,
-                this.selector,
-                () => unpromisedWebElement(childElement),
-                () => [ unpromisedWebElement(childElement) ],
-            ))
+            new ProtractorPageElement(
+                new ExistingElementLocator(
+                    this.parent as ProtractorRootLocator,
+                    this.selector,
+                    this.errorHandler,
+                    unpromisedWebElement(childElement)
+                )
+            )
         ));
     }
 }
+
+/**
+ * @private
+ */
+class ExistingElementLocator extends ProtractorLocator {
+    constructor(
+        parent: ProtractorRootLocator,
+        selector: Selector,
+        errorHandler: ProtractorErrorHandler,
+        private readonly existingNativeElement: protractor.ElementFinder,
+    ) {
+        super(parent, selector, errorHandler);
+    }
+
+    async nativeElement(): Promise<protractor.ElementFinder> {
+        return this.existingNativeElement;
+    }
+
+    async allNativeElements(): Promise<Array<protractor.ElementFinder>> {
+        return [ this.existingNativeElement ];
+    }
+}

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

@@ -0,0 +1,41 @@
+import { RootLocator } from '@serenity-js/web';
+import * as protractor from 'protractor';
+
+import { promised } from '../../promised';
+
+/**
+ * Protractor-specific implementation of {@apilink RootLocator}.
+ *
+ * @group Models
+ */
+export class ProtractorRootLocator extends RootLocator<protractor.ElementFinder> {
+    constructor(private readonly browser: protractor.ProtractorBrowser) {
+        super();
+    }
+
+    async isPresent(): Promise<boolean> {
+        return true;
+    }
+
+    async nativeElement(): Promise<Pick<protractor.ElementFinder, 'element' | 'all'>> {
+        return {
+            element: this.browser.element.bind(this.browser),
+            all:     this.browser.element.all.bind(this.browser),
+        };
+    }
+
+    async switchToFrame(element: protractor.ElementFinder): Promise<void> {
+        // https://github.com/angular/protractor/issues/1846#issuecomment-82634739;
+        const webElement = await element.getWebElement();
+
+        await promised(this.browser.switchTo().frame(webElement));
+    }
+
+    async switchToParentFrame(): Promise<void> {
+        await promised(this.browser.driver.switchToParentFrame());
+    }
+
+    async switchToMainFrame(): Promise<void> {
+        await promised(this.browser.driver.switchTo().defaultContent());
+    }
+}

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

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