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

package/src/screenplay/promised.ts

@@ -1,11 +1,10 @@
 /**
- * @desc
- *  Wraps Webdriver promise into a Node-native promise to allow for correct promise chaining.
+ * Wraps Webdriver promise-like objects into
+ * a Node-native promise to allow for correct promise chaining.
  *
  * @private
  *
  * @param promiseLike
- * @returns {Promise<T>}
  */
 export function promised<T>(promiseLike: PromiseLike<T>): Promise<T> {
     return new Promise((resolve, reject) => {

package/src/screenplay/questions/ProtractorParam.ts

@@ -1,70 +1,83 @@
 /* eslint-disable unicorn/prevent-abbreviations */
-import { Answerable, Question, QuestionAdapter } from '@serenity-js/core';
-import { formatted } from '@serenity-js/core/lib/io';
+import { Answerable, d, Question, QuestionAdapter } from '@serenity-js/core';
 
 import { BrowseTheWebWithProtractor } from '../abilities';
 
 /**
- * @desc
- *  Returns a Protractor configuration parameter specified in `protractor.conf.js`.
- *  Note that Protractor configuration parameters can be overridden via the command line.
+ * Returns a Protractor configuration parameter specified in `protractor.conf.js`
+ * and identified by name. Protractor configuration parameters can be overridden via the command line.
  *
- * @example <caption>protractor.conf.js</caption>
- *  exports.config = {
- *    params: {
- *        login: {
- *            username: 'jane@example.org'
- *            password: process.env.PASSWORD
- *        }
- *    }
- *    // ...
- *  }
+ * **Warning:** this question is Protractor-specific, so using it in your tests
+ * will reduce their portability across test integration tools.
  *
- * @example <caption>Overriding configuration parameter via the command line</caption>
- *  protractor ./protractor.conf.js --params.login.username="bob@example.org"
+ * ```js
+ * // protractor.conf.js
+ * exports.config = {
+ *   params: {
+ *     login: {
+ *       username: 'jane@example.org'
+ *       password: process.env.PASSWORD
+ *     }
+ *   }
+ *   // ...
+ * }
+ * ```
  *
- * @example <caption>Using as Screenplay Adapter</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWebWithProtractor, ProtractorParam } from '@serenity-js/protractor';
- *  import { Enter } from '@serenity-js/web';
- *  import { protractor } from 'protractor';
+ * ## Overriding configuration parameter using the command line
  *
- *  actorCalled('Jane')
- *      .whoCan( BrowseTheWebWithProtractor.using(protractor.browser))
- *      .attemptsTo(
- *          Enter.theValue(ProtractorParam.called('login').username).into(Form.exampleInput),
- *      );
+ * ```shell
+ * npx protractor ./protractor.conf.js --params.login.username="bob@example.org"
+ * ```
  *
- * @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';
+ * ## Using as `QuestionAdapter`
  *
- *  actorCalled('Jane')
- *      .whoCan( BrowseTheWebWithProtractor.using(protractor.browser))
- *      .attemptsTo(
- *          Enter.theValue(ProtractorParam.called('login.username')).into(Form.exampleInput),
- *      );
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithProtractor, ProtractorParam } from '@serenity-js/protractor'
+ * import { Enter } from '@serenity-js/web'
+ * import { protractor } from 'protractor'
  *
- * @extends {@serenity-js/core/lib/screenplay~Question<Promise<T>>}
- *g
- * @see {@link BrowseTheWebWithProtractor#param}
+ * await actorCalled('Jane')
+ *   .whoCan( BrowseTheWebWithProtractor.using(protractor.browser))
+ *   .attemptsTo(
+ *     Enter.theValue(ProtractorParam.called('login').username).into(Form.exampleInput),
+ *   )
+ * ```
+ *
+ * ## Specifying path to param as string
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { BrowseTheWebWithProtractor, ProtractorParam } from '@serenity-js/protractor'
+ * import { Enter } from '@serenity-js/web'
+ * import { protractor } from 'protractor
+ *
+ * await actorCalled('Jane')
+ *   .whoCan(BrowseTheWebWithProtractor.using(protractor.browser))
+ *   .attemptsTo(
+ *     Enter.theValue(ProtractorParam.called('login.username')).into(Form.exampleInput),
+ *   );
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink BrowseTheWebWithProtractor.param}
+ *
+ * @group Questions
  */
 export class ProtractorParam
 {
     /**
-     * @desc
-     *  Name of the parameter to retrieve. This could also be a dot-delimited path,
-     *  i.e. `login.username`
+     * Name of the parameter to retrieve. This could also be a dot-delimited path,
+     * e.g. `login.username`
      *
-     * @param {@serenity-js/core/lib/screenplay~Answerable<string>} name
-     * @returns {Question<Promise<R>> & Adapter<R>}
+     * @param name
      */
-    static called<R>(name: Answerable<string>): QuestionAdapter<R> {
-        return Question.about<R>(formatted `the ${ name } param specified in Protractor config`, actor => {
-            return actor.answer(name)
-                .then(name => (actor.abilityTo(BrowseTheWebWithProtractor) as BrowseTheWebWithProtractor).param(name));
+    static called<Return_Type>(name: Answerable<string>): QuestionAdapter<Return_Type> {
+        return Question.about<Return_Type>(d`the ${ name } param specified in Protractor config`, async actor => {
+            const paramName = await actor.answer(name);
+            const browseTheWeb = BrowseTheWebWithProtractor.as(actor) as BrowseTheWebWithProtractor;
+
+            return browseTheWeb.param<Return_Type>(paramName);
         });
     }
 }

package/src/screenplay/unpromisedWebElement.ts

@@ -1,13 +1,14 @@
 import { WebElement } from 'protractor';
 
 /**
- * @desc
- *  Wraps Webdriver then-ables into a Node-native promise to allow for correct promise chaining.
+ * Under [certain conditions](https://github.com/angular/protractor/blob/4bc80d1a459542d883ea9200e4e1f48d265d0fda/lib/element.ts#L797),
+ * Protractor `WebElement` implements a `then()` method, and under others it doesn't.
  *
- * @private
+ * This design makes it look like a "thenable" in some scenarios, but like a non-thenable in others.
+ *
+ * This function wraps `WebElement` in a `Proxy` object that ensures the wrapped element is always non-thenable.
  *
  * @param promiseLike
- * @returns {Promise<T>}
  */
 export function unpromisedWebElement<T extends WebElement>(promiseLike: T): T {
 

package/tsconfig.build.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src",
+    "lib": [
+      "es2019",
+      "dom"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/lib/screenplay/models/ProtractorModalDialog.d.ts

@@ -1,11 +0,0 @@
-import { ModalDialog } from '@serenity-js/web';
-import { ProtractorBrowser } from 'protractor';
-export declare class ProtractorModalDialog extends ModalDialog {
-    private readonly browser;
-    constructor(browser: ProtractorBrowser);
-    accept(): Promise<void>;
-    dismiss(): Promise<void>;
-    text(): Promise<string>;
-    enterValue(value: string | number | (string | number)[]): Promise<void>;
-    isPresent(): Promise<boolean>;
-}

package/lib/screenplay/models/ProtractorModalDialog.js

@@ -1,43 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProtractorModalDialog = void 0;
-const web_1 = require("@serenity-js/web");
-const selenium_webdriver_1 = require("selenium-webdriver");
-const promised_1 = require("../promised");
-class ProtractorModalDialog extends web_1.ModalDialog {
-    constructor(browser) {
-        super();
-        this.browser = browser;
-    }
-    accept() {
-        return (0, promised_1.promised)(this.browser.switchTo().alert().accept());
-    }
-    dismiss() {
-        return (0, promised_1.promised)(this.browser.switchTo().alert().dismiss());
-    }
-    text() {
-        return (0, promised_1.promised)(this.browser.switchTo().alert().getText());
-    }
-    async enterValue(value) {
-        const text = [].concat(value).join('');
-        await (0, promised_1.promised)(this.browser.switchTo().alert().sendKeys(text));
-        await (0, promised_1.promised)(this.browser.switchTo().alert().accept());
-    }
-    // todo: remove in favour of auto-wait in the above methods
-    isPresent() {
-        return (0, promised_1.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 === selenium_webdriver_1.error.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 === selenium_webdriver_1.error.WebDriverError.name
-                        && error.message === `can't convert null to object`));
-        });
-    }
-}
-exports.ProtractorModalDialog = ProtractorModalDialog;
-//# sourceMappingURL=ProtractorModalDialog.js.map

package/lib/screenplay/models/ProtractorModalDialog.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ProtractorModalDialog.js","sourceRoot":"","sources":["../../../src/screenplay/models/ProtractorModalDialog.ts"],"names":[],"mappings":";;;AAAA,0CAA+C;AAE/C,2DAAqD;AAErD,0CAAuC;AAEvC,MAAa,qBAAsB,SAAQ,iBAAW;IAElD,YAA6B,OAA0B;QACnD,KAAK,EAAE,CAAC;QADiB,YAAO,GAAP,OAAO,CAAmB;IAEvD,CAAC;IAED,MAAM;QACF,OAAO,IAAA,mBAAQ,EAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO;QACH,OAAO,IAAA,mBAAQ,EAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI;QACA,OAAO,IAAA,mBAAQ,EAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAA4C;QACzD,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvC,MAAM,IAAA,mBAAQ,EAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/D,MAAM,IAAA,mBAAQ,EAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,2DAA2D;IAC3D,SAAS;QACL,OAAO,IAAA,mBAAQ,EAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC;aAC3C,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE;YAEtB,YAAY;YACZ,4IAA4I;YAC5I,OAAO,KAAK,YAAY,KAAK;gBACzB,CAAE,CACE,KAAK,CAAC,IAAI,KAAK,0BAAM,CAAC,gBAAgB,CAAC,IAAI;oBAC3C,uEAAuE;oBACvE,oCAAoC;oBACpC,mDAAmD;uBAChD,CAAC,KAAK,CAAC,IAAI,KAAK,0BAAM,CAAC,cAAc,CAAC,IAAI;2BACtC,KAAK,CAAC,OAAO,KAAK,8BAA8B,CAAC,CAC3D,CAAC;QACV,CAAC,CAAC,CAAC;IACX,CAAC;CACJ;AA1CD,sDA0CC"}

package/lib/screenplay/models/locators/ProtractorNativeElementRoot.d.ts

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

package/lib/screenplay/models/locators/ProtractorNativeElementRoot.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ProtractorNativeElementRoot.js.map

package/lib/screenplay/models/locators/ProtractorNativeElementRoot.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ProtractorNativeElementRoot.js","sourceRoot":"","sources":["../../../../src/screenplay/models/locators/ProtractorNativeElementRoot.ts"],"names":[],"mappings":""}

package/src/screenplay/models/ProtractorModalDialog.ts

@@ -1,49 +0,0 @@
-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/locators/ProtractorNativeElementRoot.ts

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

package/tsconfig.eslint.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig",
-  "include": [
-    "src/**/*.ts",
-    "spec/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}