codeceptjs 2.6.1 → 2.6.2

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2.6.2
+
+* [WebDriver][Puppeteer] Added `forceClick` method to emulate click event instead of using native events.
+* [Playwright] Updated to 0.14
+* [Puppeteer] Updated to Puppeteer v3.0
+* [wdio] Fixed undefined output directory for wdio plugns. Fix By @PeterNgTr
+* [Playwright] Introduced `handleDownloads` method to download file. Please note, this method has slightly different API than the same one in Puppeteer.
+* [allure] Fixed undefined output directory for allure plugin on using custom runner. Fix by @charliepradeep
+* [WebDriver] Fixed `waitForEnabled` fix for webdriver 6. Fix by @dsharapkou
+* Workers: Fixed negative failure result if use scenario with the same names. Fix by @Vorobeyko
+* [MockRequest] Updated documentation to match new helper version
+* Fixed: skipped tests are not reported if a suite failed in `before`. Refer #2349 & #2354. Fix by @koushikmohan1996
+
 ## 2.6.1
 
 * [screenshotOnFail plugin] Fixed saving screenshot of active session.

package/docs/basics.md

@@ -147,6 +147,8 @@ I.click('#signup');
 I.click('//dev[@test-id="myid"]');
 ```
 
+> ℹ If click doesn't work in a test but works for user, it is possible that frontend application is not designed for automated testing. To overcome limitation of standard click in this edgecase use `forceClick` method. It will emulate click instead of sending native event. This command will click an element no matter if this element is visible or animating. It will send JavaScript "click" event to it.
+
 ### Filling Fields
 
 Clicking the links is not what takes the most time during testing a web site. If your site consists only of links you can skip test automation. The most waste of time goes into the testing of forms. CodeceptJS provides several ways of doing that.
@@ -234,6 +236,8 @@ I.seeInTitle('My Website');
 
 To see all possible assertions, check the helper's reference.
 
+> ℹ If you need custom assertions, you can install an assertion libarary like `chai`, use grabbers to obtain information from a browser and perform assertions. However, it is recommended to put custom assertions into a helper for further reuse.
+
 ### Grabbing
 
 Sometimes you need to retrieve data from a page to use it in the following steps of a scenario.
@@ -435,7 +439,7 @@ This launches the interactive console where you can call any action from the `I`
  - Press ENTER to run the next step
  - Press TAB twice to see all available commands
  - Type exit + Enter to exit the interactive shell
- - Prefix => to run js commands 
+ - Prefix => to run js commands
  I.
 ```
 

package/docs/build/Playwright.js

@@ -1,5 +1,7 @@
 const requireg = require('requireg');
 const path = require('path');
+const fs = require('fs');
+const fsExtra = require('fs-extra');
 
 const Helper = require('../helper');
 const Locator = require('../locator');
@@ -69,7 +71,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * * `keepBrowserState`: (optional, default: false) - keep browser state between tests when `restart` is set to false.
  * * `keepCookies`: (optional, default: false) - keep cookies between tests when `restart` is set to false.
  * * `waitForAction`: (optional) how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
- * * `waitForNavigation`: (optional, default: 'load'). When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Playwright API](https://github.com/GoogleChrome/Playwright/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
+ * * `waitForNavigation`: (optional, default: 'load'). When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. Choose one of those options is possible. See [Playwright API](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitfornavigationoptions).
  * * `pressKeyDelay`: (optional, default: '10'). Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
  * * `getPageTimeout` (optional, default: '0') config option to set maximum navigation time in milliseconds.
  * * `waitForTimeout`: (optional) default wait* timeout in ms. Default: 1000.
@@ -94,7 +96,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * }
  * ```
  *
- * #### Example #2: Wait for DOMContentLoaded event and 0 network connections
+ * #### Example #2: Wait for DOMContentLoaded event
  *
  * ```js
  * {
@@ -102,7 +104,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  *      Playwright : {
  *        url: "http://localhost",
  *        restart: false,
- *        waitForNavigation: [ "domcontentloaded", "networkidle0" ],
+ *        waitForNavigation: "domcontentloaded",
  *        waitForAction: 500
  *      }
  *    }
