@serenity-js/protractor 2.32.4 → 3.0.0-rc.2

package/src/screenplay/interactions/UseAngular.ts

@@ -1,6 +1,6 @@
 import { Interaction } from '@serenity-js/core';
 
-import { BrowseTheWeb } from '../abilities';
+import { BrowseTheWebWithProtractor } from '../abilities';
 
 /**
  * @desc
@@ -53,7 +53,7 @@ export class UseAngular {
      */
     static disableSynchronisation(): Interaction {
         return Interaction.where(`#actor disables synchronisation with Angular`, actor =>
-            BrowseTheWeb.as(actor).enableAngularSynchronisation(false).then(() => void 0));
+            BrowseTheWebWithProtractor.as(actor).enableAngularSynchronisation(false).then(() => void 0));
     }
 
     /**
@@ -65,6 +65,6 @@ export class UseAngular {
      */
     static enableSynchronisation(): Interaction {
         return Interaction.where(`#actor enables synchronisation with Angular`, actor =>
-            BrowseTheWeb.as(actor).enableAngularSynchronisation(true).then(() => void 0));
+            BrowseTheWebWithProtractor.as(actor).enableAngularSynchronisation(true).then(() => void 0));
     }
 }

package/src/screenplay/interactions/index.ts

@@ -1,20 +1 @@
-export * from './Accept';
-export * from './Clear';
-export * from './Click';
-export * from './Close';
-export * from './DeleteCookies';
-export * from './Dismiss';
-export * from './DoubleClick';
-export * from './Enter';
-export * from './ExecuteScript';
-export * from './Hover';
-export * from './Navigate';
-export * from './Press';
-export * from './ResizeBrowserWindow';
-export * from './RightClick';
-export * from './Scroll';
-export * from './Select';
-export * from './Switch';
-export * from './TakeScreenshot';
 export * from './UseAngular';
-export * from './Wait';

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/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/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/ProtractorPage.ts

