codeceptjs 2.3.4 → 2.4.1

package/lib/plugin/stepByStepReport.js

@@ -1,13 +1,14 @@
+const colors = require('chalk');
+const crypto = require('crypto');
+const figures = require('figures');
+const fs = require('fs');
+const mkdirp = require('mkdirp');
+const path = require('path');
+
 const Container = require('../container');
 const recorder = require('../recorder');
 const event = require('../event');
 const output = require('../output');
-const mkdirp = require('mkdirp');
-const fs = require('fs');
-const path = require('path');
-const figures = require('figures');
-const colors = require('chalk');
-const crypto = require('crypto');
 const { template, deleteDir } = require('../utils');
 
 const supportedHelpers = [

package/lib/plugin/wdio.js

@@ -1,9 +1,10 @@
+const debug = require('debug')('codeceptjs:plugin:wdio');
+
 const container = require('../container');
 const mainConfig = require('../config');
 const recorder = require('../recorder');
 const event = require('../event');
 const output = require('../output');
-const debug = require('debug')('codeceptjs:plugin:wdio');
 
 const defaultConfig = {
   services: [],

package/lib/recorder.js

@@ -1,6 +1,7 @@
+const debug = require('debug')('codeceptjs');
 const promiseRetry = require('promise-retry');
+
 const log = require('./output').log;
-const debug = require('debug')('codeceptjs');
 
 let promise;
 let running = false;
@@ -20,11 +21,14 @@ const defaultRetryOptions = {
 
 /**
  * Singleton object to record all test steps as promises and run them in chain.
+ * @alias recorder
+ * @interface
  */
 module.exports = {
 
   /**
-   * @var retries Array[object]
+   * @type {Array<Object<string, *>>}
+   * @inner
    */
   retries: [],
 
@@ -32,6 +36,7 @@ module.exports = {
    * Start recording promises
    *
    * @api
+   * @inner
    */
   start() {
     running = true;
@@ -40,10 +45,18 @@ module.exports = {
     this.reset();
   },
 
+  /**
+   * @return {boolean}
+   * @inner
+   */
   isRunning() {
     return running;
   },
 
+  /**
+   * @return {void}
+   * @inner
+   */
   startUnlessRunning() {
     if (!this.isRunning()) {
       this.start();
@@ -54,7 +67,8 @@ module.exports = {
    * Add error handler to catch rejected promises
    *
    * @api
-   * @param {*} fn
+   * @param {function} fn
+   * @inner
    */
   errHandler(fn) {
     errFn = fn;
@@ -65,6 +79,7 @@ module.exports = {
    * Resets recorder to initial state.
    *
    * @api
+   * @inner
    */
   reset() {
     if (promise && running) this.catch();
@@ -79,9 +94,27 @@ module.exports = {
     this.retries = [];
   },
 
+  /**
+   * @name CodeceptJS.recorder~session
+   * @type {CodeceptJS.RecorderSession}
+   * @inner
+   */
+
+  /**
+   * @alias RecorderSession
+   * @interface
+   */
   session: {
+    /**
+     * @type {boolean}
+     * @inner
+     */
     running: false,
 
+    /**
+     * @param {string} name
+     * @inner
+     */
     start(name) {
       log(`${currentQueue()}Starting <${name}> session`);
       tasks.push('--->');
@@ -91,6 +124,10 @@ module.exports = {
       promise = Promise.resolve();
     },
 
+    /**
+     * @param {string} name
+     * @inner
+     */
     restore(name) {
       tasks.push('<---');
       log(`${currentQueue()}Finalize <${name}> session`);
@@ -100,6 +137,10 @@ module.exports = {
       promise = promise.then(() => oldPromises.pop());
     },
 
+    /**
+     * @param {function} fn
+     * @inner
+     */
     catch(fn) {
       promise = promise.catch(fn);
     },
@@ -110,12 +151,14 @@ module.exports = {
    * Adds a promise to a chain.
    * Promise description should be passed as first parameter.
    *
-   * @param {*} taskName
-   * @param {*} fn
-   * @param {*} force
-   * @param {boolean} retry -
+   * @param {string} taskName
+   * @param {function} [fn]
+   * @param {boolean} [force=false]
+   * @param {boolean} [retry=true] -
    *     true: it will retries if `retryOpts` set.
    *     false: ignore `retryOpts` and won't retry.
+   * @return {Promise<*> | undefined}
+   * @inner
    */
   add(taskName, fn = undefined, force = false, retry = true) {
     if (typeof taskName === 'function') {
@@ -152,6 +195,11 @@ module.exports = {
     });
   },
 
+  /**
+   * @param {*} opts
+   * @return {*}
+   * @inner
+   */
   retry(opts) {
     if (!promise) return;
 
@@ -164,6 +212,11 @@ module.exports = {
     return this.add(() => this.retries.push(opts));
   },
 
+  /**
+   * @param {function} [customErrFn]
+   * @return {Promise<*>}
+   * @inner
+   */
   catch(customErrFn) {
     return promise = promise.catch((err) => {
       log(`${currentQueue()}Error | ${err}`);
@@ -179,6 +232,11 @@ module.exports = {
     });
   },
 
+  /**
+   * @param {function} customErrFn
+   * @return {Promise<*>}
+   * @inner
+   */
   catchWithoutStop(customErrFn) {
     return promise = promise.catch((err) => {
       log(`${currentQueue()}Error | ${err}`);
@@ -198,6 +256,7 @@ module.exports = {
    *
    * @api
    * @param {*} err
+   * @inner
    */
   throw(err) {
     return this.add(`throw error ${err}`, () => {
@@ -205,16 +264,28 @@ module.exports = {
     });
   },
 
+  /**
+   * @param {*} err
+   * @inner
+   */
   saveFirstAsyncError(err) {
     if (asyncErr === null) {
       asyncErr = err;
     }
   },
 
+  /**
+   * @return {*}
+   * @inner
+   */
   getAsyncErr() {
     return asyncErr;
   },
 
+  /**
+   * @return {void}
+   * @inner
+   */
   cleanAsyncErr() {
     asyncErr = null;
   },
@@ -222,6 +293,7 @@ module.exports = {
   /**
    * Stops recording promises
    * @api
+   * @inner
    */
   stop() {
     debug(this.toString());
@@ -234,6 +306,8 @@ module.exports = {
    * Get latest promise in chain.
    *
    * @api
+   * @return {Promise<*>}
+   * @inner
    */
   promise() {
     return promise;
@@ -241,6 +315,8 @@ module.exports = {
 
   /**
    * Get a list of all chained tasks
+   * @return {string}
+   * @inner
    */
   scheduled() {
     return tasks.join('\n');
@@ -248,6 +324,8 @@ module.exports = {
 
   /**
    * Get a state of current queue and tasks
+   * @return {string}
+   * @inner
    */
   toString() {
     return `Queue: ${currentQueue()}\n\nTasks: ${this.scheduled()}`;

package/lib/rerun.js

@@ -0,0 +1,81 @@
+const fsPath = require('path');
+const container = require('./container');
+const event = require('./event');
+const BaseCodecept = require('./codecept');
+const output = require('./output');
+
+class CodeceptRerunner extends BaseCodecept {
+  runOnce(test) {
+    return new Promise((resolve, reject) => {
+      // @ts-ignore
+      container.createMocha();
+      const mocha = container.mocha();
+      this.testFiles.forEach((file) => {
+        delete require.cache[file];
+      });
+      mocha.files = this.testFiles;
+      if (test) {
+        if (!fsPath.isAbsolute(test)) {
+          test = fsPath.join(global.codecept_dir, test);
+        }
+        mocha.files = mocha.files.filter(t => fsPath.basename(t, '.js') === test || t === test);
+      }
+      try {
+        mocha.run((failures) => {
+          if (failures === 0) {
+            resolve();
+          } else {
+            reject(new Error(`${failures} tests fail`));
+          }
+        });
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+
+  async runTests(test) {
+    const configRerun = this.config.rerun || {};
+    const minSuccess = configRerun.minSuccess || 1;
+    const maxReruns = configRerun.maxReruns || 1;
+    if (minSuccess > maxReruns) throw new Error('minSuccess must be less than maxReruns');
+    if (maxReruns === 1) {
+      await this.runOnce(test);
+      return;
+    }
+    let successCounter = 0;
+    let rerunsCounter = 0;
+    while (rerunsCounter < maxReruns && successCounter < minSuccess) {
+      rerunsCounter++;
+      try {
+        await this.runOnce(test);
+        successCounter++;
+        output.success(`\nProcess run ${rerunsCounter} of max ${maxReruns}, success runs ${successCounter}/${minSuccess}\n`);
+      } catch (e) {
+        output.error(`\nFail run ${rerunsCounter} of max ${maxReruns}, success runs ${successCounter}/${minSuccess} \n`);
+        console.error(e);
+      }
+    }
+    if (successCounter < minSuccess) {
+      throw new Error(`Flaky tests detected! ${successCounter} success runs achieved instead of ${minSuccess} success runs expected`);
+    }
+  }
+
+  run(test) {
+    const done = () => {
+      event.emit(event.all.result, this);
+      event.emit(event.all.after, this);
+    };
+    event.emit(event.all.before, this);
+    return this.runTests(test)
+      .then(() => {
+        this.teardown(done);
+      })
+      .catch((e) => {
+        this.teardown(done);
+        throw e;
+      });
+  }
+}
+
+module.exports = CodeceptRerunner;

package/lib/secret.js

@@ -1,12 +1,18 @@
+/** @param {string} secret */
 class Secret {
   constructor(secret) {
     this._secret = secret;
   }
 
+  /** @returns {string} */
   toString() {
     return this._secret;
   }
 
+  /**
+   * @param {*} secret
+   * @returns {Secret}
+   */
   static secret(secret) {
     return new Secret(secret);
   }

package/lib/session.js

@@ -15,6 +15,12 @@ const sessionColors = [
 
 const savedSessions = {};
 
+/**
+ * @param {CodeceptJS.LocatorOrString}  sessionName
+ * @param {Function | Object<string, *>}  config
+ * @param {Function}  [fn]
+ * @return {Promise<*> | undefined}
+ */
 function session(sessionName, config, fn) {
   if (typeof config === 'function') {
     if (typeof fn === 'function') {
@@ -34,12 +40,13 @@ function session(sessionName, config, fn) {
   if (!savedSessions[sessionName]) {
     for (const helper in helpers) {
       if (!helpers[helper]._session) continue;
-      savedSessions[sessionName] = Object.assign({
+      savedSessions[sessionName] = {
         start: () => null,
         stop: () => null,
         loadVars: () => null,
         restoreVars: () => null,
-      }, store.dryRun ? {} : helpers[helper]._session());
+        ...(store.dryRun ? {} : helpers[helper]._session()),
+      };
       break;
     }
 

package/lib/step.js

@@ -1,3 +1,6 @@
+// TODO: place MetaStep in other file, disable rule
+/* eslint-disable max-classes-per-file */
+
 const store = require('./store');
 const Secret = require('./secret');
 
@@ -10,30 +13,52 @@ let support;
 /**
  * Each command in test executed through `I.` object is wrapped in Step.
  * Step allows logging executed commands and triggers hook before and after step execution.
+ * @param {CodeceptJS.Helper} helper
+ * @param {string} name
  */
 class Step {
   constructor(helper, name) {
+    /** @member {string} */
     this.actor = 'I'; // I = actor
+    /** @member {CodeceptJS.Helper} */
     this.helper = helper; // corresponding helper
+    /** @member {string} */
     this.name = name; // name of a step console
+    /** @member {string} */
     this.helperMethod = name; // helper method
+    /** @member {string} */
     this.status = 'pending';
+    /**
+     * @member {string} suffix
+     * @memberof CodeceptJS.Step#
+     */
+    /** @member {string} */
     this.prefix = this.suffix = '';
+    /** @member {string} */
     this.comment = '';
+    /** @member {Array<*>} */
     this.args = [];
+    /** @member {string} */
     this.stack = '';
     this.setTrace();
   }
 
+  /** @function */
   setTrace() {
     Error.captureStackTrace(this);
+    /** @member {MetaStep} */
     this.metaStep = detectMetaStep(this.stack.split('\n'));
   }
 
+  /** @param {Array<*>} args */
   setArguments(args) {
     this.args = args;
   }
 
+  /**
+   * @param {...any} args
+   * @return {*}
+   */
   run() {
     this.args = Array.prototype.slice.call(arguments);
     if (store.dryRun) {
@@ -51,11 +76,13 @@ class Step {
     return result;
   }
 
+  /** @param {string} status */
   setStatus(status) {
     this.status = status;
     if (this.metaStep) this.metaStep.setStatus(status);
   }
 
+  /** @return {string} */
   humanize() {
     return this.name
     // insert a space before all caps
@@ -66,11 +93,13 @@ class Step {
       .replace(/^(.)|\s(.)/g, $1 => $1.toLowerCase());
   }
 
+  /** @return {string} */
   humanizeArgs() {
     return this.args.map((arg) => {
       if (typeof arg === 'string') {
         return `"${arg}"`;
-      } else if (Array.isArray(arg)) {
+      }
+      if (Array.isArray(arg)) {
         try {
           const res = JSON.stringify(arg);
           return res;
@@ -92,16 +121,19 @@ class Step {
     }).join(', ');
   }
 
+  /** @return {string} */
   line() {
     const lines = this.stack.split('\n');
     if (lines[STACK_LINE]) return lines[STACK_LINE].trim();
     return '';
   }
 
+  /** @return {string} */
   toString() {
     return `${this.prefix}${this.actor} ${this.humanize()} ${this.humanizeArgs()}${this.suffix}`;
   }
 
+  /** @return {string} */
   toCode() {
     return `${this.prefix}${this.actor}.${this.name}(${this.humanizeArgs()})${this.suffix}`;
   }
@@ -110,6 +142,7 @@ class Step {
     return this.constructor.name === 'MetaStep';
   }
 
+  /** @return {boolean} */
   hasBDDAncestor() {
     let hasBDD = false;
     let processingStep;
@@ -127,7 +160,7 @@ class Step {
   }
 }
 
-
+/** @extends Step */
 class MetaStep extends Step {
   constructor(obj, method) {
     super(null, method);
@@ -141,10 +174,12 @@ class MetaStep extends Step {
   setTrace() {
   }
 
+  /** @return {void} */
   run() {
   }
 }
 
+/** @type {Class<MetaStep>} */
 Step.MetaStep = MetaStep;
 
 module.exports = Step;

package/lib/store.js

@@ -1,5 +1,9 @@
-// global values for current session
+/**
+ * global values for current session
+ * @namespace
+ */
 const store = {
+  /** @type {boolean} */
   debugMode: false,
 };
 

package/lib/ui.js

@@ -1,16 +1,12 @@
-/**
- * Module dependencies.
- */
-
+const escapeRe = require('escape-string-regexp');
 const Suite = require('mocha/lib/suite');
 const Test = require('mocha/lib/test');
+
 const scenario = require('./scenario');
 const ScenarioConfig = require('./interfaces/scenarioConfig');
 const FeatureConfig = require('./interfaces/featureConfig');
-const escapeRe = require('escape-string-regexp');
 const addDataContext = require('./data/context');
 
-
 /**
  * Codecept-style interface:
  *
@@ -21,7 +17,8 @@ const addDataContext = require('./data/context');
  *   I.see('Hello, '+data.login);
  * });
  *
- * @param {Suite} suite Root suite.
+ * @param {Mocha.Suite} suite Root suite.
+ * @ignore
  */
 module.exports = function (suite) {
   const suites = [suite];
@@ -47,7 +44,7 @@ module.exports = function (suite) {
       const test = new Test(title, fn);
       test.fullTitle = () => `${suite.title}: ${test.title}`;
 
-      test.tags = (suite.tags || []).concat(title.match(/(\@[a-zA-Z0-9-_]+)/g)); // match tags from title
+      test.tags = (suite.tags || []).concat(title.match(/(\@[a-zA-Z0-9-_]+)/g) || []); // match tags from title
       test.file = file;
       if (!test.inject) {
         test.inject = {};
@@ -71,6 +68,10 @@ module.exports = function (suite) {
      * Describe a "suite" with the given `title`
      * and callback `fn` containing nested suites
      * and/or tests.
+     * @global
+     * @param {string} title
+     * @param {Object<string, *>} [opts]
+     * @returns {FeatureConfig}
      */
 
     context.Feature = function (title, opts) {
@@ -123,10 +124,12 @@ module.exports = function (suite) {
      * Describe a specification or test-case
      * with the given `title` and callback `fn`
      * acting as a thunk.
+     * @ignore
      */
     context.Scenario = addScenario;
     /**
      * Exclusive test-case.
+     * @ignore
      */
     context.Scenario.only = function (title, opts, fn, data) {
       const reString = `^${escapeRe(`${suites[0].title}: ${title}`.replace(/( \| {.+})?$/g, ''))}`;
@@ -136,11 +139,34 @@ module.exports = function (suite) {
 
     /**
      * Pending test case.
+     * @global
+     * @kind constant
+     * @type {CodeceptJS.IScenario}
      */
     context.xScenario = context.Scenario.skip = function (title) {
       return context.Scenario(title, {});
     };
 
+    /**
+     * Pending test case with message: 'Test not implemented!'.
+     * @global
+     * @kind constant
+     * @type {CodeceptJS.IScenario}
+     */
+    context.Scenario.todo = function (title, opts = {}, fn) {
+      if (typeof opts === 'function' && !fn) {
+        fn = opts;
+        opts = {};
+      }
+
+      const skipInfo = {
+        message: 'Test not implemented!',
+        description: fn ? fn.toString() : '',
+      };
+
+      return context.Scenario(title, { ...opts, skipInfo });
+    };
+
     addDataContext(context);
   });
 

package/lib/utils.js

@@ -9,18 +9,6 @@ function isObject(item) {
   return item && typeof item === 'object' && !Array.isArray(item);
 }
 
-function flatTail(flatParams, params) {
-  const res = [];
-  for (const fp of flatParams) {
-    for (const p of params) {
-      res.push([p].concat(fp));
-    }
-  }
-  return res;
-}
-
-module.exports.flatTail = flatTail;
-
 function deepMerge(target, source) {
   const merge = require('lodash.merge');
   return merge(target, source);
@@ -222,6 +210,7 @@ function toCamelCase(name) {
     return letter.toUpperCase();
   });
 }
+module.exports.toCamelCase = toCamelCase;
 
 function convertFontWeightToNumber(name) {
   const fontWeightPatterns = [
@@ -282,13 +271,17 @@ module.exports.deleteDir = function (dir_path) {
   }
 };
 
+/**
+ * Returns absolute filename to save screenshot.
+ * @param fileName {string} - filename.
+ */
 module.exports.screenshotOutputFolder = function (fileName) {
   const fileSep = path.sep;
 
   if (!fileName.includes(fileSep) || fileName.includes('record_')) {
     return path.join(global.output_dir, fileName);
   }
-  return path.join(global.codecept_dir, fileName);
+  return path.resolve(global.codecept_dir, fileName);
 };
 
 module.exports.beautify = function (code) {

package/lib/within.js

@@ -6,6 +6,11 @@ const event = require('./event');
 const Step = require('./step');
 const { isAsyncFunction } = require('./utils');
 
+/**
+ * @param {CodeceptJS.LocatorOrString}  context
+ * @param {Function}  fn
+ * @return {Promise<*> | undefined}
+ */
 function within(context, fn) {
   const helpers = store.dryRun ? {} : container.helpers();
   const locator = typeof context === 'object' ? JSON.stringify(context) : context;