codeceptjs 2.3.4 → 2.4.1

package/docs/build/Puppeteer.js

@@ -1,4 +1,9 @@
+const axios = require('axios');
+const fs = require('fs');
+const fsExtra = require('fs-extra');
 const requireg = require('requireg');
+const path = require('path');
+
 const Helper = require('../helper');
 const Locator = require('../locator');
 const recorder = require('../recorder');
@@ -7,11 +12,13 @@ const { urlEquals } = require('../assert/equal');
 const { equals } = require('../assert/equal');
 const { empty } = require('../assert/empty');
 const { truth } = require('../assert/truth');
+const isElementClickable = require('./scripts/isElementClickable');
 const {
   xpathLocator,
   ucfirst,
   fileExists,
   chunkArray,
+  toCamelCase,
   convertCssPropertiesToCamelCase,
   screenshotOutputFolder,
   getNormalizedKeyAttributeValue,
@@ -21,18 +28,15 @@ const {
   isColorProperty,
   convertColorToRGBA,
 } = require('../colorUtils');
-const path = require('path');
 const ElementNotFound = require('./errors/ElementNotFound');
 const RemoteBrowserConnectionRefused = require('./errors/RemoteBrowserConnectionRefused');
 const Popup = require('./extras/Popup');
 const Console = require('./extras/Console');
 const findReact = require('./extras/React');
-const axios = require('axios');
-const fs = require('fs');
-const fsExtra = require('fs-extra');
 
 let puppeteer;
 let perfTiming;
+let isAuthenticated = false;
 const popupStore = new Popup();
 const consoleLogStore = new Console();
 
@@ -50,6 +54,7 @@ const consoleLogStore = new Console();
  * 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'}
  * * `show`: (optional, default: false) - show Google Chrome window for debug.
  * * `restart`: (optional, default: true) - restart browser between tests.
  * * `disableScreenshots`: (optional, default: false)  - don't save screenshot on failure.
@@ -127,6 +132,22 @@ const consoleLogStore = new Console();
  * }
  * ```
  *
+* #### Example #5: Target URL with provided basic authentication
+ *
+ * ```js
+ * {
+ *    helpers: {
+ *      Puppeteer : {
+ *        url: 'http://localhost',
+ *        basicAuth: {username: 'username', password: 'password'},
+ *        show: true
+ *      }
+ *    }
+ * }
+ * ```
+ *
+ *
+ *
  * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
  *
  * ## Access From Helpers
@@ -185,7 +206,10 @@ class Puppeteer extends Helper {
 
   _setConfig(config) {
     this.options = this._validateConfig(config);
-    this.puppeteerOptions = Object.assign({ headless: !this.options.show }, this._getOptions(config));
+    this.puppeteerOptions = {
+      headless: !this.options.show,
+      ...this._getOptions(config),
+    };
     this.isRemoteBrowser = !!this.puppeteerOptions.browserWSEndpoint;
     popupStore.defaultAction = this.options.defaultPopupAction;
   }
@@ -247,9 +271,13 @@ class Puppeteer extends Helper {
       this.debugSection('Session', 'cleaning cookies and localStorage');
       await this.clearCookie();
     }
-    await this.executeScript('localStorage.clear();').catch((err) => {
-      if (!(err.message.indexOf("Storage is disabled inside 'data:' URLs.") > -1)) throw err;
-    });
+    const currentUrl = await this.grabCurrentUrl();
+
+    if (currentUrl.startsWith('http')) {
+      await this.executeScript('localStorage.clear();').catch((err) => {
+        if (!(err.message.indexOf("Storage is disabled inside 'data:' URLs.") > -1)) throw err;
+      });
+    }
     await this.closeOtherTabs();
     return this.browser;
   }
@@ -401,6 +429,7 @@ class Puppeteer extends Helper {
    * ```js
    * await I.grabPopupText();
    * ```
+   * @return {Promise<string | null>}
    */
   async grabPopupText() {
     if (popupStore.popup) {
@@ -517,12 +546,19 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} url url path or global url.
-   * {--end--}
    */
   async amOnPage(url) {
     if (!(/^\w+\:\/\//.test(url))) {
       url = this.options.url + url;
     }
+
+    if (this.config.basicAuth && (isAuthenticated !== true)) {
+      if (url.includes(this.options.url)) {
+        this.page.authenticate(this.config.basicAuth);
+        isAuthenticated = true;
+      }
+    }
+
     await this.page.goto(url, { waitUntil: this.options.waitForNavigation });
 
     const performanceTiming = JSON.parse(await this.page.evaluate(() => JSON.stringify(window.performance.timing)));
@@ -544,7 +580,6 @@ class Puppeteer extends Helper {
    * 
    * @param {number} width width in pixels or `maximize`.
    * @param {number} height height in pixels.
-   * {--end--}
    *
    * Unlike other drivers Puppeteer changes the size of a viewport, not the window!
    * Puppeteer does not control the window of a browser so it can't adjust its real size.
@@ -586,10 +621,10 @@ class Puppeteer 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.
+   * 
    * {{ react }}
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
@@ -611,7 +646,6 @@ class Puppeteer extends Helper {
    * 
    * @param {string|object} srcElement located by CSS|XPath|strict locator.
    * @param {string|object} destElement located by CSS|XPath|strict locator.
-   * {--end--}
    */
   async dragAndDrop(srcElement, destElement) {
     return proceedDragAndDrop.call(this, srcElement, destElement);
@@ -623,7 +657,7 @@ class Puppeteer extends Helper {
    * ```js
    * I.refreshPage();
    * ```
-   * {--end--}
+   * 
    */
   async refreshPage() {
     return this.page.reload({ timeout: this.options.getPageTimeout, waitUntil: this.options.waitForNavigation });
@@ -635,7 +669,7 @@ class Puppeteer extends Helper {
    * ```js
    * I.scrollPageToTop();
    * ```
-   * {--end--}
+   * 
    */
   scrollPageToTop() {
     return this.executeScript(() => {
@@ -649,7 +683,7 @@ class Puppeteer extends Helper {
    * ```js
    * I.scrollPageToBottom();
    * ```
-   * {--end--}
+   * 
    */
   scrollPageToBottom() {
     return this.executeScript(() => {
@@ -671,10 +705,9 @@ class Puppeteer 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) {
     if (typeof locator === 'number' && typeof offsetX === 'number') {
@@ -703,7 +736,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} text text value to check.
-   * {--end--}
    */
   async seeInTitle(text) {
     const title = await this.page.title();
@@ -718,8 +750,7 @@ class Puppeteer 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 */
@@ -753,7 +784,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} text value to check.
-   * {--end--}
    */
   async dontSeeInTitle(text) {
     const title = await this.page.title();
@@ -769,7 +799,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @returns {Promise<string>} title
-   * {--end--}
    */
   async grabTitle() {
     return this.page.title();
@@ -927,7 +956,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @returns {Promise<number>} number of open tabs
-   * {--end--}
    */
   async grabNumberOfOpenTabs() {
     const pages = await this.browser.pages();
@@ -941,8 +969,7 @@ class Puppeteer 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 }}
    */
   async seeElement(locator) {
@@ -958,8 +985,7 @@ class Puppeteer 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) {
@@ -975,8 +1001,8 @@ class Puppeteer 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) {
     const els = await this._locate(locator);
@@ -990,8 +1016,7 @@ class Puppeteer 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) {
     const els = await this._locate(locator);
@@ -1021,9 +1046,9 @@ class Puppeteer 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 }}
    */
@@ -1037,9 +1062,8 @@ class Puppeteer extends Helper {
    * ```js
    * I.clickLink('Logout', '#nav');
    * ```
-   * @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 }}
    */
@@ -1150,9 +1174,9 @@ class Puppeteer 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 }}
    */
@@ -1172,9 +1196,9 @@ class Puppeteer 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 }}
    */
@@ -1193,9 +1217,8 @@ class Puppeteer 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.
    */
   async checkOption(field, context = null) {
     const elm = await this._locateCheckable(field, context);
@@ -1219,9 +1242,8 @@ class Puppeteer 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.
    */
   async uncheckOption(field, context = null) {
     const elm = await this._locateCheckable(field, context);
@@ -1243,8 +1265,8 @@ class Puppeteer 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.
+   * 
    */
   async seeCheckboxIsChecked(field) {
     return proceedIsChecked.call(this, 'assert', field);
@@ -1259,8 +1281,8 @@ class Puppeteer 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.
+   * 
    */
   async dontSeeCheckboxIsChecked(field) {
     return proceedIsChecked.call(this, 'negate', field);
@@ -1278,7 +1300,7 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} key name of key to press down.
-   * {--end--}
+   * 
    */
   async pressKeyDown(key) {
     key = getNormalizedKey.call(this, key);
@@ -1298,7 +1320,7 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} key name of key to release.
-   * {--end--}
+   * 
    */
   async pressKeyUp(key) {
     key = getNormalizedKey.call(this, key);
@@ -1365,8 +1387,8 @@ class Puppeteer 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:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)).
    */
@@ -1409,9 +1431,9 @@ class Puppeteer 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 }}
    */
   async fillField(field, value) {
@@ -1439,7 +1461,6 @@ class Puppeteer extends Helper {
    * I.clearField('#email');
    * ```
    * @param {string|object} editable field located by label|name|CSS|XPath|strict locator.