@@ -0,0 +1,116 @@
+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<void> {
+        await this.browser.switchTo().window(this.handle);
+    }
+
+    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,167 @@
+import { PageElement } from '@serenity-js/web';
+import { ElementFinder, protractor } from 'protractor';
+import { WebElement } from 'selenium-webdriver';
+
+import { promised } from '../promised';
+import { promisedWebElement } from '../promisedWebElement';
+import { ProtractorNativeElementRoot } from './ProtractorNativeElementRoot';
+
+export class ProtractorPageElement
+    extends PageElement<ProtractorNativeElementRoot, ElementFinder>
+{
+    constructor(
+        context: () => Promise<ProtractorNativeElementRoot> | ProtractorNativeElementRoot,
+        locator: (root: ProtractorNativeElementRoot) => Promise<ElementFinder> | ElementFinder
+    ) {
+        super(context, context => {
+            return promisedWebElement<ElementFinder>(locator(context));
+        });
+    }
+
+    of(parent: ProtractorPageElement): PageElement<ProtractorNativeElementRoot, ElementFinder> {
+        return new ProtractorPageElement(() => parent.nativeElement(), this.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 isDisplayed(): Promise<boolean> {
+        const element: ElementFinder = await this.nativeElement();
+
+        return element.isDisplayed();
+    }
+
+    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();
+    }
+}

package/src/screenplay/models/ProtractorPageElements.ts

@@ -0,0 +1,86 @@
+import { LogicError } from '@serenity-js/core';
+import { PageElement, PageElements } from '@serenity-js/web';
+import { ElementArrayFinder, ElementFinder } from 'protractor';
+
+import { promisedWebElement } from '../promisedWebElement';
+import { ProtractorNativeElementRoot } from './ProtractorNativeElementRoot';
+import { ProtractorPageElement } from './ProtractorPageElement';
+
+export class ProtractorPageElements
+    extends PageElements<ProtractorNativeElementRoot, ElementArrayFinder, ElementFinder>
+{
+    constructor(
+        context: () => Promise<ProtractorNativeElementRoot> | ProtractorNativeElementRoot,
+        locator: (root: ProtractorNativeElementRoot) => Promise<ElementArrayFinder> | ElementArrayFinder
+    ) {
+        super(context, async (context: ProtractorNativeElementRoot): Promise<ElementArrayFinder> => {
+            return promisedWebElement<ElementArrayFinder>(locator(context));
+        });
+    }
+
+    of(parent: PageElement<ProtractorNativeElementRoot, ElementFinder>): ProtractorPageElements {
+        return new ProtractorPageElements(() => parent.nativeElement(), this.locator);
+    }
+
+    async count(): Promise<number> {
+        const elements = await this.nativeElementList() as unknown as ElementArrayFinder;
+        return elements.count();
+    }
+
+    async first(): Promise<ProtractorPageElement> {
+        const elements = await this.nativeElementList() as unknown as ElementArrayFinder;
+        return this.asElement(elements.first());
+    }
+
+    async last(): Promise<ProtractorPageElement> {
+        const elements = await this.nativeElementList() as unknown as ElementArrayFinder;
+        return this.asElement(elements.last());
+    }
+
+    async get(index: number): Promise<ProtractorPageElement> {
+        const elements = await this.nativeElementList() as unknown as ElementArrayFinder;
+
+        if (! elements.get(index)) {
+            throw new LogicError(`There's no item at index ${ index }`);
+        }
+
+        return this.asElement(elements.get(index));
+    }
+
+    async map<O>(fn: (element: PageElement, index?: number, elements?: PageElements) => Promise<O> | O): Promise<O[]> {
+        const elements = await this.nativeElementList() as unknown as ElementArrayFinder;
+
+        return elements.map((element?: ElementFinder, i?: number) =>
+            fn(new ProtractorPageElement(this.context, _context => element), i, this)
+        );
+    }
+
+    filter(fn: (element: PageElement, index?: number) => Promise<boolean> | boolean): PageElements {
+        return new ProtractorPageElements(
+            this.context,
+            async (context: ProtractorNativeElementRoot): Promise<ElementArrayFinder> => {
+                const elements = await this.locator(context) as unknown as ElementArrayFinder;
+
+                const result = elements.filter(async (nativeElement: ElementFinder, index: number) => {
+                    const element = new ProtractorPageElement(this.context, _context => nativeElement);
+                    const result = await fn(element, index);
+                    return result;
+                });
+
+                return promisedWebElement<ElementArrayFinder>(result);
+            }
+        );
+    }
+
+    async forEach(fn: (element: PageElement, index?: number, elements?: PageElements) => Promise<void> | void): Promise<void> {
+        const elements = await this.nativeElementList() as unknown as ElementArrayFinder
+
+        return elements.each((element: ElementFinder, index: number) => {
+            return fn(new ProtractorPageElement(this.context, _context => element), index, this);
+        });
+    }
+
+    private asElement(elementFinder: ElementFinder): PageElement {
+        return new ProtractorPageElement(this.context, _context => elementFinder);
+    }
+}

package/src/screenplay/models/index.ts

@@ -0,0 +1,7 @@
+export * from './ProtractorCookie';
+export * from './ProtractorModalDialog';
+export * from './ProtractorNativeElementRoot';
+export * from './ProtractorPage';
+export * from './ProtractorPageElement';
+export * from './ProtractorPageElements';
+

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);
     });

package/src/screenplay/promisedWebElement.ts

@@ -0,0 +1,28 @@
+import { WebElement } from 'protractor';
+
+/**
+ * @desc
+ *  Wraps Webdriver then-ables into a Node-native promise to allow for correct promise chaining.
+ *
+ * @private
+ *
+ * @param promiseLike
+ * @returns {Promise<T>}
+ */
+export function promisedWebElement<T extends WebElement>(promiseLike: PromiseLike<T> | T): Promise<T> {
+    if (promiseLike instanceof Promise) {
+        return promiseLike;
+    }
+
+    return Promise.resolve(new Proxy(promiseLike, {
+        has: (target, property) =>
+            property !== 'then',
+        ownKeys: (target) =>
+            Reflect.ownKeys(target)
+                .filter(property => property !== 'then'),
+        get: (target, property, receiver) =>
+            (property in receiver)
+                ? target[property]
+                : undefined,
+    }));
+}

package/src/screenplay/questions/ProtractorParam.ts