@@ -540,7 +542,7 @@ class Playwright extends Helper {
     this.browser.on('targetchanged', (target) => {
       this.debugSection('Url', target.url());
     });
-    this.browserContext = await this.browser.newContext(this.options.emulate);
+    this.browserContext = await this.browser.newContext({ acceptDownloads: true, ...this.options.emulate });
 
     const existingPages = await this.browserContext.pages();
 
@@ -1113,6 +1115,36 @@ class Playwright extends Helper {
     return empty('elements on a page').assert(els.filter(v => v).fill('ELEMENT'));
   }
 
+  /**
+   * Handles a file download.Aa file name is required to save the file on disk.
+   * Files are saved to "output" directory.
+   *
+   * Should be used with [FileSystem helper](https://codecept.io/helpers/FileSystem) to check that file were downloaded correctly.
+   *
+   * ```js
+   * I.handleDownloads('downloads/avatar.jpg');
+   * I.click('Download Avatar');
+   * I.amInPath('output/downloads');
+   * I.waitForFile('downloads/avatar.jpg', 5);
+   *
+   * ```
+   *
+   * @param {string} [fileName] set filename for downloaded file
+   */
+  async handleDownloads(fileName = 'downloads') {
+    this.page.waitForEvent('download').then(async (download) => {
+      const filePath = await download.path();
+      const downloadPath = path.join(global.output_dir, fileName || path.basename(filePath));
+      if (!fs.existsSync(path.dirname(downloadPath))) {
+        fs.mkdirSync(path.dirname(downloadPath), '0777');
+      }
+      fs.copyFileSync(filePath, downloadPath);
+      this.debug('Download completed');
+      this.debugSection('Downloaded From', await download.url());
+      this.debugSection('Downloaded To', downloadPath);
+    });
+  }
+
   /**
    * Perform a click on a link or a button, given by a locator.
    * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.

package/docs/build/Puppeteer.js

@@ -232,7 +232,7 @@ class Puppeteer extends Helper {
     try {
       requireg('puppeteer');
     } catch (e) {
-      return ['puppeteer@^1.6.0'];
+      return ['puppeteer@^3.0.1'];
     }
   }
 
@@ -1087,6 +1087,63 @@ class Puppeteer extends Helper {
     return proceedClick.call(this, locator, context);
   }
 
+  /**
+   * Perform an emulated click on a link or a button, given by a locator.
+   * Unlike normal click instead of sending native event, emulates a click with JavaScript.
+   * This works on hidden, animated or inactive elements as well.
+   * 
+   * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+   * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+   * For images, the "alt" attribute and inner text of any parent links are searched.
+   * 
+   * The second parameter is a context (CSS or XPath locator) to narrow the search.
+   * 
+   * ```js
+   * // simple link
+   * I.forceClick('Logout');
+   * // button of form
+   * I.forceClick('Submit');
+   * // CSS button
+   * I.forceClick('#form input[type=submit]');
+   * // XPath
+   * I.forceClick('//form/*[@type=submit]');
+   * // link in context
+   * I.forceClick('Logout', '#nav');
+   * // using strict locator
+   * I.forceClick({css: 'nav a.login'});
+   * ```
+   * 
+   * @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 }}
+   */
+  async forceClick(locator, context = null) {
+    let matcher = await this.context;
+    if (context) {
+      const els = await this._locate(context);
+      assertElementExists(els, context);
+      matcher = els[0];
+    }
+
+    const els = await findClickable.call(this, matcher, locator);
+    if (context) {
+      assertElementExists(els, locator, 'Clickable element', `was not found inside element ${new Locator(context).toString()}`);
+    } else {
+      assertElementExists(els, locator, 'Clickable element');
+    }
+    const elem = els[0];
+    return this.executeScript((el) => {
+      if (document.activeElement instanceof HTMLElement) {
+        document.activeElement.blur();
+      }
+      const event = document.createEvent('MouseEvent');
+      event.initEvent('click', true, true);
+      return el.dispatchEvent(event);
+    }, elem);
+  }
+
   /**
    * Performs a click on a link and waits for navigation before moving on.
    * 

package/docs/build/WebDriver.js

@@ -516,6 +516,11 @@ class WebDriver extends Helper {
       if (this.options.multiremote) {
         this.browser = await webdriverio.multiremote(this.options.multiremote);
       } else {
+        // remove non w3c capabilities
+        delete this.options.capabilities.protocol;
+        delete this.options.capabilities.hostname;
+        delete this.options.capabilities.port;
+        delete this.options.capabilities.path;
         this.browser = await webdriverio.remote(this.options);
       }
     } catch (err) {
@@ -765,13 +770,15 @@ class WebDriver extends Helper {
    * Find a clickable element by providing human readable text:
    *
    * ```js
-   * this.helpers['WebDriver']._locateClickable('Next page').then // ...
+   * const els = await this.helpers.WebDriver._locateClickable('Next page');
+   * const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages');
    * ```
    *
    * @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);
+  async _locateClickable(locator, context) {
+    const locateFn = prepareLocateFn.call(this, context);
+    return findClickable.call(this, locator, locateFn);
   }
 
   /**
@@ -875,6 +882,59 @@ class WebDriver extends Helper {
     return this.browser[clickMethod](getElementId(elem));
   }
 
+  /**
+   * Perform an emulated click on a link or a button, given by a locator.
+   * Unlike normal click instead of sending native event, emulates a click with JavaScript.
+   * This works on hidden, animated or inactive elements as well.
+   * 
+   * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+   * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+   * For images, the "alt" attribute and inner text of any parent links are searched.
+   * 
+   * The second parameter is a context (CSS or XPath locator) to narrow the search.
+   * 
+   * ```js
+   * // simple link
+   * I.forceClick('Logout');
+   * // button of form
+   * I.forceClick('Submit');
+   * // CSS button
+   * I.forceClick('#form input[type=submit]');
+   * // XPath
+   * I.forceClick('//form/*[@type=submit]');
+   * // link in context
+   * I.forceClick('Logout', '#nav');
+   * // using strict locator
+   * I.forceClick({css: 'nav a.login'});
+   * ```
+   * 
+   * @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 }}
+   */
+  async forceClick(locator, context = null) {
+    const locateFn = prepareLocateFn.call(this, context);
+
+    const res = await findClickable.call(this, locator, locateFn);
+    if (context) {
+      assertElementExists(res, locator, 'Clickable element', `was not found inside element ${new Locator(context)}`);
+    } else {
+      assertElementExists(res, locator, 'Clickable element');
+    }
+    const elem = usingFirstElement(res);
+
+    return this.executeScript((el) => {
+      if (document.activeElement instanceof HTMLElement) {
+        document.activeElement.blur();
+      }
+      const event = document.createEvent('MouseEvent');
+      event.initEvent('click', true, true);
+      return el.dispatchEvent(event);
+    }, elem);
+  }
+
   /**
    * Performs a double-click on an element matched by link|button|label|CSS or XPath.
    * Context can be specified as second parameter to narrow search.
@@ -2498,6 +2558,19 @@ class WebDriver extends Helper {
    */
   async waitForEnabled(locator, sec = null) {
     const aSec = sec || this.options.waitForTimeout;
+    if (isWebDriver5()) {
+      return this.browser.waitUntil(async () => {
+        const res = await this.$$(withStrictLocator(locator));
+        if (!res || res.length === 0) {
+          return false;
+        }
+        const selected = await forEachAsync(res, async el => this.browser.isElementEnabled(getElementId(el)));
+        if (Array.isArray(selected)) {
+          return selected.filter(val => val === true).length > 0;
+        }
+        return selected;
+      }, aSec * 1000, `element (${new Locator(locator)}) still not enabled after ${aSec} sec`);
+    }
     return this.browser.waitUntil(async () => {
       const res = await this.$$(withStrictLocator(locator));
       if (!res || res.length === 0) {
@@ -2508,7 +2581,10 @@ class WebDriver extends Helper {
         return selected.filter(val => val === true).length > 0;
       }
       return selected;
-    }, aSec * 1000, `element (${new Locator(locator)}) still not enabled after ${aSec} sec`);
+    }, {
+      timeout: aSec * 1000,
+      timeoutMsg: `element (${new Locator(locator)}) still not enabled after ${aSec} sec`,
+    });
   }
 
   /**

package/docs/changelog.md

@@ -7,6 +7,19 @@ layout: Section
 
 # Releases
 
+## 2.6.2
+
+* [WebDriver][Puppeteer] Added `forceClick` method to emulate click event instead of using native events.
+* **[Playwright]** Updated to 0.14
+* **[Puppeteer]** Updated to Puppeteer v3.0
+* **[wdio]** Fixed undefined output directory for wdio plugns. Fix By **[PeterNgTr](https://github.com/PeterNgTr)**
+* **[Playwright]** Introduced `handleDownloads` method to download file. Please note, this method has slightly different API than the same one in Puppeteer.
+* **[allure]** Fixed undefined output directory for allure plugin on using custom runner. Fix by **[charliepradeep](https://github.com/charliepradeep)**
+* **[WebDriver]** Fixed `waitForEnabled` fix for webdriver 6. Fix by **[dsharapkou](https://github.com/dsharapkou)**
+* Workers: Fixed negative failure result if use scenario with the same names. Fix by **[Vorobeyko](https://github.com/Vorobeyko)**
+* **[MockRequest]** Updated documentation to match new helper version
+* Fixed: skipped tests are not reported if a suite failed in `before`. Refer [#2349](https://github.com/Codeception/CodeceptJS/issues/2349) & [#2354](https://github.com/Codeception/CodeceptJS/issues/2354). Fix by **[koushikmohan1996](https://github.com/koushikmohan1996)**
+
 ## 2.6.1
 
 * [screenshotOnFail plugin] Fixed saving screenshot of active session.

package/docs/helpers/Appium.md

@@ -1162,12 +1162,14 @@ this.helpers['WebDriver']._locateCheckable('I agree with terms and conditions').
 Find a clickable element by providing human readable text:
 
 ```js
-this.helpers['WebDriver']._locateClickable('Next page').then // ...
+const els = await this.helpers.WebDriver._locateClickable('Next page');
+const els = await this.helpers.WebDriver._locateClickable('Next page', '.pages');
 ```
 
 #### Parameters
 
 -   `locator` **([string][4] \| [object][6])** element located by CSS|XPath|strict locator.
+-   `context`  
 
 ### \_locateFields
 
@@ -1211,6 +1213,38 @@ I.amOnPage('/login'); // opens a login page
 
 -   `url` **[string][4]** url path or global url.
 
+### forceClick
+
+Perform an emulated click on a link or a button, given by a locator.
+Unlike normal click instead of sending native event, emulates a click with JavaScript.
+This works on hidden, animated or inactive elements as well.
+
+If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+For images, the "alt" attribute and inner text of any parent links are searched.
+
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
+```js
+// simple link
+I.forceClick('Logout');
+// button of form
+I.forceClick('Submit');
+// CSS button
+I.forceClick('#form input[type=submit]');
+// XPath
+I.forceClick('//form/*[@type=submit]');
+// link in context
+I.forceClick('Logout', '#nav');
+// using strict locator
+I.forceClick({css: 'nav a.login'});
+```
+
+#### Parameters
+
+-   `locator` **([string][4] \| [object][6])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+-   `context` **([string][4]? | [object][6])** (optional, `null` by default) element to search in CSS|XPath|Strict locator.{{ react }} (optional, default `null`)
+
 ### doubleClick
 
 Performs a double-click on an element matched by link|button|label|CSS or XPath.