-   * {--end--}
    */
   async clearField(field) {
     return this.fillField(field, '');
@@ -1452,9 +1473,8 @@ class Puppeteer 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 }}
    */
@@ -1476,9 +1496,9 @@ class Puppeteer 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) {
     return proceedSeeInField.call(this, 'assert', field, value);
@@ -1493,9 +1513,8 @@ class Puppeteer 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) {
     return proceedSeeInField.call(this, 'negate', field, value);
@@ -1512,9 +1531,8 @@ class Puppeteer 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--}
    */
   async attachFile(locator, pathToFile) {
     const file = path.join(global.codecept_dir, pathToFile);
@@ -1547,9 +1565,8 @@ class Puppeteer 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 els = await findFields.call(this, select);
@@ -1587,9 +1604,8 @@ class Puppeteer 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--}
    * {{ react }}
    */
   async grabNumberOfVisibleElements(locator) {
@@ -1606,7 +1622,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} url a fragment to check
-   * {--end--}
    */
   async seeInCurrentUrl(url) {
     stringIncludes('url').assert(url, await this._getPageUrl());
@@ -1616,7 +1631,6 @@ class Puppeteer extends Helper {
    * Checks that current url does not contain a provided fragment.
    * 
    * @param {string} url value to check.
-   * {--end--}
    */
   async dontSeeInCurrentUrl(url) {
     stringIncludes('url').negate(url, await this._getPageUrl());
@@ -1633,7 +1647,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} url value to check.
-   * {--end--}
    */
   async seeCurrentUrlEquals(url) {
     urlEquals(this.options.url).assert(url, await this._getPageUrl());
@@ -1649,7 +1662,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} url value to check.
-   * {--end--}
    */
   async dontSeeCurrentUrlEquals(url) {
     urlEquals(this.options.url).negate(url, await this._getPageUrl());
@@ -1665,8 +1677,7 @@ class Puppeteer 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 }}
    */
@@ -1676,10 +1687,13 @@ class Puppeteer extends Helper {
 
   /**
    * Checks that text is equal to provided one.
-   *
+   * 
    * ```js
    * I.seeTextEquals('text', 'h1');
    * ```
+   * 
+   * @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);
@@ -1695,9 +1709,8 @@ class Puppeteer 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 }}
    */
@@ -1714,7 +1727,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @returns {Promise<string>} source code
-   * {--end--}
    */
   async grabSource() {
     return this.page.content();
@@ -1727,6 +1739,7 @@ class Puppeteer extends Helper {
    * let logs = await I.grabBrowserLogs();
    * console.log(JSON.stringify(logs))
    * ```
+   * @return {Promise<any[]>}
    */
   async grabBrowserLogs() {
     const logs = consoleLogStore.entries;
@@ -1744,7 +1757,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @returns {Promise<string>} current URL
-   * {--end--}
    */
   async grabCurrentUrl() {
     return this._getPageUrl();
@@ -1757,7 +1769,6 @@ class Puppeteer extends Helper {
    * I.seeInSource('<h1>Green eggs &amp; ham</h1>');
    * ```
    * @param {string} text value to check.
-   * {--end--}
    */
   async seeInSource(text) {
     const source = await this.page.content();
@@ -1772,7 +1783,7 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} value to check.
-   * {--end--}
+   * 
    */
   async dontSeeInSource(text) {
     const source = await this.page.content();
@@ -1789,9 +1800,9 @@ class Puppeteer 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 }}
    */
@@ -1808,9 +1819,9 @@ class Puppeteer 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 }}
    */
@@ -1827,7 +1838,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {object} cookie a cookie object.
-   * {--end--}
    */
   async setCookie(cookie) {
     if (Array.isArray(cookie)) {
@@ -1844,7 +1854,7 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} name cookie name.
-   * {--end--}
+   * 
    *
    */
   async seeCookie(name) {
@@ -1860,7 +1870,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {string} name cookie name.
-   * {--end--}
    */
   async dontSeeCookie(name) {
     const cookies = await this.page.cookies();
@@ -1870,16 +1879,15 @@ class Puppeteer 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--}
    *
    * Returns cookie in JSON format. If name not passed returns all cookies for this domain.
    */
@@ -1899,8 +1907,7 @@ class Puppeteer 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(name) {
     const cookies = await this.page.cookies();
@@ -1937,8 +1944,9 @@ class Puppeteer 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>}
+   * 
    *
    * If a function returns a Promise It will wait for it resolution.
    */
@@ -1973,8 +1981,9 @@ class Puppeteer 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>}
+   * 
    *
    * Asynchronous scripts can also be executed with `executeScript` if a function returns a Promise.
    */
@@ -2003,9 +2012,8 @@ class Puppeteer 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
    * {{ react }}
    */
   async grabTextFrom(locator) {
@@ -2026,9 +2034,8 @@ class Puppeteer 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) {
     const els = await findFields.call(this, locator);
@@ -2045,14 +2052,13 @@ class Puppeteer 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) {
     const els = await this._locate(locator);
     assertElementExists(els, locator);
-    const values = await Promise.all(els.map(el => this.page.evaluate(element => element.innerHTML, el)));
+    const values = await Promise.all(els.map(el => el.executionContext().evaluate(element => element.innerHTML, el)));
     if (Array.isArray(values) && values.length === 1) {
       return values[0];
     }
@@ -2067,16 +2073,15 @@ class Puppeteer 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--}
    * {{ react }}
    */
   async grabCssPropertyFrom(locator, cssProperty) {
     const els = await this._locate(locator);
     const res = await Promise.all(els.map(el => el.executionContext().evaluate(el => JSON.parse(JSON.stringify(getComputedStyle(el))), el)));
-    const cssValues = res.map(props => props[cssProperty]);
+    const cssValues = res.map(props => props[toCamelCase(cssProperty)]);
 
     if (res.length > 0) {
       return cssValues;
@@ -2091,9 +2096,8 @@ class Puppeteer 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--}
    * {{ react }}
    */
   async seeCssPropertiesOnElements(locator, cssProperties) {
@@ -2138,9 +2142,8 @@ class Puppeteer 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--}
    * {{ react }}
    */
   async seeAttributesOnElements(locator, attributes) {
@@ -2179,9 +2182,8 @@ class Puppeteer 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--}
    * {{ react }}
    */
   async dragSlider(locator, offsetX = 0) {
@@ -2210,10 +2212,9 @@ class Puppeteer 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--}
    * {{ react }}
    */
   async grabAttributeFrom(locator, attr) {
@@ -2240,8 +2241,7 @@ class Puppeteer 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) {
     const fullPageOption = fullPage || this.options.fullPageScreenshots;
@@ -2267,7 +2267,6 @@ class Puppeteer extends Helper {
    * ```
    * 
    * @param {number} sec number of second to wait.
-   * {--end--}
    */
   async wait(sec) {
     return new Promise(((done) => {
@@ -2279,9 +2278,8 @@ class Puppeteer 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) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2319,8 +2317,7 @@ class Puppeteer 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) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2357,10 +2354,9 @@ class Puppeteer 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
    * {{ react }}
    */
   async waitNumberOfVisibleElements(locator, num, sec) {
@@ -2390,6 +2386,31 @@ class Puppeteer extends Helper {
     });
   }
 
+  /**
+   * 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) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator);
+
+    return this.waitForFunction(isElementClickable, [els[0]], waitTimeout).catch(async (e) => {
+      if (/failed: timeout/i.test(e.message)) {
+        throw new Error(`element ${new Locator(locator).toString()} still not clickable after ${waitTimeout || this.options.waitForTimeout / 1000} sec`);
+      } else {
+        throw e;
+      }
+    });
+  }
+
   /**
    * Waits for element to be present on page (by default waits for 1sec).
    * Element can be located by CSS or XPath.
@@ -2399,9 +2420,8 @@ class Puppeteer 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
    * {{ react }}
    */
   async waitForElement(locator, sec) {
@@ -2428,9 +2448,8 @@ class Puppeteer 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
    *
    * This method accepts [React selectors](https://codecept.io/react).
    */
@@ -2458,9 +2477,8 @@ class Puppeteer 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) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2486,9 +2504,8 @@ class Puppeteer 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) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2520,8 +2537,7 @@ class Puppeteer 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 waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2548,8 +2564,7 @@ class Puppeteer 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 waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2583,9 +2598,8 @@ class Puppeteer 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) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2605,10 +2619,11 @@ class Puppeteer extends Helper {
 
       if (locator.isXPath()) {
         waiter = contextObject.waitForFunction((locator, text, $XPath) => {
+          eval($XPath); // eslint-disable-line no-eval
           const el = $XPath(null, locator);
           if (!el.length) return false;
           return el[0].innerText.indexOf(text) > -1;
-        }, { timeout: waitTimeout }, locator.value, text, $XPath);
+        }, { timeout: waitTimeout }, locator.value, text, $XPath.toString());
       }
     } else {
       waiter = contextObject.waitForFunction(text => document.body.innerText.indexOf(text) > -1, { timeout: waitTimeout }, text);
@@ -2628,7 +2643,7 @@ class Puppeteer extends Helper {
    * ```
    *
    * @param {string|function} urlOrPredicate
-   * @param {number?} [sec=null] seconds to wait
+   * @param {?number} [sec=null] seconds to wait
    */
   async waitForRequest(urlOrPredicate, sec = null) {
     const timeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2644,7 +2659,7 @@ class Puppeteer extends Helper {
    * ```
    *
    * @param {string|function} urlOrPredicate
-   * @param {number?} [sec=null] number of seconds to wait
+   * @param {?number} [sec=null] number of seconds to wait
    */
   async waitForResponse(urlOrPredicate, sec = null) {
     const timeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2659,8 +2674,7 @@ class Puppeteer 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) {
     if (Number.isInteger(locator)) {
@@ -2679,7 +2693,8 @@ class Puppeteer extends Helper {
         throw new Error('Element #invalidIframeSelector was not found by text|CSS|XPath');
       }
       return;
-    } else if (!locator) {
+    }
+    if (!locator) {
       this.context = await this.page.mainFrame().$('body');
       return;
     }
@@ -2711,9 +2726,9 @@ class Puppeteer 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) {
     let args = [];
@@ -2737,7 +2752,11 @@ class Puppeteer extends Helper {
    * @param {*} opts
    */
   async waitForNavigation(opts = {}) {
-    opts = Object.assign({ timeout: this.options.getPageTimeout, waitUntil: this.options.waitForNavigation }, opts);
+    opts = {
+      timeout: this.options.getPageTimeout,
+      waitUntil: this.options.waitForNavigation,
+      ...opts,
+    };
     return this.page.waitForNavigation(opts);
   }
 
@@ -2750,9 +2769,9 @@ class Puppeteer 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) {
     console.log('This method will remove in CodeceptJS 1.4; use `waitForFunction` instead!');
@@ -2776,9 +2795,8 @@ class Puppeteer 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) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -2827,7 +2845,6 @@ class Puppeteer extends Helper {
    *   loadEventEnd: 241
    * }
    * ```
-   * {--end--}
    */
   async grabDataFromPerformanceTiming() {
     return perfTiming;
@@ -2854,7 +2871,6 @@ class Puppeteer 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 els = await this._locate(locator);