codeceptjs 2.1.3 → 2.2.1

package/lib/helper/Nightmare.js

@@ -81,6 +81,9 @@ class Nightmare extends Helper {
   static _config() {
     return [
       { name: 'url', message: 'Base url of site to be tested', default: 'http://localhost' },
+      {
+        name: 'show', message: 'Show browser window', default: true, type: 'confirm',
+      },
     ];
   }
 
@@ -392,13 +395,9 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/amOnPage }}
-   *
-   * In a second argument a list of request headers can be passed:
+   * {{> amOnPage }}
+   * @param headers {object} list of request headers can be passed
    *
-   * ```js
-   * I.amOnPage('/auth', { 'x-my-custom-header': 'some value' })
-   * ```
    */
   async amOnPage(url, headers = null) {
     if (!(/^\w+\:\/\//.test(url))) {
@@ -417,7 +416,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeInTitle }}
+   * {{> seeInTitle }}
    */
   async seeInTitle(text) {
     const title = await this.browser.title();
@@ -425,7 +424,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeInTitle }}
+   * {{> dontSeeInTitle }}
    */
   async dontSeeInTitle(text) {
     const title = await this.browser.title();
@@ -433,21 +432,21 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabTitle }}
+   * {{> grabTitle }}
    */
   async grabTitle() {
     return this.browser.title();
   }
 
   /**
-   * {{> ../webapi/grabCurrentUrl }}
+   * {{> grabCurrentUrl }}
    */
   async grabCurrentUrl() {
     return this.browser.url();
   }
 
   /**
-   * {{> ../webapi/seeInCurrentUrl }}
+   * {{> seeInCurrentUrl }}
    */
   async seeInCurrentUrl(url) {
     const currentUrl = await this.browser.url();
@@ -455,7 +454,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeInCurrentUrl }}
+   * {{> dontSeeInCurrentUrl }}
    */
   async dontSeeInCurrentUrl(url) {
     const currentUrl = await this.browser.url();
@@ -463,7 +462,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeCurrentUrlEquals }}
+   * {{> seeCurrentUrlEquals }}
    */
   async seeCurrentUrlEquals(url) {
     const currentUrl = await this.browser.url();
@@ -471,7 +470,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeCurrentUrlEquals }}
+   * {{> dontSeeCurrentUrlEquals }}
    */
   async dontSeeCurrentUrlEquals(url) {
     const currentUrl = await this.browser.url();
@@ -479,21 +478,21 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/see }}
+   * {{> see }}
    */
   async see(text, context = null) {
     return proceedSee.call(this, 'assert', text, context);
   }
 
   /**
-   * {{> ../webapi/dontSee }}
+   * {{> dontSee }}
    */
   dontSee(text, context = null) {
     return proceedSee.call(this, 'negate', text, context);
   }
 
   /**
-   * {{> ../webapi/seeElement }}
+   * {{> seeElement }}
    */
   async seeElement(locator) {
     locator = new Locator(locator, 'css');
@@ -504,7 +503,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeElement }}
+   * {{> dontSeeElement }}
    */
   async dontSeeElement(locator) {
     locator = new Locator(locator, 'css');
@@ -516,7 +515,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeElementInDOM }}
+   * {{> seeElementInDOM }}
    */
   async seeElementInDOM(locator) {
     locator = new Locator(locator, 'css');
@@ -525,7 +524,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeElementInDOM }}
+   * {{> dontSeeElementInDOM }}
    */
   async dontSeeElementInDOM(locator) {
     locator = new Locator(locator, 'css');
@@ -534,7 +533,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeInSource }}
+   * {{> seeInSource }}
    */
   async seeInSource(text) {
     const source = await this.browser.evaluate(() => document.documentElement.outerHTML);
@@ -542,7 +541,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeInSource }}
+   * {{> dontSeeInSource }}
    */
   async dontSeeInSource(text) {
     const source = await this.browser.evaluate(() => document.documentElement.outerHTML);
@@ -550,20 +549,15 @@ class Nightmare extends Helper {
   }
 
   /**
-   * asserts that an element appears a given number of times in the DOM
-   * Element is located by label or name or CSS or XPath.
-   *
-   * ```js
-   * I.seeNumberOfElements('#submitBtn', 1);
-   * ```
+   * {{> seeNumberOfElements }}
    */
-  async seeNumberOfElements(selector, num) {
-    const elements = await this._locate(selector);
-    return equals(`expected number of elements (${selector}) is ${num}, but found ${elements.length}`).assert(elements.length, num);
+  async seeNumberOfElements(locator, num) {
+    const elements = await this._locate(locator);
+    return equals(`expected number of elements (${locator}) is ${num}, but found ${elements.length}`).assert(elements.length, num);
   }
 
   /**
-   * {{> ../webapi/seeNumberOfVisibleElements }}
+   * {{> seeNumberOfVisibleElements }}
    */
   async seeNumberOfVisibleElements(locator, num) {
     const res = await this.grabNumberOfVisibleElements(locator);
@@ -571,7 +565,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabNumberOfVisibleElements }}
+   * {{> grabNumberOfVisibleElements }}
    */
   async grabNumberOfVisibleElements(locator) {
     locator = new Locator(locator, 'css');
@@ -585,7 +579,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/click }}
+   * {{> click }}
    */
   async click(locator, context = null) {
     const el = await findClickable.call(this, locator, context);
@@ -595,7 +589,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/doubleClick }}
+   * {{> doubleClick }}
    */
   async doubleClick(locator, context = null) {
     const el = await findClickable.call(this, locator, context);
@@ -606,7 +600,7 @@ class Nightmare extends Helper {
 
 
   /**
-   * {{> ../webapi/rightClick }}
+   * {{> rightClick }}
    */
   async rightClick(locator, context = null) {
     const el = await findClickable.call(this, locator, context);
@@ -617,7 +611,7 @@ class Nightmare extends Helper {
 
 
   /**
-   * {{> ../webapi/moveCursorTo }}
+   * {{> moveCursorTo }}
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
     locator = new Locator(locator, 'css');
@@ -629,7 +623,7 @@ class Nightmare extends Helper {
 
 
   /**
-   * {{> ../webapi/executeScript }}
+   * {{> executeScript }}
    *
    * Wrapper for synchronous [evaluate](https://github.com/segmentio/nightmare#evaluatefn-arg1-arg2)
    */
@@ -639,7 +633,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/executeAsyncScript }}
+   * {{> executeAsyncScript }}
    *
    * Wrapper for asynchronous [evaluate](https://github.com/segmentio/nightmare#evaluatefn-arg1-arg2).
    * Unlike NightmareJS implementation calling `done` will return its first argument.
@@ -650,7 +644,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/resizeWindow }}
+   * {{> resizeWindow }}
    */
   async resizeWindow(width, height) {
     if (width === 'maximize') {
@@ -660,7 +654,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/checkOption }}
+   * {{> checkOption }}
    */
   async checkOption(field, context = null) {
     const els = await findCheckable.call(this, field, context);
@@ -670,7 +664,17 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/fillField }}
+   * {{> uncheckOption }}
+   */
+  async uncheckOption(field, context = null) {
+    const els = await findCheckable.call(this, field, context);
+    assertElementExists(els[0], field, 'Checkbox or radio');
+    return this.browser.evaluate(els => window.codeceptjs.unCheckEl(els[0]), els)
+      .wait(this.options.waitForAction);
+  }
+
+  /**
+   * {{> fillField }}
    */
   async fillField(field, value) {
     const el = await findField.call(this, field);
@@ -680,14 +684,14 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/clearField }}
+   * {{> clearField }}
    */
   async clearField(field) {
     return this.fillField(field, '');
   }
 
   /**
-   * {{> ../webapi/appendField }}
+   * {{> appendField }}
    */
   async appendField(field, value) {
     const el = await findField.call(this, field);
@@ -697,14 +701,14 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeInField }}
+   * {{> seeInField }}
    */
   async seeInField(field, value) {
     return proceedSeeInField.call(this, 'assert', field, value);
   }
 
   /**
-   * {{> ../webapi/dontSeeInField }}
+   * {{> dontSeeInField }}
    */
   async dontSeeInField(field, value) {
     return proceedSeeInField.call(this, 'negate', field, value);
@@ -739,26 +743,25 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeCheckboxIsChecked }}
+   * {{> seeCheckboxIsChecked }}
    */
   async seeCheckboxIsChecked(field) {
     return proceedIsChecked.call(this, 'assert', field);
   }
 
   /**
-   * {{> ../webapi/dontSeeCheckboxIsChecked }}
+   * {{> dontSeeCheckboxIsChecked }}
    */
   async dontSeeCheckboxIsChecked(field) {
     return proceedIsChecked.call(this, 'negate', field);
   }
 
   /**
-   * {{> ../webapi/attachFile }}
+   * {{> attachFile }}
    *
-   * ##### Limitations:
+   * Doesn't work if the Chromium DevTools panel is open (as Chromium allows only one attachment to the debugger at a time. [See more](https://github.com/rosshinkley/nightmare-upload#important-note-about-setting-file-upload-inputs))
    *
-   * * works only with CSS selectors.
-   * * doesn't work if the Chromium DevTools panel is open (as Chromium allows only one attachment to the debugger at a time. [See more](https://github.com/rosshinkley/nightmare-upload#important-note-about-setting-file-upload-inputs))
+   * @param locator CSS locator (XPath not allowed)
    */
   async attachFile(locator, pathToFile) {
     const file = path.join(global.codecept_dir, pathToFile);
@@ -775,7 +778,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabTextFrom }}
+   * {{> grabTextFrom }}
    */
   async grabTextFrom(locator) {
     locator = new Locator(locator, 'css');
@@ -791,7 +794,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabValueFrom }}
+   * {{> grabValueFrom }}
    */
   async grabValueFrom(locator) {
     const el = await findField.call(this, locator);
@@ -800,7 +803,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabAttributeFrom }}
+   * {{> grabAttributeFrom }}
    */
   async grabAttributeFrom(locator, attr) {
     locator = new Locator(locator, 'css');
@@ -817,7 +820,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabHTMLFrom }}
+   * {{> grabHTMLFrom }}
    */
   async grabHTMLFrom(locator) {
     locator = new Locator(locator, 'css');
@@ -840,7 +843,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/selectOption }}
+   * {{> selectOption }}
    */
   async selectOption(select, option) {
     const fetchAndCheckOption = function (el, locator) {
@@ -883,7 +886,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/setCookie }}
+   * {{> setCookie }}
    *
    * Wrapper for `.cookies.set(cookie)`.
    * [See more](https://github.com/segmentio/nightmare/blob/master/Readme.md#cookiessetcookie)
@@ -893,7 +896,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/seeCookie}}
+   * {{> seeCookie }}
    *
    */
   async seeCookie(name) {
@@ -902,7 +905,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/dontSeeCookie}}
+   * {{> dontSeeCookie }}
    */
   async dontSeeCookie(name) {
     const res = await this.browser.cookies.get(name);
@@ -910,24 +913,18 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabCookie}}
+   * {{> grabCookie }}
    *
