codeceptjs 2.3.4 → 2.4.1

package/lib/locator.js

@@ -1,8 +1,14 @@
 const cssToXPath = require('css-to-xpath');
-const xpathLocator = require('./utils').xpathLocator;
 const sprintf = require('sprintf-js').sprintf;
 
+const xpathLocator = require('./utils').xpathLocator;
+
+/** @class */
 class Locator {
+  /**
+   * @param {CodeceptJS.LocatorOrString}  locator
+   * @param {string}  [defaultType]
+   */
   constructor(locator, defaultType = '') {
     this.type = null;
     if (!locator) return;
@@ -63,6 +69,9 @@ class Locator {
     return { [this.type]: this.value };
   }
 
+  /**
+   * @return  {string}
+   */
   toString() {
     return this.output || `{${this.type}: ${this.value}}`;
   }
@@ -95,6 +104,9 @@ class Locator {
     return this.isFuzzy() && this.value[0] === '~';
   }
 
+  /**
+   * @return  {string}
+   */
   toXPath() {
     if (this.isXPath()) return this.value;
     if (this.isCSS()) return cssToXPath(this.value);
@@ -102,6 +114,10 @@ class Locator {
   }
 
   // DSL
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   or(locator) {
     const xpath = xpathLocator.combine([
       this.toXPath(),
@@ -110,21 +126,37 @@ class Locator {
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   find(locator) {
     const xpath = sprintf('%s//%s', this.toXPath(), convertToSubSelector(locator));
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   withChild(locator) {
     const xpath = sprintf('%s[./child::%s]', this.toXPath(), convertToSubSelector(locator));
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   withDescendant(locator) {
     const xpath = sprintf('%s[./descendant::%s]', this.toXPath(), convertToSubSelector(locator));
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {number}  position
+   * @return {Locator}
+   */
   at(position) {
     if (position < 0) {
       position++; // -1 points to the last element
@@ -137,20 +169,34 @@ class Locator {
     return new Locator({ xpath });
   }
 
+  /**
+   * @return  {Locator}
+   */
   first() {
     return this.at(1);
   }
 
+  /**
+   * @return  {Locator}
+   */
   last() {
     return this.at(-1);
   }
 
+  /**
+   * @param {string} text
+   * @return  {Locator}
+   */
   withText(text) {
     text = xpathLocator.literal(text);
     const xpath = sprintf('%s[%s]', this.toXPath(), `contains(., ${text})`);
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {Object.<string, string>} attrs
+   * @return  {Locator}
+   */
   withAttr(attrs) {
     const operands = [];
     for (const attr of Object.keys(attrs)) {
@@ -160,27 +206,47 @@ class Locator {
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {string} output
+   * @return  {Locator}
+   */
   as(output) {
     this.output = output;
     return this;
   }
 
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   inside(locator) {
     const xpath = sprintf('%s[ancestor::%s]', this.toXPath(), convertToSubSelector(locator));
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   after(locator) {
     const xpath = sprintf('%s[preceding-sibling::%s]', this.toXPath(), convertToSubSelector(locator));
     return new Locator({ xpath });
   }
 
+  /**
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @return  {Locator}
+   */
   before(locator) {
     const xpath = sprintf('%s[following-sibling::%s]', this.toXPath(), convertToSubSelector(locator));
     return new Locator({ xpath });
   }
 }
 
+/**
+ * @param {CodeceptJS.LocatorOrString} locator
+ * @returns {Locator}
+ */
 Locator.build = (locator) => {
   if (!locator) return new Locator({ xpath: '//*' });
   return new Locator(locator, 'css');
@@ -190,7 +256,6 @@ Locator.filters = [];
 
 Locator.addFilter = fn => Locator.filters.push(fn);
 
-
 Locator.clickable = {
   narrow: literal => xpathLocator.combine([
     `.//a[normalize-space(.)=${literal}]`,

package/lib/output.js

@@ -15,14 +15,21 @@ let outputLevel = 0;
 let outputProcess = '';
 let newline = true;
 
+/**
+ * @alias output
+ * @namespace
+ */
 module.exports = {
   colors,
   styles,
   print,
+  /** @type {number} */
   stepShift: 0,
 
   /**
    * Set or return current verbosity level
+   * @param {number} level
+   * @return {number}
    */
   level(level) {
     if (level !== undefined) outputLevel = level;
@@ -32,6 +39,8 @@ module.exports = {
   /**
    * Print information for a process
    * Used in multiple-run
+   * @param {string} process
+   * @return {string}
    */
   process(process) {
     if (process === null) return outputProcess = '';
@@ -41,6 +50,7 @@ module.exports = {
 
   /**
    * Print information in --debug mode
+   * @param {string} msg
    */
   debug(msg) {
     if (outputLevel >= 2) {
@@ -50,6 +60,7 @@ module.exports = {
 
   /**
    * Print information in --verbose mode
+   * @param {string} msg
    */
   log(msg) {
     if (outputLevel >= 3) print(' '.repeat(this.stepShift), styles.log(truncate(`   ${msg}`, this.spaceShift)));
@@ -57,6 +68,7 @@ module.exports = {
 
   /**
    * Print error
+   * @param {string} msg
    */
   error(msg) {
     print(styles.error(msg));
@@ -64,17 +76,23 @@ module.exports = {
 
   /**
    * Print a successful message
+   * @param {string} msg
    */
   success(msg) {
     print(styles.success(msg));
   },
 
+  /**
+   * @param {string} name
+   * @param {string} msg
+   */
   plugin(name, msg) {
     this.debug(`<${name}> ${msg}`);
   },
 
   /**
    * Print a step
+   * @param {CodeceptJS.Step} step
    */
   step(step) {
     if (outputLevel === 0) return;
@@ -98,7 +116,11 @@ module.exports = {
     print(' '.repeat(this.stepShift), truncate(stepLine, this.spaceShift));
   },
 
+  /** @namespace */
   suite: {
+    /**
+     * @param {Mocha.Suite} suite
+     */
     started: (suite) => {
       if (!suite.title) return;
       print(`${colors.bold(suite.title)} --`);
@@ -106,27 +128,50 @@ module.exports = {
     },
   },
 
+  /** @namespace */
   test: {
+    /**
+     * @param {Mocha.Test} test
+     */
     started(test) {
       print(`  ${colors.magenta.bold(test.title)}`);
     },
+    /**
+     * @param {Mocha.Test} test
+     */
     passed(test) {
       print(`  ${colors.green.bold(figures.tick)} ${test.title} ${colors.grey(`in ${test.duration}ms`)}`);
     },
+    /**
+     * @param {Mocha.Test} test
+     */
     failed(test) {
       print(`  ${colors.red.bold(figures.cross)} ${test.title} ${colors.grey(`in ${test.duration}ms`)}`);
     },
+    /**
+     * @param {Mocha.Test} test
+     */
     skipped(test) {
       print(`  ${colors.yellow.bold('S')} ${test.title}`);
     },
   },
 
+  /** @namespace */
   scenario: {
+    /**
+     * @param {Mocha.Test} test
+     */
     started(test) {},
+    /**
+     * @param {Mocha.Test} test
+     */
     passed(test) {
       print(`  ${colors.green.bold(`${figures.tick} OK`)} ${colors.grey(`in ${test.duration}ms`)}`);
       print();
     },
+    /**
+     * @param {Mocha.Test} test
+     */
     failed(test) {
       print(`  ${colors.red.bold(`${figures.cross} FAILED`)} ${colors.grey(`in ${test.duration}ms`)}`);
       print();
@@ -136,11 +181,19 @@ module.exports = {
   /**
    *
    * Print a text in console log
+   * @param {string} message
+   * @param {string} [color]
    */
   say(message, color = 'cyan') {
     if (outputLevel >= 1) print(`   ${colors[color].bold(message)}`);
   },
 
+  /**
+   * @param {number} passed
+   * @param {number} failed
+   * @param {number} skipped
+   * @param {number} duration
+   */
   result(passed, failed, skipped, duration) {
     let style = colors.bgGreen;
     let msg = ` ${passed || 0} passed`;

package/lib/parser.js

@@ -1,78 +1,10 @@
-const parser = require('parse-function')({ ecmaVersion: 2017 });
-const { flatTail } = require('./utils');
+function _interopDefault(ex) { return (ex && (typeof ex === 'object') && 'default' in ex) ? ex.default : ex; }
+const parser = _interopDefault(require('parse-function'))({ ecmaVersion: 2017 });
 
 module.exports.getParamsToString = function (fn) {
   return getParams(fn).join(', ');
 };
 
-module.exports.toTypeDef = function (fn) {
-  const types = [];
-  const paramNames = [];
-  const params = getParams(fn);
-  for (const key in params) {
-    let paramName = params[key];
-    const paramValue = paramName.split('=');
-    const isOptional = paramValue.length !== 1;
-    if (isOptional) {
-      paramName = paramValue[0];
-    }
-    paramNames[key] = paramName;
-    if (isOptional) {
-      paramNames[key] += '?';
-    }
-    types[key] = guessParamTypes(paramName);
-  }
-
-  let combinedTypes = types[types.length - 1];
-  if (!combinedTypes) return methodSignature(fn);
-  if (types.length === 1) {
-    return combinedTypes.map(type => methodSignature(fn, paramNames, [type])).join('');
-  }
-
-  for (let i = types.length - 2; i >= 0; i--) {
-    combinedTypes = flatTail(combinedTypes, types[i]);
-  }
-  return combinedTypes.map(type => methodSignature(fn, paramNames, type)).join('');
-};
-
-function methodSignature(fn, paramNames, params) {
-  if (!fn.name) return;
-  if (!params) params = [];
-  params = params.map((p, i) => `${paramNames[i]}: ${p}`).join(', ');
-  let returnType = 'void';
-  if (fn.name.indexOf('grab') === 0) {
-    if (fn.name.indexOf('BrowserLog') > 0 || fn.name.indexOf('ScrollPosition') > 0) {
-      returnType = 'Promise<object>';
-    }
-    if (fn.name.indexOf('Number') > 0) {
-      returnType = 'Promise<number>';
-    }
-    returnType = 'Promise<string>';
-  }
-  return `    ${fn.name}(${params}) : ${returnType},\n`;
-}
-
-function guessParamTypes(paramName) {
-  switch (paramName) {
-    case 'fn':
-      return ['Function'];
-    case 'locator':
-    case 'field':
-    case 'context':
-    case 'select':
-      return ['LocatorOrString'];
-    case 'num':
-    case 'sec':
-    case 'width':
-    case 'height':
-    case 'offset':
-    case 'offsetX':
-    case 'offsetY':
-      return ['number'];
-  }
-  return ['string'];
-}
-
 function getParams(fn) {
   if (fn.isSinonProxy) return [];
   const newFn = fn.toString().replace(/^async/, 'async function');
@@ -91,4 +23,3 @@ function getParams(fn) {
     console.error(err);
   }
 }
-

package/lib/pause.js

@@ -1,3 +1,6 @@
+const colors = require('chalk');
+const readline = require('readline');
+
 const container = require('./container');
 const history = require('./history');
 const store = require('./store');
@@ -6,8 +9,6 @@ const event = require('./event');
 const output = require('./output');
 const methodsOfObject = require('./utils').methodsOfObject;
 
-const readline = require('readline');
-const colors = require('chalk');
 // npm install colors
 let rl;
 let nextStep;

package/lib/plugin/allure.js

@@ -1,5 +1,6 @@
-const event = require('../event');
 const Allure = require('allure-js-commons');
+
+const event = require('../event');
 const logger = require('../output');
 const ansiRegExp = require('../utils').ansiRegExp;
 
@@ -73,6 +74,8 @@ const defaultConfig = {
 module.exports = (config) => {
   config = Object.assign(defaultConfig, config);
 
+  const plugin = {};
+
   const reporter = new Allure();
   reporter.setOptions({ targetDir: config.outputDir });
 
@@ -80,15 +83,31 @@ module.exports = (config) => {
   let currentStep;
   let isHookSteps = false;
 
-  this.addAttachment = (name, buffer, type) => {
+  reporter.pendingCase = function (testName, timestamp, opts = {}) {
+    reporter.startCase(testName, timestamp);
+
+    if (opts.description) plugin.setDescription(opts.description);
+    if (opts.severity) plugin.severity(opts.severity);
+    if (opts.severity) plugin.addLabel('tag', opts.severity);
+
+    reporter.endCase('pending', { message: opts.message || 'Test ignored' }, timestamp);
+  };
+
+  plugin.addAttachment = (name, buffer, type) => {
     reporter.addAttachment(name, buffer, type);
   };
 
-  this.setDescription = (description, type) => {
-    reporter.setDescription(description, type);
+  plugin.setDescription = (description, type) => {
+    const currentTest = reporter.getCurrentTest();
+    if (currentTest) {
+      currentTest.setDescription(description, type);
+    } else {
+      logger.error(`The test is not run. Please use "setDescription" for events:
+      "test.start", "test.before", "test.after", "test.passed", "test.failed", "test.finish"`);
+    }
   };
 
-  this.createStep = (name, stepFunc = () => {}) => {
+  plugin.createStep = (name, stepFunc = () => {}) => {
     let result;
     let status = 'passed';
     reporter.startStep(name);
@@ -110,7 +129,7 @@ module.exports = (config) => {
     return result;
   };
 
-  this.createAttachment = (name, content, type) => {
+  plugin.createAttachment = (name, content, type) => {
     if (typeof content === 'function') {
       const attachmentName = name;
       const buffer = content.apply(this, arguments);
@@ -118,27 +137,27 @@ module.exports = (config) => {
     } reporter.addAttachment(name, content, type);
   };
 
-  this.severity = (severity) => {
-    this.addLabel('severity', severity);
+  plugin.severity = (severity) => {
+    plugin.addLabel('severity', severity);
   };
 
-  this.epic = (epic) => {
-    this.addLabel('epic', epic);
+  plugin.epic = (epic) => {
+    plugin.addLabel('epic', epic);
   };
 
-  this.feature = (feature) => {
-    this.addLabel('feature', feature);
+  plugin.feature = (feature) => {
+    plugin.addLabel('feature', feature);
   };
 
-  this.story = (story) => {
-    this.addLabel('story', story);
+  plugin.story = (story) => {
+    plugin.addLabel('story', story);
   };
 
-  this.issue = (issue) => {
-    this.addLabel('issue', issue);
+  plugin.issue = (issue) => {
+    plugin.addLabel('issue', issue);
   };
 
-  this.addLabel = (name, value) => {
+  plugin.addLabel = (name, value) => {
     const currentTest = reporter.getCurrentTest();
     if (currentTest) {
       currentTest.addLabel(name, value);
@@ -155,16 +174,16 @@ module.exports = (config) => {
   event.dispatcher.on(event.suite.before, (suite) => {
     for (const test of suite.tests) {
       if (test.pending) {
-        reporter.pendingCase(test.title);
+        reporter.pendingCase(test.title, null, test.opts.skipInfo);
       }
     }
   });
 
-  event.dispatcher.on(event.hook.started, (hook) => {
+  event.dispatcher.on(event.hook.started, () => {
     isHookSteps = true;
   });
 
-  event.dispatcher.on(event.hook.passed, (hook) => {
+  event.dispatcher.on(event.hook.passed, () => {
     isHookSteps = false;
   });
 
@@ -199,7 +218,7 @@ module.exports = (config) => {
     reporter.endCase('failed', err);
   });
 
-  event.dispatcher.on(event.test.passed, (test) => {
+  event.dispatcher.on(event.test.passed, () => {
     if (currentStep) reporter.endStep('passed');
     if (currentMetaStep.length) {
       currentMetaStep.forEach(() => reporter.endStep('passed'));
@@ -262,5 +281,5 @@ module.exports = (config) => {
     }
   }
 
-  return this;
+  return plugin;
 };

package/lib/plugin/autoLogin.js

@@ -217,7 +217,10 @@ const defaultConfig = {
 */
 module.exports = function (config) {
   config = Object.assign(defaultConfig, config);
-  Object.keys(config.users).map(u => config.users[u] = Object.assign({}, defaultUser, config.users[u]));
+  Object.keys(config.users).map(u => config.users[u] = {
+    ...defaultUser,
+    ...config.users[u],
+  });
 
   if (config.saveToFile) {
     // loading from file

package/lib/plugin/pauseOnFail.js

@@ -0,0 +1,38 @@
+const event = require('../event');
+const pause = require('../pause');
+
+/**
+ * Automatically launches [interactive pause](/basics/#pause) when a test fails.
+ *
+ * Useful for debugging flaky tests on local environment.
+ * Add this plugin to config file:
+ *
+ * ```js
+ * plugins: {
+ *   pauseOnFail: {},
+ * }
+ * ```
+ *
+ * Unlike other plugins, `pauseOnFail` is not recommended to be enabled by default.
+ * Enable it manually on each run via `-p` option:
+ *
+ * ```
+ * npx codeceptjs run -p pauseOnFail
+ * ```
+ *
+ */
+module.exports = (config) => {
+  let failed = false;
+
+  event.dispatcher.on(event.test.started, (step) => {
+    failed = false;
+  });
+
+  event.dispatcher.on(event.step.failed, (step) => {
+    failed = true;
+  });
+
+  event.dispatcher.on(event.test.after, (step) => {
+    if (failed) pause();
+  });
+};

package/lib/plugin/puppeteerCoverage.js

@@ -1,11 +1,12 @@
+const debug = require('debug')('codeceptjs:plugin:puppeteerCoverage');
+const fs = require('fs');
+const path = require('path');
+
 const Container = require('../container');
 const recorder = require('../recorder');
 const event = require('../event');
 const output = require('../output');
-const fs = require('fs');
-const path = require('path');
 const { clearString } = require('../utils');
-const debug = require('debug')('codeceptjs:plugin:puppeteerCoverage');
 
 const defaultConfig = {
   coverageDir: 'output/coverage',
@@ -27,10 +28,10 @@ function buildFileName(test, uniqueFileName) {
   }
 
   if (uniqueFileName) {
-    const uuid =
-      test.uuid ||
-      test.ctx.test.uuid ||
-      Math.floor(new Date().getTime() / 1000);
+    const uuid = test.uuid
+      || test.ctx.test.uuid
+      || Math.floor(new Date().getTime() / 1000);
+
     fileName = `${fileName.substring(0, 10)}_${uuid}.coverage.json`;
   } else {
     fileName = `${fileName}.coverage.json`;

package/lib/plugin/screenshotOnFail.js

@@ -1,9 +1,10 @@
+const fs = require('fs');
+const path = require('path');
+
 const Container = require('../container');
 const recorder = require('../recorder');
 const event = require('../event');
 const output = require('../output');
-const fs = require('fs');
-const path = require('path');
 const { fileExists, clearString } = require('../utils');
 const Codeceptjs = require('../index');
 
@@ -99,7 +100,7 @@ module.exports = function (config) {
       try {
         if (options.reportDir) {
           fileName = path.join(options.reportDir, fileName);
-          const mochaReportDir = path.join(process.cwd(), options.reportDir);
+          const mochaReportDir = path.resolve(process.cwd(), options.reportDir);
           if (!fileExists(mochaReportDir)) {
             fs.mkdirSync(mochaReportDir);
           }
@@ -115,11 +116,15 @@ module.exports = function (config) {
           allureReporter.addAttachment('Last Seen Screenshot', fs.readFileSync(path.join(global.output_dir, fileName)), 'image/png');
         }
       } catch (err) {
-        if (err &&
-            err.type &&
-            err.type === 'RuntimeError' &&
-            err.message &&
-            (err.message.indexOf('was terminated due to') > -1 || err.message.indexOf('no such window: target window already closed') > -1)
+        if (
+          err
+          && err.type
+          && err.type === 'RuntimeError'
+          && err.message
+          && (
+            err.message.indexOf('was terminated due to') > -1
+            || err.message.indexOf('no such window: target window already closed') > -1
+          )
         ) {
           helper.isRunning = false;
         }