codeceptjs 2.3.4 → 2.4.1

package/docs/build/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);
@@ -707,10 +729,17 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} url url path or global url.
-   * {--end--}
    *
    */
   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);
   }
 
@@ -737,9 +766,9 @@ class WebDriver extends Helper {
    * I.click({css: 'nav a.login'});
    * ```
    * 
-   * @param {string|object} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {string|object} context (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * 
    *
    * {{ react }}
    */
@@ -768,9 +797,9 @@ class WebDriver extends Helper {
    * I.doubleClick('.btn.edit');
    * ```
    * 
-   * @param {string|object} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {string|object} context (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * 
    *
    * {{ react }}
    */
@@ -800,9 +829,9 @@ class WebDriver extends Helper {
    * I.rightClick('Click me', '.context');
    * ```
    * 
-   * @param {string|object} locator clickable element located by CSS|XPath|strict locator.
-   * @param {string|object} context (optional, `null` by default) element located by CSS|XPath|strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator clickable element located by CSS|XPath|strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
+   * 
    *
    * {{ react }}
    */
@@ -844,9 +873,9 @@ class WebDriver extends Helper {
    * // or by strict locator
    * I.fillField({css: 'form#login input[name=username]'}, 'John');
    * ```
-   * @param {string|object} field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value text value to fill.
-   * {--end--}
+   * 
    * {{ react }}
    *
    */
@@ -864,9 +893,8 @@ class WebDriver extends Helper {
    * ```js
    * I.appendField('#myTextField', 'appended');
    * ```
-   * @param {string|object} field located by label|name|CSS|XPath|strict locator
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
    * @param {string} value text value to append.
-   * {--end--}
    * {{ react }}
    */
   async appendField(field, value) {
@@ -886,7 +914,6 @@ class WebDriver extends Helper {
    * I.clearField('#email');
    * ```
    * @param {string|object} editable field located by label|name|CSS|XPath|strict locator.
-   * {--end--}
    *
    */
   async clearField(field) {
@@ -916,9 +943,8 @@ class WebDriver extends Helper {
    * ```js
    * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
    * ```
-   * @param {string|object} select field located by label|name|CSS|XPath|strict locator.
-   * @param {string|array} option visible text or value of option.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
+   * @param {string|Array<*>} option visible text or value of option.
    */
   async selectOption(select, option) {
     const res = await findFields.call(this, select);
@@ -959,9 +985,8 @@ class WebDriver extends Helper {
    * I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
    * ```
    * 
-   * @param {string|object} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
    * @param {string} pathToFile local file path relative to codecept.json config file.
-   * {--end--}
    * Appium: not tested
    */
   async attachFile(locator, pathToFile) {
@@ -999,9 +1024,8 @@ class WebDriver extends Helper {
    * I.checkOption('I Agree to Terms and Conditions');
    * I.checkOption('agree', '//form');
    * ```
-   * @param {string|object} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {string} context (optional, `null` by default) element located by CSS | XPath | strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
    * Appium: not tested
    */
   async checkOption(field, context = null) {
@@ -1030,9 +1054,8 @@ class WebDriver extends Helper {
    * I.uncheckOption('I Agree to Terms and Conditions');
    * I.uncheckOption('agree', '//form');
    * ```
-   * @param {string|object} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {string} context (optional, `null` by default) element located by CSS | XPath | strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
    * Appium: not tested
    */
   async uncheckOption(field, context = null) {
@@ -1059,9 +1082,8 @@ class WebDriver extends Helper {
    * ```
    * If multiple elements found returns an array of texts.
    * 
-   * @param locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<string>} attribute value
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @returns {Promise<string|string[]>} attribute value
    *
    */
   async grabTextFrom(locator) {
@@ -1086,9 +1108,8 @@ class WebDriver extends Helper {
    * let postHTML = await I.grabHTMLFrom('#post');
    * ```
    * 
-   * @param locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} element located by CSS|XPath|strict locator.
    * @returns {Promise<string>} HTML code for an element
-   * {--end--}
    *
    */
   async grabHTMLFrom(locator) {
@@ -1109,9 +1130,8 @@ class WebDriver extends Helper {
    * ```js
    * let email = await I.grabValueFrom('input[name=email]');
    * ```
-   * @param {string|object} locator field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
    * @returns {Promise<string>} attribute value
-   * {--end--}
    *
    */
   async grabValueFrom(locator) {
@@ -1129,10 +1149,9 @@ class WebDriver extends Helper {
    * const value = await I.grabCssPropertyFrom('h3', 'font-weight');
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {string} cssProperty CSS property name.
    * @returns {Promise<string>} CSS value
-   * {--end--}
    */
   async grabCssPropertyFrom(locator, cssProperty) {
     const res = await this._locate(locator, true);
@@ -1148,10 +1167,9 @@ class WebDriver extends Helper {
    * ```js
    * let hint = await I.grabAttributeFrom('#tooltip', 'title');
    * ```
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {string} attr attribute name.
    * @returns {Promise<string>} attribute value
-   * {--end--}
    * Appium: can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
    */
   async grabAttributeFrom(locator, attr) {
@@ -1168,7 +1186,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} text text value to check.
-   * {--end--}
    *
    */
   async seeInTitle(text) {
@@ -1183,7 +1200,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();
@@ -1198,7 +1215,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} text value to check.
-   * {--end--}
    *
    */
   async dontSeeInTitle(text) {
@@ -1215,7 +1231,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @returns {Promise<string>} title
-   * {--end--}
    *
    */
   async grabTitle() {
@@ -1234,8 +1249,7 @@ class WebDriver extends Helper {
    * I.see('Register', {css: 'form.register'}); // use strict locator
    * ```
    * @param {string} text expected on page.
-   * @param {string|object} context (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
-   * {--end--}
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
    *
    * {{ react }}
    */
@@ -1245,13 +1259,13 @@ 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.
+   * 
+   * @param {string} text element value to check.
+   * @param {CodeceptJS.LocatorOrString?} [context=null]  element located by CSS|XPath|strict locator.
    */
   async seeTextEquals(text, context = null) {
     return proceedSee.call(this, 'assert', text, context, true);
@@ -1267,9 +1281,8 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} text which is not present.
-   * @param {string|object} context (optional) element located by CSS|XPath|strict locator in which to perfrom search.
-   *
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator in which to perfrom search.
+   * 
    *
    * {{ react }}
    */
@@ -1287,9 +1300,9 @@ class WebDriver extends Helper {
    * I.seeInField('form input[type=hidden]','hidden_value');
    * I.seeInField('#searchform input','Search');
    * ```
-   * @param {string|object} field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
-   * {--end--}
+   * 
    *
    */
   async seeInField(field, value) {
@@ -1305,9 +1318,8 @@ class WebDriver extends Helper {
    * I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
    * ```
    * 
-   * @param {string|object} field located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
    * @param {string} value value to check.
-   * {--end--}
    *
    */
   async dontSeeInField(field, value) {
@@ -1323,8 +1335,8 @@ class WebDriver extends Helper {
    * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
    * ```
    * 
-   * @param {string|object} field located by label|name|CSS|XPath|strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * 
    * Appium: not tested
    */
   async seeCheckboxIsChecked(field) {
@@ -1340,8 +1352,8 @@ class WebDriver extends Helper {
    * I.dontSeeCheckboxIsChecked('agree'); // located by name
    * ```
    * 
-   * @param {string|object} field located by label|name|CSS|XPath|strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
+   * 
    * Appium: not tested
    */
   async dontSeeCheckboxIsChecked(field) {
@@ -1355,8 +1367,7 @@ class WebDriver extends Helper {
    * ```js
    * I.seeElement('#modal');
    * ```
-   * @param {string|object} locator located by CSS|XPath|strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
    * {{ react }}
    *
    */
@@ -1374,8 +1385,7 @@ class WebDriver extends Helper {
    * I.dontSeeElement('.modal'); // modal is not shown
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|Strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
    * {{ react }}
    */
   async dontSeeElement(locator) {
@@ -1394,8 +1404,8 @@ class WebDriver extends Helper {
    * ```js
    * I.seeElementInDOM('#modal');
    * ```
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * 
    *
    */
   async seeElementInDOM(locator) {
@@ -1410,8 +1420,7 @@ class WebDriver extends Helper {
    * I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|Strict locator.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
    *
    */
   async dontSeeElementInDOM(locator) {
@@ -1426,7 +1435,6 @@ class WebDriver extends Helper {
    * I.seeInSource('<h1>Green eggs &amp; ham</h1>');
    * ```
    * @param {string} text value to check.
-   * {--end--}
    *
    */
   async seeInSource(text) {
@@ -1443,7 +1451,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @returns {Promise<string>} source code
-   * {--end--}
    *
    */
   async grabSource() {
@@ -1457,6 +1464,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) {
@@ -1476,7 +1484,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @returns {Promise<string>} current URL
-   * {--end--}
    */
   async grabCurrentUrl() {
     const res = await this.browser.getUrl();
@@ -1492,7 +1499,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} value to check.
-   * {--end--}
+   * 
    */
   async dontSeeInSource(text) {
     const source = await this.browser.getPageSource();
@@ -1508,9 +1515,9 @@ class WebDriver extends Helper {
    * I.seeNumberOfElements('#submitBtn', 1);
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {number} num number of elements.
-   * {--end--}
+   * 
    * {{ react }}
    */
   async seeNumberOfElements(locator, num) {
@@ -1526,9 +1533,9 @@ class WebDriver extends Helper {
    * I.seeNumberOfVisibleElements('.buttons', 3);
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {number} num number of elements.
-   * {--end--}
+   * 
    * {{ react }}
    */
   async seeNumberOfVisibleElements(locator, num) {
@@ -1543,9 +1550,8 @@ class WebDriver extends Helper {
    * I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
    * @param {object} cssProperties object with CSS properties and their values to check.
-   * {--end--}
    */
   async seeCssPropertiesOnElements(locator, cssProperties) {
     const res = await this._locate(locator);
@@ -1586,9 +1592,8 @@ class WebDriver extends Helper {
    * I.seeAttributesOnElements('//form', { method: "post"});
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
    * @param {object} attributes attributes and their values to check.
-   * {--end--}
    */
   async seeAttributesOnElements(locator, attributes) {
     const res = await this._locate(locator);
@@ -1621,9 +1626,8 @@ class WebDriver extends Helper {
    * let numOfElements = await I.grabNumberOfVisibleElements('p');
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
    * @returns {Promise<number>} number of visible elements
-   * {--end--}
    */
   async grabNumberOfVisibleElements(locator) {
     const res = await this._locate(locator);
@@ -1642,7 +1646,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} url a fragment to check
-   * {--end--}
    *
    */
   async seeInCurrentUrl(url) {
@@ -1654,7 +1657,6 @@ class WebDriver extends Helper {
    * Checks that current url does not contain a provided fragment.
    * 
    * @param {string} url value to check.
-   * {--end--}
    *
    */
   async dontSeeInCurrentUrl(url) {
@@ -1673,7 +1675,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} url value to check.
-   * {--end--}
    *
    */
   async seeCurrentUrlEquals(url) {
@@ -1691,7 +1692,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} url value to check.
-   * {--end--}
    *
    */
   async dontSeeCurrentUrlEquals(url) {
@@ -1724,8 +1724,9 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string|function} fn function to be executed in browser context.
-   * @param ...args args to be passed to function.
-   * {--end--}
+   * @param {...any} args to be passed to function.
+   * @return {Promise<any>}
+   * 
    *
    *
    * Wraps [execute](http://webdriver.io/api/protocol/execute.html) command.
@@ -1757,14 +1758,36 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string|function} fn function to be executed in browser context.
-   * @param ...args args to be passed to function.
-   * {--end--}
+   * @param {...any} args to be passed to function.
+   * @return {Promise<any>}
+   * 
    *
    */
   executeAsyncScript(fn) {
     return this.browser.executeAsync.apply(this.browser, arguments);
   }
 
+  /**
+   * Scroll element into viewport.
+   * 
+   * ```js
+   * I.scrollIntoView('#submit');
+   * I.scrollIntoView('#submit', true);
+   * I.scrollIntoView('#submit', { behavior: "smooth", block: "center", inline: "center" });
+   * ```
+   * 
+   * @param {string|object} locator located by CSS|XPath|strict locator.
+   * @param {boolean|object} alignToTop (optional) or scrollIntoViewOptions (optional), see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView.
+   * 
+   *
+   */
+  async scrollIntoView(locator, scrollIntoViewOptions) {
+    const res = await this._locate(withStrictLocator(locator), true);
+    assertElementExists(res);
+    const elem = usingFirstElement(res);
+    return elem.scrollIntoView(scrollIntoViewOptions);
+  }
+
   /**
    * Scrolls to element matched by locator.
    * Extra shift can be set with offsetX and offsetY options.
@@ -1774,10 +1797,9 @@ class WebDriver extends Helper {
    * I.scrollTo('#submit', 5, 5);
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|strict locator.
-   * @param {number} offsetX (optional, `0` by default) X-axis offset.
-   * @param {number} offsetY (optional, `0` by default) Y-axis offset.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
+   * @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
    *
    */
   async scrollTo(locator, offsetX = 0, offsetY = 0) {
@@ -1816,10 +1838,10 @@ class WebDriver extends Helper {
    * I.moveCursorTo('#submit', 5,5);
    * ```
    * 
-   * @param {string|object} locator located by CSS|XPath|strict locator.
-   * @param {number} offsetX (optional, `0` by default) X-axis offset.
-   * @param {number} offsetY (optional, `0` by default) Y-axis offset.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+   * @param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
+   * @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
+   * 
    *
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
@@ -1840,8 +1862,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} fileName file name to save.
-   * @param {boolean} fullPage (optional, `false` by default) flag to enable fullscreen screenshot mode.
-   * {--end--}
+   * @param {boolean} [fullPage=false] (optional, `false` by default) flag to enable fullscreen screenshot mode.
    *
    */
   async saveScreenshot(fileName, fullPage = false) {
@@ -1881,7 +1902,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {object} cookie a cookie object.
-   * {--end--}
    *
    *
    * Uses Selenium's JSON [cookie
@@ -1900,8 +1920,7 @@ class WebDriver extends Helper {
    * I.clearCookie('test');
    * ```
    * 
-   * @param {string} cookie (optional, `null` by default) cookie name
-   * {--end--}
+   * @param {?string} [cookie=null] (optional, `null` by default) cookie name
    *
    */
   async clearCookie(cookie) {
@@ -1916,7 +1935,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} name cookie name.
-   * {--end--}
+   * 
    *
    */
   async seeCookie(name) {
@@ -1932,7 +1951,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} name cookie name.
-   * {--end--}
    *
    */
   async dontSeeCookie(name) {
@@ -1943,16 +1961,15 @@ class WebDriver extends Helper {
   /**
    * Gets a cookie object by name.
    * If none provided gets all cookies.
-   * * Resumes test execution, so **should be used inside async with `await`** operator.
+   * Resumes test execution, so **should be used inside async with `await`** operator.
    * 
    * ```js
    * let cookie = await I.grabCookie('auth');
    * assert(cookie.value, '123456');
    * ```
    * 
-   * @param [name=null] cookie name.
+   * @param {?string} [name=null] cookie name.
    * @returns {Promise<string>} attribute value
-   * {--end--}
    *
    */
   async grabCookie(name) {
@@ -1991,7 +2008,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) => {
@@ -2029,7 +2046,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} key name of key to press down.
-   * {--end--}
+   * 
    */
   async pressKeyDown(key) {
     key = getNormalizedKey.call(this, key);
@@ -2058,7 +2075,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} key name of key to release.
-   * {--end--}
+   * 
    */
   async pressKeyUp(key) {
     key = getNormalizedKey.call(this, key);
@@ -2134,8 +2151,8 @@ class WebDriver extends Helper {
    * - `'Space'`
    * - `'Tab'`
    * 
-   * @param {string|array} key key or array of keys to press.
-   * {--end--}
+   * @param {string|string[]} key key or array of keys to press.
+   * 
    *
    * _Note:_ In case a text field or textarea is focused be aware that some browsers do not respect active modifier when combining modifier keys with other keys.
    */
@@ -2183,7 +2200,6 @@ class WebDriver extends Helper {
    * 
    * @param {number} width width in pixels or `maximize`.
    * @param {number} height height in pixels.
-   * {--end--}
    * Appium: not tested in web, in apps doesn't work
    */
   async resizeWindow(width, height) {
@@ -2220,7 +2236,6 @@ class WebDriver extends Helper {
    * 
    * @param {string|object} srcElement located by CSS|XPath|strict locator.
    * @param {string|object} destElement located by CSS|XPath|strict locator.
-   * {--end--}
    * Appium: not tested
    */
   async dragAndDrop(srcElement, destElement) {
@@ -2244,9 +2259,8 @@ class WebDriver extends Helper {
    * I.dragSlider('#slider', -70);
    * ```
    * 
-   * @param {string|object} locator located by label|name|CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator located by label|name|CSS|XPath|strict locator.
    * @param {number} offsetX position to drag.
-   * {--end--}
    */
   async dragSlider(locator, offsetX = 0) {
     const browser = this.browser;
@@ -2338,7 +2352,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {number} sec number of second to wait.
-   * {--end--}
    *
    */
   async wait(sec) {
@@ -2349,9 +2362,8 @@ class WebDriver extends Helper {
    * Waits for element to become enabled (by default waits for 1sec).
    * Element can be located by CSS or XPath.
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * @param sec (optional) time in seconds to wait, 1 by default.
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec=1] (optional) time in seconds to wait, 1 by default.
    *
    */
   async waitForEnabled(locator, sec = null) {
@@ -2378,9 +2390,8 @@ class WebDriver extends Helper {
    * I.waitForElement('.btn.continue', 5); // wait for 5 secs
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec] (optional, `1` by default) time in seconds to wait
    */
   async waitForElement(locator, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -2390,6 +2401,30 @@ class WebDriver extends Helper {
     }, aSec * 1000, `element (${locator}) still not present on page after ${aSec} sec`);
   }
 
+  /**
+   * Waits for element to be clickable (by default waits for 1sec).
+   * Element can be located by CSS or XPath.
+   * 
+   * ```js
+   * I.waitForClickable('.btn.continue');
+   * I.waitForClickable('.btn.continue', 5); // wait for 5 secs
+   * ```
+   * 
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec] (optional, `1` by default) time in seconds to wait
+   */
+  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
@@ -2406,8 +2441,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} urlPart value to check.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitInUrl(urlPart, sec = null) {
     const client = this.browser;
@@ -2436,8 +2470,7 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string} urlPart value to check.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitUrlEquals(urlPart, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -2470,9 +2503,8 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string }text to wait for.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * @param {string|object} context (optional) element located by CSS|XPath|strict locator.
-   * {--end--}
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
+   * @param {CodeceptJS.LocatorOrString} [context] (optional) element located by CSS|XPath|strict locator.
    *
    */
   async waitForText(text, sec = null, context = null) {
@@ -2501,8 +2533,7 @@ class WebDriver extends Helper {
    * 
    * @param {string|object} field input field.
    * @param {string }value expected value.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitForValue(field, value, sec = null) {
     const client = this.browser;
@@ -2529,9 +2560,8 @@ class WebDriver extends Helper {
    * I.waitForVisible('#popup');
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    *
    */
   async waitForVisible(locator, sec = null) {
@@ -2554,10 +2584,9 @@ class WebDriver extends Helper {
    * I.waitNumberOfVisibleElements('a', 3);
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
    * @param {number} num number of elements.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    */
   async waitNumberOfVisibleElements(locator, num, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
@@ -2579,9 +2608,8 @@ class WebDriver extends Helper {
    * I.waitForInvisible('#popup');
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    *
    */
   async waitForInvisible(locator, sec = null) {
@@ -2602,9 +2630,8 @@ class WebDriver extends Helper {
    * I.waitToHide('#popup');
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    *
    */
   async waitToHide(locator, sec = null) {
@@ -2624,9 +2651,8 @@ class WebDriver extends Helper {
    * I.waitForDetached('#popup');
    * ```
    * 
-   * @param {string|object} locator element located by CSS|XPath|strict locator.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    *
    */
   async waitForDetached(locator, sec = null) {
@@ -2655,9 +2681,9 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {string|function} fn to be executed in browser context.
-   * @param {array|number} argsOrSec (optional, `1` by default) arguments for function or seconds.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
-   * {--end--}
+   * @param {any[]|number} [argsOrSec] (optional, `1` by default) arguments for function or seconds.
+   * @param {number} [sec] (optional, `1` by default) time in seconds to wait
+   * 
    *
    */
   async waitForFunction(fn, argsOrSec = null, sec = null) {
@@ -2683,9 +2709,9 @@ class WebDriver extends Helper {
    * ```
    * 
    * @param {function|string} fn function which is executed in browser context.
-   * @param {number} sec (optional, `1` by default) time in seconds to wait
+   * @param {number} [sec=1] (optional, `1` by default) time in seconds to wait
    * @param {string} [timeoutMsg=''] message to show in case of timeout fail.
-   * {--end--}
+   * @param {?number} [interval=null]
    *
    */
   async waitUntil(fn, sec = null, timeoutMsg = null, interval = null) {
@@ -2702,17 +2728,18 @@ class WebDriver extends Helper {
    * I.switchTo(); // switch back to main page
    * ```
    * 
-   * @param {string|object} locator (optional, `null` by default) element located by CSS|XPath|strict locator.
-   * {--end--}
+   * @param {?CodeceptJS.LocatorOrString} [locator=null] (optional, `null` by default) element located by CSS|XPath|strict locator.
    *
    */
   async switchTo(locator) {
     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);
@@ -2727,8 +2754,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;
@@ -2753,8 +2780,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;
@@ -2808,7 +2835,6 @@ class WebDriver extends Helper {
    * ```
    * 
    * @returns {Promise<number>} number of open tabs
-   * {--end--}
    */
   async grabNumberOfOpenTabs() {
     const pages = await this.browser.getWindowHandles();
@@ -2822,7 +2848,7 @@ class WebDriver extends Helper {
    * ```js
    * I.refreshPage();
    * ```
-   * {--end--}
+   * 
    */
   async refreshPage() {
     const client = this.browser;
@@ -2835,7 +2861,7 @@ class WebDriver extends Helper {
    * ```js
    * I.scrollPageToTop();
    * ```
-   * {--end--}
+   * 
    */
   scrollPageToTop() {
     const client = this.browser;
@@ -2852,7 +2878,7 @@ class WebDriver extends Helper {
    * ```js
    * I.scrollPageToBottom();
    * ```
-   * {--end--}
+   * 
    */
   scrollPageToBottom() {
     const client = this.browser;
@@ -2876,8 +2902,7 @@ class WebDriver extends Helper {
    * let { x, y } = await I.grabPageScrollPosition();
    * ```
    * 
-   * @returns {Promise<object>} scroll position
-   * {--end--}
+   * @returns {Promise<Object<string, *>>} scroll position
    */
   async grabPageScrollPosition() {
     /* eslint-disable comma-dangle */
@@ -2903,7 +2928,6 @@ class WebDriver extends Helper {
    * @param {number} latitude to set.
    * @param {number} longitude to set
    * @param {number} altitude (optional, null by default) to set
-   * {--end--}
    *
    */
   async setGeoLocation(latitude, longitude, altitude = null) {
@@ -2920,7 +2944,7 @@ class WebDriver extends Helper {
    * ```js
    * let geoLocation = await I.grabGeoLocation();
    * ```
-   * {--end--}
+   * 
    *
    */
   async grabGeoLocation() {
@@ -2948,14 +2972,16 @@ class WebDriver extends Helper {
    * @param {string|object} locator element located by CSS|XPath|strict locator.
    * @param {string} elementSize x, y, width or height of the given element.
    * @returns {object} Element bounding rectangle
-   * {--end--}
    */
   async grabElementBoundingRect(locator, prop) {
     const res = await this._locate(locator, true);
     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;
   }
@@ -3010,58 +3036,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;