-   * Returns cookie in JSON format. If name not passed returns all cookies for this domain.
-   *
-   * Multiple cookies can be received by passing query object:
-   *
-   * ```js
-   * I.grabCookie({ secure: true});
-   * ```
+   * @returns Promise<object> Cookie in JSON format. If name not passed returns all cookies for this domain.
    *
-   * If you'd like get all cookies for all urls, use: `.grabCookie({ url: null }).`
+   * Multiple cookies can be received by passing query object `I.grabCookie({ secure: true});`. If you'd like get all cookies for all urls, use: `.grabCookie({ url: null }).`
    */
   async grabCookie(name) {
     return this.browser.cookies.get(name);
   }
 
   /**
-   * {{> ../webapi/clearCookie}}
+   * {{> clearCookie }}
    */
   async clearCookie(cookie) {
     if (!cookie) {
@@ -937,7 +934,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/waitForFunction }}
+   * {{> waitForFunction }}
    */
   async waitForFunction(fn, argsOrSec = null, sec = null) {
     let args = [];
@@ -953,7 +950,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/wait }}
+   * {{> wait }}
    */
   async wait(sec) {
     return new Promise(((done) => {
@@ -962,7 +959,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/waitForText }}
+   * {{> waitForText }}
    */
   async waitForText(text, sec, context = null) {
     if (!context) {
@@ -982,7 +979,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/waitForVisible }}
+   * {{> waitForVisible }}
    */
   waitForVisible(locator, sec) {
     this.browser.options.waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -1000,14 +997,14 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/waitToHide }}
+   * {{> waitToHide }}
    */
   async waitToHide(locator, sec = null) {
     return this.waitForInvisible(locator, sec);
   }
 
   /**
-   * {{> ../webapi/waitForInvisible }}
+   * {{> waitForInvisible }}
    */
   waitForInvisible(locator, sec) {
     this.browser.options.waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -1025,7 +1022,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/waitForElement }}
