codeceptjs 2.3.4 → 2.4.1

package/lib/helper/clientscripts/nightmare.js

@@ -1,10 +1,22 @@
 if (!window.codeceptjs) {
+  /**
+   * @alias CodeceptJS.browserCodecept
+   * @namespace
+   */
   const codeceptjs = {};
 
-  // all found elements are stored here for reuse
+  /**
+   * all found elements are stored here for reuse
+   * @inner
+   * @type {Node[]}
+   */
   codeceptjs.elements = [];
 
-  // global context changer
+  /**
+   * global context changer
+   * @inner
+   * @type {?Node}
+   */
   codeceptjs.within = null;
 
   // save
@@ -17,24 +29,50 @@ if (!window.codeceptjs) {
     return els.map(el => storeElement(el));
   };
 
-  // finders
+  /**
+   * finders
+   * @param {number} id
+   * @return {Node}
+   */
   codeceptjs.fetchElement = function (id) {
     if (!this.elements[id]) throw new Error(`Element (${id}) is not accessible`);
     return this.elements[id];
   };
 
+  /**
+   * @param   {string}  by
+   * @param   {CodeceptJS.ILocator}  locator
+   * @param   {*}  [contextEl]
+   * @return  {number[]}
+   */
   codeceptjs.findAndStoreElements = function (by, locator, contextEl) {
     return storeElements(this.findElements(by, locator, contextEl));
   };
 
+  /**
+   * @param   {string}  by
+   * @param   {CodeceptJS.ILocator}  locator
+   * @param   {*}  [contextEl]
+   * @return  {number | undefined}
+   */
   codeceptjs.findAndStoreElement = function (by, locator, contextEl) {
     return storeElement(this.findElement(by, locator, contextEl));
   };
 
+  /**
+   * @param {string} by
+   * @param {CodeceptJS.ILocator} locator
+   */
   codeceptjs.setWithin = function (by, locator) {
     this.within = this.findElement(by, locator);
   };
 
+  /**
+   * @param   {string}  by
+   * @param   {CodeceptJS.ILocator}  locator
+   * @param   {*}  [contextEl]
+   * @return  {Node[]}
+   */
   codeceptjs.findElements = function (by, locator, contextEl) {
     let context;
     if (typeof contextEl !== 'number') {
@@ -78,11 +116,21 @@ if (!window.codeceptjs) {
     return [];
   };
 
+  /**
+   * @param   {string}  by
+   * @param   {CodeceptJS.ILocator}  locator
+   * @param   {*}  [context]
+   * @return  {?Node}
+   */
   codeceptjs.findElement = function (by, locator, context) {
     return this.findElements(by, locator, context)[0] || null;
   };
 
   // actions
+  /**
+   * @param {number} el
+   * @return {boolean}
+   */
   codeceptjs.clickEl = function (el) {
     if (document.activeElement instanceof HTMLElement) {
       document.activeElement.blur();
@@ -92,6 +140,7 @@ if (!window.codeceptjs) {
     return this.fetchElement(el).dispatchEvent(event);
   };
 
+  /** @param {number} el */
   codeceptjs.doubleClickEl = function (el) {
     if (document.activeElement instanceof HTMLElement) {
       document.activeElement.blur();
@@ -101,6 +150,11 @@ if (!window.codeceptjs) {
     this.fetchElement(el).dispatchEvent(event);
   };
 
+  /**
+   * @param {number} el
+   * @param {number | undefined} x
+   * @param {number | undefined} y
+   */
   codeceptjs.hoverEl = function (el, x, y) {
     if (document.activeElement instanceof HTMLElement) {
       document.activeElement.blur();
@@ -118,7 +172,7 @@ if (!window.codeceptjs) {
     this.fetchElement(el).dispatchEvent(event);
   };
 
-
+  /** @param {number} el */
   codeceptjs.rightClickEl = function (el) {
     const event = new MouseEvent('contextmenu', {
       bubbles: true,
@@ -130,6 +184,10 @@ if (!window.codeceptjs) {
     this.fetchElement(el).dispatchEvent(event);
   };
 
+  /**
+   * @param {number} el
+   * @return {boolean  |  undefined}
+   */
   codeceptjs.checkEl = function (el) {
     const element = this.fetchElement(el);
     const event = document.createEvent('HTMLEvents');
@@ -139,6 +197,10 @@ if (!window.codeceptjs) {
     return element.dispatchEvent(event);
   };
 
+  /**
+   * @param {number} el
+   * @return {boolean}
+   */
   codeceptjs.unCheckEl = function (el) {
     const element = this.fetchElement(el);
     const event = document.createEvent('HTMLEvents');

package/lib/helper/scripts/isElementClickable.js

@@ -0,0 +1,24 @@
+function isElementClickable(elem) {
+  if (!elem.getBoundingClientRect || !elem.scrollIntoView || !document.elementFromPoint) {
+    return false;
+  }
+
+  const isElementInViewport = (elem) => {
+    const rect = elem.getBoundingClientRect();
+    const verticleInView = (rect.top <= window.innerHeight) && ((rect.top + rect.height) > 0);
+    const horizontalInView = (rect.left <= window.innerWidth) && ((rect.left + rect.width) > 0);
+    return horizontalInView && verticleInView;
+  };
+
+  const getOverlappingElement = (elem) => {
+    const rect = elem.getBoundingClientRect();
+    const x = rect.left + (elem.clientWidth / 2);
+    const y = rect.top + (elem.clientHeight / 2);
+    return document.elementFromPoint(x, y);
+  };
+
+  const isClickable = elem => elem.disabled !== true && isElementInViewport(elem) && getOverlappingElement(elem) === elem;
+  return isClickable(elem);
+}
+
+module.exports = isElementClickable;

package/lib/helper.js

@@ -21,6 +21,8 @@ class Helper {
 
   /**
    * Abstract method to provide required config options
+   * @return {*}
+   * @protected
    */
   static _config() {
 
@@ -29,6 +31,8 @@ class Helper {
   /**
    * Abstract method to validate config
    * @param {*} config
+   * @returns {*}
+   * @protected
    */
   _validateConfig(config) {
     return config;
@@ -36,6 +40,8 @@ class Helper {
 
   /**
    * Sets config for current test
+   * @param {*} opts
+   * @protected
    */
   _setConfig(opts) {
     this.options = this._validateConfig(opts);
@@ -43,6 +49,7 @@ class Helper {
 
   /**
    * Hook executed before all tests
+   * @protected
    */
   _init() {
 
@@ -50,6 +57,7 @@ class Helper {
 
   /**
    * Hook executed before each test.
+   * @protected
    */
   _before() {
 
@@ -57,6 +65,7 @@ class Helper {
 
   /**
    * Hook executed after each test
+   * @protected
    */
   _after() {
 
@@ -66,7 +75,8 @@ class Helper {
    * Hook provides a test details
    * Executed in the very beginning of a test
    *
-   * @param {*} test
+   * @param {Mocha.Test} test
+   * @protected
    */
   _test(test) {
 
@@ -75,7 +85,8 @@ class Helper {
   /**
    * Hook executed after each passed test
    *
-   * @param {*} test
+   * @param {Mocha.Test} test
+   * @protected
    */
   _passed(test) {
 
@@ -84,7 +95,8 @@ class Helper {
   /**
    * Hook executed after each failed test
    *
-   * @param {*} test
+   * @param {Mocha.Test} test
+   * @protected
    */
   _failed(test) {
 
@@ -93,8 +105,8 @@ class Helper {
   /**
    * Hook executed before each step
    *
-   * @param {*} step
-   * @override
+   * @param {CodeceptJS.Step} step
+   * @protected
    */
   _beforeStep(step) {
 
@@ -103,8 +115,8 @@ class Helper {
   /**
    * Hook executed after each step
    *
-   * @param {*} step
-   * @override
+   * @param {CodeceptJS.Step} step
+   * @protected
    */
   _afterStep(step) {
 
@@ -113,7 +125,8 @@ class Helper {
   /**
    * Hook executed before each suite
    *
-   * @param {*} suite
+   * @param {Mocha.Suite} suite
+   * @protected
    */
   _beforeSuite(suite) {
 
@@ -122,7 +135,8 @@ class Helper {
   /**
    * Hook executed after each suite
    *
-   * @param {*} suite
+   * @param {Mocha.Suite} suite
+   * @protected
    */
   _afterSuite(suite) {
 
@@ -131,7 +145,8 @@ class Helper {
   /**
    * Hook executed after all tests are executed
    *
-   * @param {*} suite
+   * @param {Mocha.Suite} suite
+   * @protected
    */
   _finishTest(suite) {
 
@@ -139,6 +154,9 @@ class Helper {
 
   /**
    * Access another configured helper: `this.helpers['AnotherHelper']`
+   *
+   * @readonly
+   * @type {*}
    */
   get helpers() {
     return container.helpers();
@@ -146,11 +164,17 @@ class Helper {
 
   /**
    * Print debug message to console (outputs only in debug mode)
+   *
+   * @param {string} msg
    */
   debug(msg) {
     output.debug(msg);
   }
 
+  /**
+   * @param {string}  section
+   * @param {string}  msg
+   */
   debugSection(section, msg) {
     output.debug(`[${section}] ${msg}`);
   }

package/lib/history.js

@@ -1,8 +1,8 @@
+const colors = require('chalk');
 const fs = require('fs');
 const path = require('path');
 
 const output = require('./output');
-const colors = require('chalk');
 
 /**
  * REPL history records REPL commands and stores them in

package/lib/hooks.js

@@ -1,5 +1,6 @@
-const getParamNames = require('./utils').getParamNames;
 const fsPath = require('path');
+
+const getParamNames = require('./utils').getParamNames;
 const fileExists = require('./utils').fileExists;
 const output = require('./output');
 

package/lib/index.js

@@ -2,19 +2,38 @@
  * Index file for loading CodeceptJS programmatically.
  *
  * Includes Public API objects
+ * @alias index
+ * @namespace
  */
 module.exports = {
+  /** @type {typeof CodeceptJS.Codecept} */
   codecept: require('./codecept'),
+  /** @type {typeof CodeceptJS.Codecept} */
+  Codecept: require('./codecept'),
+  /** @type {typeof CodeceptJS.output} */
   output: require('./output'),
+  /** @type {typeof CodeceptJS.Container} */
   container: require('./container'),
+  /** @type {typeof CodeceptJS.event} */
   event: require('./event'),
+  /** @type {CodeceptJS.recorder} */
   recorder: require('./recorder'),
+  /** @type {typeof CodeceptJS.Config} */
   config: require('./config'),
+  /** @type {CodeceptJS.actor} */
   actor: require('./actor'),
+  /** @type {typeof CodeceptJS.Helper} */
   helper: require('./helper'),
+  /** @type {typeof CodeceptJS.Helper} */
+  Helper: require('./helper'),
+  /** @type {typeof CodeceptJS.pause} */
   pause: require('./pause'),
+  /** @type {typeof CodeceptJS.within} */
   within: require('./within'),
+  /**  @type {typeof CodeceptJS.DataTable} */
   dataTable: require('./data/table'),
+  /** @type {typeof CodeceptJS.store} */
   store: require('./store'),
+  /** @type {typeof CodeceptJS.Locator} */
   locator: require('./locator'),
 };

package/lib/interfaces/bdd.js

@@ -8,6 +8,10 @@ let steps = {};
 
 const STACK_POSITION = 2;
 
+/**
+ * @param {*} step
+ * @param {*} fn
+ */
 const addStep = (step, fn) => {
   const stack = (new Error()).stack;
   steps[step] = fn;

package/lib/interfaces/featureConfig.js

@@ -1,3 +1,4 @@
+/** @class */
 class FeatureConfig {
   constructor(suite) {
     this.suite = suite;
@@ -6,7 +7,8 @@ class FeatureConfig {
   /**
    * Retry this suite for x times
    *
-   * @param {*} retries
+   * @param {number} retries
+   * @returns {this}
    */
   retry(retries) {
     this.suite.retries(retries);
@@ -15,7 +17,8 @@ class FeatureConfig {
 
   /**
    * Set timeout for this suite
-   * @param {*} timeout
+   * @param {number} timeout
+   * @returns {this}
    */
   timeout(timeout) {
     this.suite.timeout(timeout);
@@ -25,6 +28,9 @@ class FeatureConfig {
   /**
    * Configures a helper.
    * Helper name can be omitted and values will be applied to first helper.
+   * @param {string | Object<string, *>} helper
+   * @param {Object<string, *>} [obj]
+   * @returns {this}
    */
   config(helper, obj) {
     if (!obj) {
@@ -44,7 +50,8 @@ class FeatureConfig {
 
   /**
    * Append a tag name to scenario title
-   * @param {*} tagName
+   * @param {string} tagName
+   * @returns {this}
    */
   tag(tagName) {
     if (tagName[0] !== '@') {

package/lib/interfaces/gherkin.js

@@ -6,6 +6,7 @@ const { isAsyncFunction } = require('../utils');
 const event = require('../event');
 const scenario = require('../scenario');
 const Step = require('../step');
+const DataTableArgument = require('../data/dataTableArgument');
 
 const parser = new Parser();
 parser.stopAtFirstError = false;
@@ -36,6 +37,9 @@ module.exports = (text) => {
       };
       const fn = matchStep(step.text);
       if (step.argument) {
+        step.argument.parse = () => {
+          return new DataTableArgument(step.argument);
+        };
         fn.params.push(step.argument);
         if (step.argument.type === 'DataTable') metaStep.comment = `\n${transformTable(step.argument)}`;
         if (step.argument.content) metaStep.comment = `\n${step.argument.content}`;
@@ -65,7 +69,7 @@ module.exports = (text) => {
             const value = example.cells[index].value;
             current[placeholder] = value;
             exampleSteps = exampleSteps.map((step) => {
-              step = Object.assign({}, step);
+              step = { ...step };
               step.text = step.text.replace(`<${placeholder}>`, value);
               return step;
             });
@@ -102,7 +106,7 @@ function addExampleInTable(exampleSteps, placeholders) {
   const steps = JSON.parse(JSON.stringify(exampleSteps));
   for (const placeholder in placeholders) {
     steps.map((step) => {
-      step = Object.assign({}, step);
+      step = { ...step };
       if (step.argument && step.argument.type === 'DataTable') {
         for (const id in step.argument.rows) {
           const cells = step.argument.rows[id].cells;

package/lib/interfaces/scenarioConfig.js

@@ -1,3 +1,4 @@
+/** @class */
 class ScenarioConfig {
   constructor(test) {
     this.test = test;
@@ -8,6 +9,7 @@ class ScenarioConfig {
    * Can pass an Error object or regex matching expected message.
    *
    * @param {*} err
+   * @returns {this}
    */
   throws(err) {
     this.test.throws = err;
@@ -19,7 +21,7 @@ class ScenarioConfig {
    * If test passes - throws an error.
    * Can pass an Error object or regex matching expected message.
    *
-   * @param {*} err
+   * @returns {this}
    */
   fails() {
     this.test.throws = new Error();
@@ -29,7 +31,8 @@ class ScenarioConfig {
   /**
    * Retry this test for x times
    *
-   * @param {*} retries
+   * @param {number} retries
+   * @returns {this}
    */
   retry(retries) {
     this.test.retries(retries);
@@ -38,7 +41,8 @@ class ScenarioConfig {
 
   /**
    * Set timeout for this test
-   * @param {*} timeout
+   * @param {number} timeout
+   * @returns {this}
    */
   timeout(timeout) {
     this.test.timeout(timeout);
@@ -47,7 +51,8 @@ class ScenarioConfig {
 
   /**
    * Pass in additional objects to inject into test
-   * @param {*} obj
+   * @param {Object<string, any>} obj
+   * @returns {this}
    */
   inject(obj) {
     this.test.inject = obj;
@@ -57,6 +62,9 @@ class ScenarioConfig {
   /**
    * Configures a helper.
    * Helper name can be omitted and values will be applied to first helper.
+   * @param {string | Object<string, any>} helper
+   * @param {Object<string, any>} [obj]
+   * @returns {this}
    */
   async config(helper, obj) {
     if (!obj) {
@@ -75,7 +83,8 @@ class ScenarioConfig {
 
   /**
    * Append a tag name to scenario title
-   * @param {*} tagName
+   * @param {string} tagName
+   * @returns {this}
    */
   tag(tagName) {
     if (tagName[0] !== '@') tagName = `@${tagName}`;
@@ -86,12 +95,14 @@ class ScenarioConfig {
 
   /**
    * Dynamically injects dependencies, see https://codecept.io/pageobjects/#dynamic-injection
-   * @param {*} dependencies
+   * @param {Object<string, *>} dependencies
+   * @returns {this}
    */
   injectDependencies(dependencies) {
     Object.keys(dependencies).forEach((key) => {
       this.test.inject[key] = dependencies[key];
     });
+    return this;
   }
 }
 

package/lib/listener/config.js

@@ -15,7 +15,7 @@ module.exports = function () {
   function enableDynamicConfigFor(type) {
     event.dispatcher.on(event[type].before, (context = {}) => {
       function updateHelperConfig(helper, config) {
-        const oldConfig = Object.assign({}, helper.options);
+        const oldConfig = { ...helper.options };
         try {
           helper._setConfig(deepMerge(deepClone(oldConfig), config));
           debug(`[${ucfirst(type)} Config] ${helper.constructor.name} ${JSON.stringify(config)}`);

package/lib/listener/exit.js

@@ -23,4 +23,10 @@ module.exports = function () {
       process.exitCode = 1;
     }
   });
+
+  process.on('beforeExit', (code) => {
+    if (code) {
+      process.exit(code);
+    }
+  });
 };

package/lib/listener/steps.js

@@ -61,4 +61,3 @@ module.exports = function () {
     currentTest.steps.push(step);
   });
 };
-

package/lib/listener/trace.js

@@ -34,4 +34,3 @@ module.exports = function () {
     test.err = err;
   });
 };
-