codeceptjs 2.3.4 → 2.4.1

package/lib/helper/WebDriver.js

@@ -1,7 +1,9 @@
 let webdriverio;
+
 const assert = require('assert');
 const path = require('path');
 const requireg = require('requireg');
+
 const Helper = require('../helper');
 const stringIncludes = require('../assert/include').includes;
 const { urlEquals, equals } = require('../assert/equal');
@@ -39,6 +41,7 @@ const webRoot = 'body';
  * This helper should be configured in codecept.json or codecept.conf.js
  *
  * * `url`: base url of website to be tested.
+ * * `basicAuth`: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
  * * `browser`: browser in which to perform testing.
  * * `host`: (optional, default: localhost) - WebDriver host to connect.
  * * `port`: (optional, default: 4444) - WebDriver port to connect.
@@ -78,6 +81,25 @@ const webRoot = 'body';
  * }
  * ```
  *
+ * Example with basic authentication
+ * ```js
+ * {
+ *    helpers: {
+ *      WebDriver : {
+ *        smartWait: 5000,
+ *        browser: "chrome",
+ *        basicAuth: {username: 'username', password: 'password'},
+ *        restart: false,
+ *        windowSize: "maximize",
+ *        timeouts: {
+ *          "script": 60000,
+ *          "page load": 10000
+ *        }
+ *      }
+ *    }
+ * }
+ * ```
+ *
  * Additional configuration params can be used from [webdriverio
  * website](http://webdriver.io/guide/getstarted/configuration.html).
  *
@@ -91,7 +113,7 @@ const webRoot = 'body';
  *        browser: "chrome",
  *        desiredCapabilities: {
  *          chromeOptions: {
- *            args: [ "--headless", "--disable-gpu", "--window-size=800,600" ]
+ *            args: [ "--headless", "--disable-gpu", "--no-sandbox" ]
  *          }
  *        }
  *      }
@@ -613,7 +635,7 @@ class WebDriver extends Helper {
    * ```
    *
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locate(locator, smartWait = false) {
     if (require('../store').debugMode) smartWait = false;
@@ -644,7 +666,7 @@ class WebDriver extends Helper {
    * this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').then // ...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locateCheckable(locator) {
     return findCheckable.call(this, locator, this.$$.bind(this)).then(res => res);
@@ -657,7 +679,7 @@ class WebDriver extends Helper {
    * this.helpers['WebDriver']._locateClickable('Next page').then // ...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locateClickable(locator) {
     return findClickable.call(this, locator, this.$$.bind(this)).then(res => res);
@@ -670,7 +692,7 @@ class WebDriver extends Helper {
    * this.helpers['WebDriver']._locateFields('Your email').then // ...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locateFields(locator) {
     return findFields.call(this, locator).then(res => res);
@@ -686,7 +708,7 @@ class WebDriver extends Helper {
    * I.defineTimeout({ implicit: 10000, pageLoad: 10000, script: 5000 });
    * ```
    *
-   * @param timeouts WebDriver timeouts object.
+   * @param {WebdriverIO.Timeouts} timeouts WebDriver timeouts object.
    */
   defineTimeout(timeouts) {
     return this._defineBrowserTimeout(this.browser, timeouts);
@@ -701,6 +723,14 @@ class WebDriver extends Helper {
    *
    */
   amOnPage(url) {
+    let split_url;
+    if (this.config.basicAuth) {
+      if (url.startsWith('/')) {
+        url = this.config.url + url;
+      }
+      split_url = url.split('//');
+      url = `${split_url[0]}//${this.config.basicAuth.username}:${this.config.basicAuth.password}@${split_url[1]}`;
+    }
     return this.browser.url(url);
   }
 
@@ -983,7 +1013,7 @@ class WebDriver extends Helper {
    * I.seeTitleEquals('Test title.');
    * ```
    *
-   * @param text value to check.
+   * @param {string} text value to check.
    */
   async seeTitleEquals(text) {
     const title = await this.browser.getTitle();
@@ -1019,14 +1049,7 @@ class WebDriver extends Helper {
   }
 
   /**
-   * Checks that text is equal to provided one.
-   *
-   * ```js
-   * I.seeTextEquals('text', 'h1');
-   * ```
-   *
-   * @param text element value to check.
-   * @param context (optional) element located by CSS|XPath|strict locator.
+   * {{> seeTextEquals }}
    */
   async seeTextEquals(text, context = null) {
     return proceedSee.call(this, 'assert', text, context, true);
@@ -1140,6 +1163,7 @@ class WebDriver extends Helper {
    * let logs = await I.grabBrowserLogs();
    * console.log(JSON.stringify(logs))
    * ```
+   * @returns {Promise<string|undefined>}
    */
   async grabBrowserLogs() {
     if (this.browser.isW3C) {
@@ -1312,6 +1336,17 @@ class WebDriver extends Helper {
     return this.browser.executeAsync.apply(this.browser, arguments);
   }
 
+  /**
+   * {{> scrollIntoView }}
+   *
+   */
+  async scrollIntoView(locator, scrollIntoViewOptions) {
+    const res = await this._locate(withStrictLocator(locator), true);
+    assertElementExists(res);
+    const elem = usingFirstElement(res);
+    return elem.scrollIntoView(scrollIntoViewOptions);
+  }
+
   /**
    * {{> scrollTo }}
    *
@@ -1464,7 +1499,7 @@ class WebDriver extends Helper {
    * Checks that the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`, contains the
    * given string.
    *
-   * @param text value to check.
+   * @param {string} text value to check.
    */
   async seeInPopup(text) {
     return this.browser.getAlertText().then((res) => {
@@ -1737,6 +1772,21 @@ class WebDriver extends Helper {
     }, aSec * 1000, `element (${locator}) still not present on page after ${aSec} sec`);
   }
 
+  /**
+   * {{> waitForClickable }}
+   */
+  async waitForClickable(locator, waitTimeout) {
+    waitTimeout = waitTimeout || this.options.waitForTimeout;
+    let res = await this._locate(locator);
+    res = usingFirstElement(res);
+    assertElementExists(res, locator);
+
+    return res.waitForClickable({
+      timeout: waitTimeout,
+      timeoutMsg: `element ${res.selector} still not clickable after ${waitTimeout} sec`,
+    });
+  }
+
   async waitUntilExists(locator, sec = null) {
     console.log(`waitUntilExists deprecated:
     * use 'waitForElement' to wait for element to be attached
@@ -1940,9 +1990,11 @@ class WebDriver extends Helper {
     this.browser.isInsideFrame = true;
     if (Number.isInteger(locator)) {
       return this.browser.switchToFrame(locator);
-    } else if (!locator) {
+    }
+    if (!locator) {
       return this.browser.switchToFrame(null);
     }
+
     let res = await this._locate(locator, true);
     assertElementExists(res, locator);
     res = usingFirstElement(res);
@@ -1957,8 +2009,8 @@ class WebDriver extends Helper {
    * I.switchToNextTab(2);
    * ```
    *
-   * @param num (optional) number of tabs to switch forward, default: 1.
-   * @param sec (optional) time in seconds to wait.
+   * @param {number} [num] (optional) number of tabs to switch forward, default: 1.
+   * @param {number | null} [sec] (optional) time in seconds to wait.
    */
   async switchToNextTab(num = 1, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -1983,8 +2035,8 @@ class WebDriver extends Helper {
    * I.switchToPreviousTab(2);
    * ```
    *
-   * @param num (optional) number of tabs to switch backward, default: 1.
-   * @param sec (optional) time in seconds to wait.
+   * @param {number} [num] (optional) number of tabs to switch backward, default: 1.
+   * @param {number?} [sec] (optional) time in seconds to wait.
    */
   async switchToPreviousTab(num = 1, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -2118,7 +2170,10 @@ class WebDriver extends Helper {
     assertElementExists(res, locator);
     const el = usingFirstElement(res);
 
-    const rect = Object.assign({}, await el.getLocation(), await el.getSize());
+    const rect = {
+      ...await el.getLocation(),
+      ...await el.getSize(),
+    };
     if (prop) return rect[prop];
     return rect;
   }
@@ -2173,58 +2228,57 @@ async function proceedSee(assertType, text, context, strict = false) {
   return stringIncludes(description)[assertType](text, selected);
 }
 
-// Mimic Array.forEach() API, but with an async callback function.
-// Execute each callback on each array item serially. Useful when using WebDriver API.
-//
-// Added due because of problem with chrome driver when too many requests
-// are made simultaneously. https://bugs.chromium.org/p/chromedriver/issues/detail?id=2152#c9
-//
-// @param {object[]} array Input array items to iterate over
-// @param {function} callback Async function to excute on each array item
-// @return Array
-async function forEachAsync(array, callback, option = {}) {
+/**
+ * Mimic Array.forEach() API, but with an async callback function.
+ * Execute each callback on each array item serially. Useful when using WebDriver API.
+ *
+ * Added due because of problem with chrome driver when too many requests
+ * are made simultaneously. https://bugs.chromium.org/p/chromedriver/issues/detail?id=2152#c9
+ * @private
+ * @param {Array} array Input array items to iterate over.
+ * @param {Function} callback - Async function to excute on each array item.
+ * @param {object} [options] - Configurable options.
+ * @param {boolean} [options.expandArrayResults=true] - Flag to flat one dimension array results.
+ * @return {Promise<Array>} - Array of values.
+ */
+async function forEachAsync(array, callback, options = { expandArrayResults: true }) {
   const {
     expandArrayResults = true,
-  } = option;
+  } = options;
   const inputArray = Array.isArray(array) ? array : [array];
   const values = [];
   for (let index = 0; index < inputArray.length; index++) {
-    let res;
-    try {
-      res = await callback(inputArray[index], index, inputArray);
-      if (Array.isArray(res) && expandArrayResults) {
-        res.forEach(val => values.push(val));
-      } else if (res) {
-        values.push(res);
-      }
-    } catch (err) {
-      throw err;
+    const res = await callback(inputArray[index], index, inputArray);
+
+    if (Array.isArray(res) && expandArrayResults) {
+      res.forEach(val => values.push(val));
+    } else if (res) {
+      values.push(res);
     }
   }
   return values;
 }
 
-//  Mimic Array.filter() API, but with an async callback function.
-//  Execute each callback on each array item serially. Useful when using WebDriver API.
-//  Added due because of problem with chrome driver when too many requests
-//  are made simultaneously. https://bugs.chromium.org/p/chromedriver/issues/detail?id=2152#c9
-//  @param {object[]} array Input array items to iterate over
-//  @param {function} callback Async functin to excute on each array item
-//  @param {object} option Additional options. 'extractValue' will extract the .value object from a WebdriverIO
-//
+/**
+ * Mimic Array.filter() API, but with an async callback function.
+ * Execute each callback on each array item serially. Useful when using WebDriver API.
+ *
+ * Added due because of problem with chrome driver when too many requests
+ * are made simultaneously. https://bugs.chromium.org/p/chromedriver/issues/detail?id=2152#c9
+ * @private
+ * @param {Array} array - Input array items to iterate over.
+ * @param {Function} callback - Async functin to excute on each array item.
+ * @return {Promise<Array>} - Array of values.
+ */
 async function filterAsync(array, callback) {
   const inputArray = Array.isArray(array) ? array : [array];
   const values = [];
   for (let index = 0; index < inputArray.length; index++) {
-    try {
-      const res = await callback(inputArray[index], index, inputArray);
-      const value = Array.isArray(res) ? res[0] : res;
+    const res = await callback(inputArray[index], index, inputArray);
+    const value = Array.isArray(res) ? res[0] : res;
 
-      if (value) {
-        values.push(inputArray[index]);
-      }
-    } catch (err) {
-      throw err;
+    if (value) {
+      values.push(inputArray[index]);
     }
   }
   return values;

package/lib/helper/WebDriverIO.js

@@ -1,5 +1,9 @@
 let webdriverio;
+
+const assert = require('assert');
+const path = require('path');
 const requireg = require('requireg');
+
 const Helper = require('../helper');
 const stringIncludes = require('../assert/include').includes;
 const { urlEquals, equals } = require('../assert/equal');
@@ -21,8 +25,6 @@ const {
 const ElementNotFound = require('./errors/ElementNotFound');
 const ConnectionRefused = require('./errors/ConnectionRefused');
 
-const assert = require('assert');
-const path = require('path');
 
 const webRoot = 'body';
 const Locator = require('../locator');
@@ -92,7 +94,7 @@ let withinStore = {};
  *        "browser": "chrome",
  *        "desiredCapabilities": {
  *          "chromeOptions": {
- *            "args": [ "--headless", "--disable-gpu", "--window-size=800,600" ]
+ *            "args": [ "--headless", "--disable-gpu", "--no-sandbox" ]
  *          }
  *        }
  *      }
@@ -446,7 +448,7 @@ class WebDriverIO extends Helper {
    * this.helpers['WebDriverIO']._locate({name: 'password'}).then //...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locate(locator, smartWait = false) {
     if (!this.options.smartWait || !smartWait) return this.browser.elements(withStrictLocator.call(this, locator));
@@ -465,7 +467,7 @@ class WebDriverIO extends Helper {
    * this.helpers['WebDriverIO']._locateCheckable('I agree with terms and conditions').then // ...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locateCheckable(locator) {
     return findCheckable.call(this, locator, this.browser.elements.bind(this)).then(res => res.value);
@@ -478,7 +480,7 @@ class WebDriverIO extends Helper {
    * this.helpers['WebDriverIO']._locateClickable('Next page').then // ...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locateClickable(locator) {
     return findClickable.call(this, locator, this.browser.elements.bind(this)).then(res => res.value);
@@ -491,7 +493,7 @@ class WebDriverIO extends Helper {
    * this.helpers['WebDriverIO']._locateFields('Your email').then // ...
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    */
   async _locateFields(locator) {
     return findFields.call(this, locator).then(res => res.value);
@@ -507,7 +509,7 @@ class WebDriverIO extends Helper {
    * I.defineTimeout({ implicit: 10000, pageLoad: 10000, script: 5000 });
    * ```
    *
-   * @param timeouts WebDriver timeouts object.
+   * @param {WebdriverIO.Timeouts}  timeouts WebDriver timeouts object.
    */
   async defineTimeout(timeouts) {
     try {
@@ -780,7 +782,7 @@ class WebDriverIO extends Helper {
    * I.seeTitleEquals('Test title.');
    * ```
    *
-   * @param text value to check.
+   * @param {string} text value to check.
    */
   async seeTitleEquals(text) {
     const title = await this.browser.getTitle();
@@ -821,8 +823,8 @@ class WebDriverIO extends Helper {
    * I.seeTextEquals('text', 'h1');
    * ```
    *
-   * @param text element value to check.
-   * @param context (optional) element located by CSS|XPath|strict locator.
+   * @param {string} text element value to check.
+   * @param {CodeceptJS.LocatorOrString?} [context] (optional) element located by CSS|XPath|strict locator.
    */
   async seeTextEquals(text, context = null) {
     return proceedSee.call(this, 'assert', text, context, true);
@@ -974,8 +976,8 @@ class WebDriverIO extends Helper {
    * I.seeNumberOfElements('#submitBtn', 1);
    * ```
    *
-   * @param locator element located by CSS|XPath|strict locator.
-   * @param num number of elements.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [num] number of elements.
    */
   async seeNumberOfElements(locator, num) {
     const res = await this._locate(withStrictLocator.call(this, locator));
@@ -1127,9 +1129,9 @@ class WebDriverIO extends Helper {
    * I.scrollTo('#submit', 5, 5);
    * ```
    *
-   * @param locator located by CSS|XPath|strict locator.
-   * @param offsetX (optional) X-axis offset.
-   * @param offsetY (optional) Y-axis offset.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {number} [offsetX=0] (optional) X-axis offset.
+   * @param {number} [offsetY=0] (optional) Y-axis offset.
    */
 
   /**
@@ -1165,7 +1167,7 @@ class WebDriverIO extends Helper {
   }
 
   /**
-   * {{> moveCursorTo}}
+   * {{> moveCursorTo }}
    * Appium: support only web testing
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
@@ -1239,7 +1241,7 @@ class WebDriverIO extends Helper {
   }
 
   /**
-   * {{> clearCookie}}
+   * {{> clearCookie }}
    * Appium: support only web testing
    */
   async clearCookie(cookie) {
@@ -1247,7 +1249,7 @@ class WebDriverIO extends Helper {
   }
 
   /**
-   * {{> seeCookie}}
+   * {{> seeCookie }}
    * Appium: support only web testing
    */
   async seeCookie(name) {
@@ -1256,7 +1258,7 @@ class WebDriverIO extends Helper {
   }
 
   /**
-   * {{> dontSeeCookie}}
+   * {{> dontSeeCookie }}
    * Appium: support only web testing
    */
   async dontSeeCookie(name) {
@@ -1265,7 +1267,7 @@ class WebDriverIO extends Helper {
   }
 
   /**
-   * {{> grabCookie}}
+   * {{> grabCookie }}
    * Appium: support only web testing
    */
   async grabCookie(name) {
@@ -1301,7 +1303,7 @@ class WebDriverIO extends Helper {
    * Checks that the active JavaScript popup, as created by `window.alert|window.confirm|window.prompt`, contains the
    * given string. Appium: support only web testing
    *
-   * @param text value to check.
+   * @param {string} text value to check.
    */
   async seeInPopup(text) {
     return this.browser.alertText().then((res) => {
@@ -1325,17 +1327,7 @@ class WebDriverIO extends Helper {
   }
 
   /**
-   * {{> pressKey }}
-   * {{> _keys }}
-   *
-   * To make combinations with modifier and mouse clicks (like Ctrl+Click) press a modifier, click, then release it.
-   * Appium: support, but clear field before pressing in apps:
-   *
-   * ```js
-   * I.pressKey('Control');
-   * I.click('#someelement');
-   * I.pressKey('Control');
-   * ```
+   * {{> pressKeyWithKeyNormalization }}
    */
   async pressKey(key) {
     let modifier;
@@ -1661,7 +1653,6 @@ class WebDriverIO extends Helper {
 
   /**
    * {{> waitUntil }}
-   * @param interval (optional) time in seconds between condition checks.
    * * *Appium*: supported
    */
   async waitUntil(fn, sec = null, timeoutMsg = null, interval = null) {
@@ -1677,9 +1668,11 @@ class WebDriverIO extends Helper {
   async switchTo(locator) {
     if (Number.isInteger(locator)) {
       return this.browser.frame(locator);
-    } else if (!locator) {
+    }
+    if (!locator) {
       return this.browser.frame(null);
     }
+
     const res = await this._locate(withStrictLocator.call(this, locator), true);
     assertElementExists(res, locator);
     return this.browser.frame(res.value[0]);
@@ -1693,8 +1686,8 @@ class WebDriverIO extends Helper {
    * I.switchToNextTab(2);
    * ```
    *
-   * @param num (optional) number of tabs to switch forward, default: 1.
-   * @param sec (optional) time in seconds to wait.
+   * @param {number} [num=1] (optional) number of tabs to switch forward, default: 1.
+   * @param {?number} [sec=null] (optional) time in seconds to wait.
    */
   async switchToNextTab(num = 1, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -1719,8 +1712,8 @@ class WebDriverIO extends Helper {
    * I.switchToPreviousTab(2);
    * ```
    *
-   * @param num (optional) number of tabs to switch backward, default: 1.
-   * @param sec (optional) time in seconds to wait.
+   * @param {number} [num=1] (optional) number of tabs to switch backward, default: 1.
+   * @param {?number} [sec] (optional) time in seconds to wait.
    */
   async switchToPreviousTab(num = 1, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -1888,16 +1881,11 @@ async function forEachAsync(array, callback, option = {}) {
   const inputArray = Array.isArray(array) ? array : [array];
   const values = [];
   for (let index = 0; index < inputArray.length; index++) {
-    let res;
-    try {
-      res = await callback(inputArray[index], index, inputArray);
-      if (Array.isArray(res) && expandArrayResults) {
-        res.forEach(val => values.push(val));
-      } else if (res) {
-        values.push(res);
-      }
-    } catch (err) {
-      throw err;
+    const res = await callback(inputArray[index], index, inputArray);
+    if (Array.isArray(res) && expandArrayResults) {
+      res.forEach(val => values.push(val));
+    } else if (res) {
+      values.push(res);
     }
   }
   if (unifyResults) {
@@ -1921,15 +1909,11 @@ async function filterAsync(array, callback, option = {}) {
   const inputArray = Array.isArray(array) ? array : [array];
   const values = [];
   for (let index = 0; index < inputArray.length; index++) {
-    try {
-      const res = unify(await callback(inputArray[index], index, inputArray), { extractValue });
-      const value = Array.isArray(res) ? res[0] : res;
+    const res = unify(await callback(inputArray[index], index, inputArray), { extractValue });
+    const value = Array.isArray(res) ? res[0] : res;
 
-      if (value) {
-        values.push(inputArray[index]);
-      }
-    } catch (err) {
-      throw err;
+    if (value) {
+      values.push(inputArray[index]);
     }
   }
   return values;
@@ -1939,8 +1923,8 @@ async function filterAsync(array, callback, option = {}) {
 // Internal helper method to handle command results (similar behaviour as the unify function from WebDriverIO
 // except it does not resolve promises)
 //
-// @param  {object[]} items  list of items
-// @param  {object} [option]  extractValue: set to try to return the .value property of the input items
+// @param {object[]} items  list of items
+// @param {object} [option]  extractValue: set to try to return the .value property of the input items
 function unify(items, option = {}) {
   const { extractValue = false } = option;