+   * {{> waitForElement }}
    */
   async waitForElement(locator, sec) {
     this.browser.options.waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -1046,7 +1043,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/waitForDetached }}
+   * {{> waitForDetached }}
    */
   async waitForDetached(locator, sec) {
     this.browser.options.waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
@@ -1061,7 +1058,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/refreshPage }}
+   * {{> refreshPage }}
    */
   async refreshPage() {
     return this.browser.refresh();
@@ -1076,7 +1073,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/saveScreenshot }}
+   * {{> saveScreenshot }}
    */
   async saveScreenshot(fileName, fullPage = this.options.fullPageScreenshots) {
     const outputFile = screenshotOutputFolder(fileName);
@@ -1099,7 +1096,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/scrollTo }}
+   * {{> scrollTo }}
    */
   async scrollTo(locator, offsetX = 0, offsetY = 0) {
     if (typeof locator === 'number' && typeof offsetX === 'number') {
@@ -1121,14 +1118,14 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/scrollPageToTop }}
+   * {{> scrollPageToTop }}
    */
   async scrollPageToTop() {
     return this.executeScript(() => window.scrollTo(0, 0));
   }
 
   /**
-   * {{> ../webapi/scrollPageToBottom }}
+   * {{> scrollPageToBottom }}
    */
   async scrollPageToBottom() {
     /* eslint-disable prefer-arrow-callback, comma-dangle */
@@ -1144,7 +1141,7 @@ class Nightmare extends Helper {
   }
 
   /**
-   * {{> ../webapi/grabPageScrollPosition}}
+   * {{> grabPageScrollPosition }}
    */
   async grabPageScrollPosition() {
     /* eslint-disable comma-dangle */