@@ -1,8 +1,8 @@
 /* eslint-disable unicorn/prevent-abbreviations */
-import { Answerable, AnswersQuestions, Question, UsesAbilities } from '@serenity-js/core';
+import { Adapter, Answerable, Question } from '@serenity-js/core';
 import { formatted } from '@serenity-js/core/lib/io';
 
-import { BrowseTheWeb } from '../abilities';
+import { BrowseTheWebWithProtractor } from '../abilities';
 
 /**
  * @desc
@@ -18,28 +18,40 @@ import { BrowseTheWeb } from '../abilities';
  *        }
  *    }
  *    // ...
- * }
+ *  }
  *
  * @example <caption>Overriding configuration parameter via the command line</caption>
  *  protractor ./protractor.conf.js --params.login.username="bob@example.org"
  *
- * @example <caption>Using in a test scenario</caption>
+ * @example <caption>Using as Screenplay Adapter</caption>
  *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Enter, ProtractorParam } from '@serenity-js/protractor';
+ *  import { BrowseTheWebWithProtractor, ProtractorParam } from '@serenity-js/protractor';
+ *  import { Enter } from '@serenity-js/web';
  *  import { protractor } from 'protractor';
  *
  *  actorCalled('Jane')
- *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .whoCan( BrowseTheWebWithProtractor.using(protractor.browser))
  *      .attemptsTo(
- *          Enter.theValue(ProtractorParam.called('login.username').into(Form.exampleInput),
+ *          Enter.theValue(ProtractorParam.called('login').username).into(Form.exampleInput),
  *      );
  *
- * @extends {@serenity-js/core/lib/screenplay~Question<Promise<T>>}
+ * @example <caption>Specifying path to param as string</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWebWithProtractor, ProtractorParam } from '@serenity-js/protractor';
+ *  import { Enter } from '@serenity-js/web';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Jane')
+ *      .whoCan( BrowseTheWebWithProtractor.using(protractor.browser))
+ *      .attemptsTo(
+ *          Enter.theValue(ProtractorParam.called('login.username')).into(Form.exampleInput),
+ *      );
  *
- * @see {@link BrowseTheWeb#param}
+ * @extends {@serenity-js/core/lib/screenplay~Question<Promise<T>>}
+ *g
+ * @see {@link BrowseTheWebWithProtractor#param}
  */
-export class ProtractorParam<T = any>
-    extends Question<Promise<T>>
+export class ProtractorParam
 {
     /**
      * @desc
@@ -47,33 +59,12 @@ export class ProtractorParam<T = any>
      *  i.e. `login.username`
      *
      * @param {@serenity-js/core/lib/screenplay~Answerable<string>} name
-     * @returns {ProtractorParam<R>}
-     */
-    static called<R>(name: Answerable<string>): ProtractorParam {
-        return new ProtractorParam<R>(name);
-    }
-
-    /**
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} name
-     */
-    constructor(private readonly name: Answerable<string>) {
-        super(formatted `the ${ name } param specified in Protractor config`);
-    }
-
-    /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  answer this {@link @serenity-js/core/lib/screenplay~Question}.
-     *
-     * @param {AnswersQuestions & UsesAbilities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @returns {Question<Promise<R>> & Adapter<R>}
      */
-    answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<T> {
-        return actor.answer(this.name)
-            .then(name => BrowseTheWeb.as(actor).param(name));
+    static called<R>(name: Answerable<string>): Question<Promise<R>> & Adapter<R> {
+        return Question.about<Promise<R>>(formatted `the ${ name } param specified in Protractor config`, actor => {
+            return actor.answer(name)
+                .then(name => BrowseTheWebWithProtractor.as(actor).param(name));
+        });
     }
 }

package/src/screenplay/questions/index.ts

@@ -1,14 +1 @@
-export * from './Attribute';
-export * from './Browser';
-export * from './Cookie';
-export * from './CSSClasses';
-export * from './LastScriptExecution';
-export * from './ModalDialog';
-export { Pick } from './Pick';
 export * from './ProtractorParam';
-export * from './Selected';
-export { Target } from './targets';
-export * from './text';
-export * from './Value';
-export * from './Website';
-export * from './Window';