codeceptjs 2.3.4 → 2.4.1

package/lib/event.js

@@ -3,8 +3,28 @@ const events = require('events');
 const dispatcher = new events.EventEmitter();
 const log = require('./output').log;
 
+/**
+ * @namespace
+ * @alias event
+ */
 module.exports = {
+  /**
+   * @type {NodeJS.EventEmitter}
+   * @constant
+   * @inner
+   */
   dispatcher,
+  /**
+   * @type {object}
+   * @constant
+   * @inner
+   * @property {'test.start'} started
+   * @property {'test.before'} before
+   * @property {'test.after'} after
+   * @property {'test.passed'} passed
+   * @property {'test.failed'} failed
+   * @property {'test.finish'} finished
+   */
   test: {
     started: 'test.start', // sync
     before: 'test.before', // async
@@ -13,15 +33,40 @@ module.exports = {
     failed: 'test.failed', // sync
     finished: 'test.finish', // sync
   },
+  /**
+   * @type {object}
+   * @constant
+   * @inner
+   * @property {'suite.before'} before
+   * @property {'suite.after'} after
+   */
   suite: {
     before: 'suite.before',
     after: 'suite.after',
   },
+  /**
+   * @type {object}
+   * @constant
+   * @inner
+   * @property {'hook.start'} started
+   * @property {'hook.passed'} passed
+   */
   hook: {
     started: 'hook.start',
     passed: 'hook.passed',
     failed: 'hook.failed',
   },
+  /**
+   * @type {object}
+   * @constant
+   * @inner
+   * @property {'step.start'} started
+   * @property {'step.before'} before
+   * @property {'step.after'} after
+   * @property {'step.passed'} passed
+   * @property {'step.failed'} failed
+   * @property {'step.finish'} finished
+   */
   step: {
     before: 'step.before', // async
     after: 'step.after', // async
@@ -31,16 +76,35 @@ module.exports = {
     finished: 'step.finish', // sync
     comment: 'step.comment',
   },
+  /**
+   * @type {object}
+   * @constant
+   * @inner
+   * @property {'global.before'} before
+   * @property {'global.after'} after
+   * @property {'global.result'} result
+   */
   all: {
     before: 'global.before',
     after: 'global.after',
     result: 'global.result',
   },
+  /**
+   * @type {object}
+   * @constant
+   * @inner
+   * @property {'multiple.before'} before
+   * @property {'multiple.after'} after
+   */
   multiple: {
     before: 'multiple.before',
     after: 'multiple.after',
   },
 
+  /**
+   * @param {string} event
+   * @param {*} param
+   */
   emit(event, param) {
     let msg = `Emitted | ${event}`;
     if (param && param.toString()) {
@@ -55,7 +119,7 @@ module.exports = {
     }
   },
 
-  // for testing only!
+  /** for testing only! */
   cleanDispatcher: () => {
     let event;
     for (event in this.test) {

package/lib/helper/Appium.js

@@ -1,11 +1,13 @@
 let webdriverio;
 let wdioV4;
 let SCREEN_SIZE;
+
+const fs = require('fs');
+const requireg = require('requireg');
+
 const Webdriver = require('./WebDriver');
 const AssertionFailedError = require('../assert/error');
 const truth = require('../assert/truth').truth;
-const requireg = require('requireg');
-const fs = require('fs');
 const recorder = require('../recorder');
 const Locator = require('../locator');
 const ConnectionRefused = require('./errors/ConnectionRefused');
@@ -249,7 +251,8 @@ class Appium extends Webdriver {
         width: res.value[0],
         height: res.value[1],
       });
-    } else if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && !this.platform) {
+    }
+    if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && !this.platform) {
       const dimensions = this.options.windowSize.split('x');
       await this.browser.windowHandleSize({
         width: dimensions[0],
@@ -435,7 +438,7 @@ class Appium extends Webdriver {
    * I.seeAppIsInstalled("com.example.android.apis");
    * ```
    *
-   * @param bundleId String  ID of bundled app
+   * @param {string} bundleId String  ID of bundled app
    *
    * Appium: support only Android
    */
@@ -452,7 +455,7 @@ class Appium extends Webdriver {
    * I.seeAppIsNotInstalled("com.example.android.apis");
    * ```
    *
-   * @param bundleId String  ID of bundled app
+   * @param {string} bundleId String  ID of bundled app
    *
    * Appium: support only Android
    */
@@ -468,7 +471,7 @@ class Appium extends Webdriver {
    * ```js
    * I.installApp('/path/to/file.apk');
    * ```
-   * @param path path to apk file
+   * @param {string} path path to apk file
    *
    * Appium: support only Android
    */
@@ -483,7 +486,8 @@ class Appium extends Webdriver {
    * ```js
    * I.removeApp('appName', 'com.example.android.apis');
    * ```
-   * @param bundleId String  ID of bundle
+   * @param {string} appId
+   * @param {string}  bundleId String  ID of bundle
    *
    * Appium: support only Android
    */
@@ -507,6 +511,7 @@ class Appium extends Webdriver {
    * ```js
    * I.seeCurrentActivityIs(".HomeScreenActivity")
    * ```
+   * @param {string} currentActivity
    *
    * Appium: support only Android
    */
@@ -554,7 +559,7 @@ class Appium extends Webdriver {
    * I.seeOrientationIs('LANDSCAPE')
    * ```
    *
-   * @param orientation LANDSCAPE or PORTRAIT
+   * @param {'LANDSCAPE'|'PORTRAIT'} orientation LANDSCAPE or PORTRAIT
    *
    * Appium: support Android and iOS
    */
@@ -584,7 +589,7 @@ class Appium extends Webdriver {
    * I.setOrientation('LANDSCAPE')
    * ```
    *
-   * @param orientation LANDSCAPE or PORTRAIT
+   * @param {'LANDSCAPE'|'PORTRAIT'} orientation LANDSCAPE or PORTRAIT
    *
    * Appium: support Android and iOS
    */
@@ -700,7 +705,7 @@ class Appium extends Webdriver {
   /**
    * Switch to the specified context.
    *
-   * @param context the context to switch to
+   * @param {*} context the context to switch to
 
    */
   async _switchToContext(context) {
@@ -799,7 +804,7 @@ class Appium extends Webdriver {
    * I.setSettings({cyberdelia: 'open'});
    * ```
    *
-   * @param settings object
+   * @param {object} settings object
    *
    * Appium: support Android and iOS
    */
@@ -820,7 +825,7 @@ class Appium extends Webdriver {
    * I.hideDeviceKeyboard('pressKey', 'Done');
    * ```
    *
-   * @param  strategy  desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
+   * @param {'tapOutside' | 'pressKey'} strategy  desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
    *
    * Appium: support Android and iOS
    */
@@ -838,7 +843,7 @@ class Appium extends Webdriver {
    * I.sendDeviceKeyEvent(3);
    * ```
    *
-   * @param keyValue  Device specific key value
+   * @param {number} keyValue  Device specific key value
    *
    * Appium: support only Android
    */
@@ -912,10 +917,10 @@ class Appium extends Webdriver {
    *
    * [See complete reference](http://webdriver.io/api/mobile/swipe.html)
    *
-   * @param locator
-   * @param xoffset
-   * @param yoffset
-   * @param speed (optional), 1000 by default
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {number} xoffset
+   * @param {number} yoffset
+   * @param {number} [speed=1000] (optional), 1000 by default
    *
    * Appium: support Android and iOS
    */
@@ -933,8 +938,8 @@ class Appium extends Webdriver {
    * I.performswipe(100,200);
    * ```
    *
-   * @param from
-   * @param to
+   * @param {number} from
+   * @param {number} to
    *
    * Appium: support Android and iOS
    */
@@ -964,9 +969,9 @@ class Appium extends Webdriver {
    * I.swipeDown(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param locator
-   * @param yoffset (optional)
-   * @param speed (optional), 1000 by default
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {number} [yoffset] (optional)
+   * @param {number} [speed=1000] (optional), 1000 by default
    *
    * Appium: support Android and iOS
    */
@@ -992,9 +997,9 @@ class Appium extends Webdriver {
    * I.swipeLeft(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param locator
-   * @param xoffset (optional)
-   * @param speed (optional), 1000 by default
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {number} [xoffset] (optional)
+   * @param {number} [speed=1000] (optional), 1000 by default
    *
    * Appium: support Android and iOS
    */
@@ -1018,9 +1023,9 @@ class Appium extends Webdriver {
    * I.swipeRight(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param locator
-   * @param xoffset (optional)
-   * @param speed (optional), 1000 by default
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {number} [xoffset] (optional)
+   * @param {number} [speed=1000] (optional), 1000 by default
    *
    * Appium: support Android and iOS
    */
@@ -1044,9 +1049,9 @@ class Appium extends Webdriver {
    * I.swipeUp(locator, 1200, 1000); // set offset and speed
    * ```
    *
-   * @param locator
-   * @param yoffset (optional)
-   * @param speed (optional), 1000 by default
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @param {number} [yoffset] (optional)
+   * @param {number} [speed=1000] (optional), 1000 by default
    *
    * Appium: support Android and iOS
    */
@@ -1074,12 +1079,12 @@ class Appium extends Webdriver {
    *    500);
    * ```
    *
-   * @param searchableLocator
-   * @param scrollLocator
-   * @param direction
-   * @param timeout
-   * @param offset
-   * @param speed
+   * @param {string} searchableLocator
+   * @param {string} scrollLocator
+   * @param {string} direction
+   * @param {number} timeout
+   * @param {number} offset
+   * @param {number} speed
    *
    * Appium: support Android and iOS
    */
@@ -1351,6 +1356,15 @@ class Appium extends Webdriver {
     return super.grabValueFrom(parseLocator.call(this, locator));
   }
 
+  /**
+   * {{> scrollIntoView }}
+   *
+   * Supported only for web testing
+   */
+  async scrollIntoView(locator, scrollIntoViewOptions) {
+    if (this.isWeb) return super.scrollIntoView(locator, scrollIntoViewOptions);
+  }
+
   /**
    * {{> seeCheckboxIsChecked }}
    *
@@ -1390,7 +1404,7 @@ class Appium extends Webdriver {
   /**
    * {{> selectOption }}
    *
-   * * Supported on only for web testing!
+   * Supported only for web testing
    */
   async selectOption(select, option) {
     if (this.isWeb) return super.selectOption(select, option);

package/lib/helper/FileSystem.js

@@ -1,10 +1,11 @@
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+
 const Helper = require('../helper');
 const fileExists = require('../utils').fileExists;
 const fileIncludes = require('../assert/include').fileIncludes;
 const fileEquals = require('../assert/equal').fileEquals;
-const assert = require('assert');
-const path = require('path');
-const fs = require('fs');
 
 /**
  * Helper for testing filesystem.
@@ -33,6 +34,7 @@ class FileSystem extends Helper {
   /**
    * Enters a directory In local filesystem.
    * Starts from a current directory
+   * @param {string} openPath
    */
   amInPath(openPath) {
     this.dir = path.join(global.codecept_dir, openPath);
@@ -41,6 +43,8 @@ class FileSystem extends Helper {
 
   /**
    * Writes test to file
+   * @param {string} name
+   * @param {string} text
    */
   writeToFile(name, text) {
     fs.writeFileSync(path.join(this.dir, name), text);
@@ -48,6 +52,7 @@ class FileSystem extends Helper {
 
   /**
    * Checks that file exists
+   * @param {string} name
    */
   seeFile(name) {
     this.file = path.join(this.dir, name);
@@ -55,8 +60,27 @@ class FileSystem extends Helper {
     assert.ok(fileExists(this.file), `File ${name} not found in ${this.dir}`);
   }
 
+  /**
+  * Checks that file with a name including given text exists in the current directory.
+  *
+  *```js
+  * I.handleDownloads();
+  * I.click('Download as PDF');
+  * I.amInPath('output/downloads');
+  * I.seeFileNameMatching('.pdf');
+  * ```
+  */
+  seeFileNameMatching(text) {
+    assert.ok(
+      this.grabFileNames().some(file => file.includes(text)),
+      `File name which contains ${text} not found in ${this.dir}`,
+    );
+  }
+
   /**
    * Checks that file found by `seeFile` includes a text.
+   * @param {string} text
+   * @param {string} encoding
    */
   seeInThisFile(text, encoding) {
     const content = getFileContents(this.file, encoding);
@@ -65,6 +89,8 @@ class FileSystem extends Helper {
 
   /**
    * Checks that file found by `seeFile` doesn't include text.
+   * @param {string} text
+   * @param {string} encoding
    */
   dontSeeInThisFile(text, encoding) {
     const content = getFileContents(this.file, encoding);
@@ -73,6 +99,8 @@ class FileSystem extends Helper {
 
   /**
    * Checks that contents of file found by `seeFile` equal to text.
+   * @param {string} text
+   * @param {string} encoding
    */
   seeFileContentsEqual(text, encoding) {
     const content = getFileContents(this.file, encoding);
@@ -81,11 +109,28 @@ class FileSystem extends Helper {
 
   /**
    * Checks that contents of file found by `seeFile` doesn't equal to text.
+   * @param {string} text
+   * @param {string} encoding
    */
   dontSeeFileContentsEqual(text, encoding) {
     const content = getFileContents(this.file, encoding);
     fileEquals(this.file).negate(text, content);
   }
+
+  /**
+  * Returns file names in current directory.
+  *
+  * ```js
+  * I.handleDownloads();
+  * I.click('Download Files');
+  * I.amInPath('output/downloads');
+  * const downloadedFileNames = I.grabFileNames();
+  * ```
+  */
+  grabFileNames() {
+    return fs.readdirSync(this.dir)
+      .filter(item => !fs.lstatSync(path.join(this.dir, item)).isDirectory());
+  }
 }
 
 function getFileContents(file, encoding) {

package/lib/helper/GraphQL.js

@@ -1,6 +1,7 @@
-const Helper = require('../helper');
 const requireg = require('requireg');
 
+const Helper = require('../helper');
+
 let axios = requireg('axios');
 let headers = {};
 
@@ -49,7 +50,7 @@ class GraphQL extends Helper {
       endpoint: '',
     };
     this.options = Object.assign(this.options, config);
-    headers = Object.assign({}, this.options.defaultHeaders);
+    headers = { ...this.options.defaultHeaders };
     axios.defaults.headers = this.options.defaultHeaders;
   }
 

package/lib/helper/GraphQLDataFactory.js

@@ -1,5 +1,6 @@
 const path = require('path');
 const requireg = require('requireg');
+
 const Helper = require('../helper');
 const GraphQL = require('./GraphQL');
 

package/lib/helper/Mochawesome.js

@@ -1,10 +1,11 @@
 let addMochawesomeContext;
 let currentTest;
 let currentSuite;
+
+const requireg = require('requireg');
+
 const Helper = require('../helper');
 const clearString = require('../utils').clearString;
-const requireg = require('requireg');
-const path = require('path');
 
 
 class Mochawesome extends Helper {

package/lib/helper/MockRequest.js

@@ -1,5 +1,6 @@
-const Helper = require('../helper');
 const requireg = require('requireg');
+
+const Helper = require('../helper');
 const { appendBaseUrl } = require('../utils');
 const pollyWebDriver = require('./clientscripts/PollyWebDriverExt');
 
@@ -32,7 +33,22 @@ let PollyJS;
  *    MockRequest: {}
  * }
  * ```
- * The same can be done when using WebDriver helper..
+ *
+ * > Partially works with WebDriver helper
+ *
+ * [Polly config options](https://netflix.github.io/pollyjs/#/configuration?id=configuration) can be passed as well:
+ *
+ * ```js
+ * // enable replay mode
+ * helpers: {
+ *  Puppeteer: {
+ *    // regular Puppeteer config here
+ *  },
+ *  MockRequest: {
+ *     mode: 'replay',
+ *  },
+ * }
+ * ```
  *
  * ### Usage
  *
@@ -101,13 +117,15 @@ class MockRequest extends Helper {
     }
     await page.setRequestInterception(true);
 
-    this.polly = new PollyJS(title, {
+    const defaultConfig = {
       mode: 'passthrough',
       adapters: ['puppeteer'],
       adapterOptions: {
         puppeteer: { page },
       },
-    });
+    };
+
+    this.polly = new PollyJS(title, { ...defaultConfig, ...this.options });
   }
 
   /**
@@ -140,7 +158,7 @@ class MockRequest extends Helper {
    * I.mockRequest('GET', ['/secrets', '/v2/secrets'], 403);
    * ```
    * @param {string} method request method. Can be `GET`, `POST`, `PUT`, etc or `ANY`.
-   * @param {string|array} oneOrMoreUrls url(s) to mock. Can be exact URL, a pattern, or an array of URLs.
+   * @param {string|string[]} oneOrMoreUrls url(s) to mock. Can be exact URL, a pattern, or an array of URLs.
    * @param {number|string|object} dataOrStatusCode status code when number provided. A response body otherwise
    * @param {string|object} additionalData response body when a status code is set by previous parameter.
    *

package/lib/helper/Nightmare.js

@@ -1,4 +1,7 @@
+const path = require('path');
 const requireg = require('requireg');
+const urlResolve = require('url').resolve;
+
 const Helper = require('../helper');
 const stringIncludes = require('../assert/include').includes;
 const urlEquals = require('../assert/equal').urlEquals;
@@ -6,9 +9,7 @@ const equals = require('../assert/equal').equals;
 const empty = require('../assert/empty').empty;
 const truth = require('../assert/truth').truth;
 const Locator = require('../locator');
-const path = require('path');
 const ElementNotFound = require('./errors/ElementNotFound');
-const urlResolve = require('url').resolve;
 const {
   xpathLocator,
   fileExists,
@@ -396,7 +397,7 @@ class Nightmare extends Helper {
 
   /**
    * {{> amOnPage }}
-   * @param headers {object} list of request headers can be passed
+   * @param {?object} headers list of request headers can be passed
    *
    */
   async amOnPage(url, headers = null) {
@@ -760,8 +761,6 @@ class Nightmare extends Helper {
    * {{> attachFile }}
    *
    * 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);
@@ -915,7 +914,7 @@ class Nightmare extends Helper {
   /**
    * {{> grabCookie }}
    *
-   * @returns Promise<object> Cookie in JSON format. If name not passed returns all cookies for this domain.
+   * Cookie in JSON format. If name not passed returns all cookies for this domain.
    *
    * 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 }).`
    */

package/lib/helper/Protractor.js

@@ -4,7 +4,9 @@ let Button;
 let ProtractorBy;
 let ProtractorExpectedConditions;
 
+const path = require('path');
 const requireg = require('requireg');
+
 const Helper = require('../helper');
 const stringIncludes = require('../assert/include').includes;
 const { urlEquals, equals } = require('../assert/equal');
@@ -23,7 +25,6 @@ const {
 const ElementNotFound = require('./errors/ElementNotFound');
 const ConnectionRefused = require('./errors/ConnectionRefused');
 const Locator = require('../locator');
-const path = require('path');
 
 let withinStore = {};
 let Runner;
@@ -99,7 +100,7 @@ let Runner;
  *        "browser": "chrome",
  *        "capabilities": {
  *          "chromeOptions": {
- *            "args": [ "--headless", "--disable-gpu", "--window-size=800,600" ]
+ *            "args": [ "--headless", "--disable-gpu", "--no-sandbox" ]
  *          }
  *        }
  *      }
@@ -508,11 +509,7 @@ class Protractor extends Helper {
   }
 
   /**
-   * Checks that text is equal to provided one.
-   *
-   * ```js
-   * I.seeTextEquals('text', 'h1');
-   * ```
+   * {{> seeTextEquals }}
    */
   async seeTextEquals(text, context = null) {
     return proceedSee.call(this, 'assert', text, context, true);
@@ -757,6 +754,7 @@ class Protractor extends Helper {
     }
     return array.length === 1 ? array[0] : array;
   }
+
   /**
    * {{> seeInTitle }}
    */
@@ -1235,7 +1233,8 @@ class Protractor extends Helper {
   async switchTo(locator) {
     if (Number.isInteger(locator)) {
       return this.browser.switchTo().frame(locator);
-    } else if (!locator) {
+    }
+    if (!locator) {
       return this.browser.switchTo().frame(null);
     }