codeceptjs 3.1.2 → 3.2.2

package/docs/reports.md

@@ -7,8 +7,8 @@ title: Reporters
 
 ## Cli
 
-By default CodeceptJS provides cli reporter with console output.
-Test names and failures will be printed to screen.
+By default, CodeceptJS provides cli reporter with console output.
+Test names and failures will be printed out on screen.
 
 ```sh
 GitHub --
@@ -33,8 +33,8 @@ GitHub --
   Run with --verbose flag to see NodeJS stacktrace
 
 ```
-npx codeceptjs run --stepsutput add `--steps` option to `run` command:
-```
+
+output steps use `--steps` option:
 ```
 npx codeceptjs run --steps
 ```
@@ -201,7 +201,7 @@ npx codeceptjs dry-run --debug -p allure
 
 ## ReportPortal
 
-Allure is a great reportin tool, however, if you are running tests on different machines it is hard to merge its XML result files to build a proper report. So, for enterprise grade reporting we recommend using [ReportPortal](https://reportportal.io).
+Allure is a great reporting tool, however, if you are running tests on different machines it is hard to merge its XML result files to build a proper report. So, for enterprise grade reporting we recommend using [ReportPortal](https://reportportal.io).
 
 ![](https://camo.githubusercontent.com/6550c0365f1d0ce1e29c53f1860b12957d1fc529/68747470733a2f2f692e6962622e636f2f516d353247306e2f53637265656e73686f742d323031392d30342d31312d61742d31352d35372d34302e706e67)
 
@@ -376,3 +376,21 @@ npx codeceptjs run --reporter mocha-multi
 ```
 
 This will give you cli with steps in console and HTML report in `output` directory.
+
+
+## Testrail
+
+Testrail integration with CodeceptJS is now so seamless. The test run is created automatically afterwards. The screenshots of failed tests are also attached to test results.
+
+Try to use [codeceptjs-testrail](https://www.npmjs.com/package/codeceptjs-testrail) plugin
+
+Install it via NPM:
+
+```sh
+npm i codeceptjs-testrail --save
+```
+
+![Attachemnt for failed case](http://g.recordit.co/ajaa2QRlnW.gif)
+
+Now there is new feature, add the configuration to test run of test plan
+![Attachemnt for failed case](http://g.recordit.co/uQLvQUq7cT.gif)

package/lib/actor.js

@@ -27,8 +27,26 @@ class Actor {
   }
 
   /**
+   * set the maximum execution time for the next step
    * @function
-   * @param {*} opts
+   * @param {number} timeout - step timeout in seconds
+   * @return {this}
+   * @inner
+   */
+  limitTime(timeout) {
+    if (!store.timeouts) return this;
+
+    event.dispatcher.prependOnceListener(event.step.before, (step) => {
+      output.log(`Timeout to ${step}: ${timeout}s`);
+      step.setTimeout(timeout * 1000, Step.TIMEOUT_ORDER.codeLimitTime);
+    });
+
+    return this;
+  }
+
+  /**
+   * @function
+   * @param {*} [opts]
    * @return {this}
    * @inner
    */
@@ -114,7 +132,7 @@ function recordStep(step, args) {
       step.startTime = Date.now();
     }
     return val = step.run(...args);
-  });
+  }, false, undefined, step.getTimeout());
 
   event.emit(event.step.after, step);
 

package/lib/codecept.js

@@ -77,6 +77,7 @@ class Codecept {
       global.inject = container.support;
       global.share = container.share;
       global.secret = require('./secret').secret;
+      global.codecept_debug = output.debug;
       global.codeceptjs = require('./index'); // load all objects
 
       // BDD
@@ -95,6 +96,7 @@ class Codecept {
     runHook(require('./listener/steps'));
     runHook(require('./listener/config'));
     runHook(require('./listener/helpers'));
+    runHook(require('./listener/timeout'));
     runHook(require('./listener/exit'));
 
     // custom hooks

package/lib/command/info.js

@@ -32,7 +32,7 @@ module.exports = async function (path) {
     }
   }
   output.print('***************************************');
-  output.print('If you have questions ask them in our Slack: shorturl.at/cuKU8');
+  output.print('If you have questions ask them in our Slack: http://bit.ly/chat-codeceptjs');
   output.print('Or ask them on our discussion board: https://codecept.discourse.group/');
   output.print('Please copy environment info when you report issues on GitHub: https://github.com/Codeception/CodeceptJS/issues');
   output.print('***************************************');

package/lib/config.js

@@ -13,6 +13,7 @@ const defaultConfig = {
   include: {},
   mocha: {},
   bootstrap: null,
+  timeout: null,
   teardown: null,
   hooks: [],
   gherkin: {},
@@ -21,6 +22,17 @@ const defaultConfig = {
       enabled: true, // will be disabled by default in 2.0
     },
   },
+  stepTimeout: 0,
+  stepTimeoutOverride: [
+    {
+      pattern: 'wait.*',
+      timeout: 0,
+    },
+    {
+      pattern: 'amOnPage',
+      timeout: 0,
+    },
+  ],
 };
 
 let hooks = [];
@@ -128,7 +140,7 @@ function loadConfigFile(configFile) {
   const extensionName = path.extname(configFile);
 
   // .conf.js config file
-  if (extensionName === '.js' || extensionName === '.ts') {
+  if (extensionName === '.js' || extensionName === '.ts' || extensionName === '.cjs') {
     return Config.create(require(configFile).config);
   }
 

package/lib/container.js

@@ -7,6 +7,7 @@ const MochaFactory = require('./mochaFactory');
 const recorder = require('./recorder');
 const event = require('./event');
 const WorkerStorage = require('./workerStorage');
+const store = require('./store');
 
 let container = {
   helpers: {},
@@ -45,6 +46,7 @@ class Container {
     container.support = createSupportObjects(config.include || {});
     container.plugins = createPlugins(config.plugins || {}, opts);
     if (config.gherkin) loadGherkinSteps(config.gherkin.steps || []);
+    if (opts && typeof opts.timeouts === 'boolean') store.timeouts = opts.timeouts;
   }
 
   /**
@@ -233,7 +235,7 @@ function createSupportObjects(config) {
     const currentObject = objects[object];
     Object.keys(currentObject).forEach((method) => {
       const currentMethod = currentObject[method];
-      if (currentMethod[Symbol.toStringTag] === 'AsyncFunction') {
+      if (currentMethod && currentMethod[Symbol.toStringTag] === 'AsyncFunction') {
         objects[object][method] = asyncWrapper(currentMethod);
       }
     });

package/lib/data/dataTableArgument.js

@@ -1,4 +1,9 @@
+/**
+ * DataTableArgument class to store the Cucumber data table from
+ * a step as an object with methods that can be used to access the data.
+ */
 class DataTableArgument {
+  /** @param {*} gherkinDataTable */
   constructor(gherkinDataTable) {
     this.rawData = gherkinDataTable.rows.map((row) => {
       return row.cells.map((cell) => {
@@ -7,16 +12,25 @@ class DataTableArgument {
     });
   }
 
+  /** Returns the table as a 2-D array
+  * @returns {string[][]}
+  */
   raw() {
     return this.rawData.slice(0);
   }
 
+  /** Returns the table as a 2-D array, without the first row
+  * @returns {string[][]}
+  */
   rows() {
     const copy = this.raw();
     copy.shift();
     return copy;
   }
 
+  /** Returns an array of objects where each row is converted to an object (column header is the key)
+  * @returns {any[]}
+  */
   hashes() {
     const copy = this.raw();
     const header = copy.shift();
@@ -26,6 +40,27 @@ class DataTableArgument {
       return r;
     });
   }
+
+  /** Returns an object where each row corresponds to an entry
+   * (first column is the key, second column is the value)
+  * @returns {Record<string, string>}
+  */
+  rowsHash() {
+    const rows = this.raw();
+    const everyRowHasTwoColumns = rows.every((row) => row.length === 2);
+    if (!everyRowHasTwoColumns) {
+      throw new Error('rowsHash can only be called on a data table where all rows have exactly two columns');
+    }
+    /** @type {Record<string, string>} */
+    const result = {};
+    rows.forEach((x) => (result[x[0]] = x[1]));
+    return result;
+  }
+
+  /** Transposed the data */
+  transpose() {
+    this.rawData = this.rawData[0].map((x, i) => this.rawData.map((y) => y[i]));
+  }
 }
 
 module.exports = DataTableArgument;

package/lib/helper/Appium.js

@@ -481,10 +481,11 @@ class Appium extends Webdriver {
    * ```js
    * I.removeApp('appName', 'com.example.android.apis');
    * ```
-   * @param {string} appId
-   * @param {string}  bundleId String  ID of bundle
    *
    * Appium: support only Android
+   *
+   * @param {string} appId
+   * @param {string} [bundleId] ID of bundle
    */
   async removeApp(appId, bundleId) {
     onlyForApps.call(this, 'Android');
@@ -820,9 +821,10 @@ class Appium extends Webdriver {
    * I.hideDeviceKeyboard('pressKey', 'Done');
    * ```
    *
-   * @param {'tapOutside' | 'pressKey'} strategy  desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
-   *
    * Appium: support Android and iOS
+   *
+   * @param {'tapOutside' | 'pressKey'} [strategy] Desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
+   * @param {string} [key] Optional key
    */
   async hideDeviceKeyboard(strategy, key) {
     onlyForApps.call(this);
@@ -1162,6 +1164,8 @@ class Appium extends Webdriver {
    * ```
    *
    * Appium: support Android and iOS
+   *
+   * @param {Array} actions Array of touch actions
    */
   async touchPerform(actions) {
     onlyForApps.call(this);

package/lib/helper/FileSystem.js

@@ -91,6 +91,7 @@ class FileSystem extends Helper {
   * I.amInPath('output/downloads');
   * I.seeFileNameMatching('.pdf');
   * ```
+  * @param {string} text
   */
   seeFileNameMatching(text) {
     assert.ok(

package/lib/helper/Playwright.js

@@ -80,6 +80,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * * `basicAuth`: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
  * * `windowSize`: (optional) default window size. Set a dimension like `640x480`.
  * * `userAgent`: (optional) user-agent string.
+ * * `locale`: (optional) locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
  * * `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
  * * `chromium`: (optional) pass additional chromium options
  * * `electron`: (optional) pass additional electron options
@@ -197,6 +198,19 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * }
  * ```
  *
+ * #### Example #7: Launch test with a specifc user locale
+ *
+ * ```js
+ * {
+ *  helpers: {
+ *   Playwright : {
+ *     url: "http://localhost",
+ *     locale: "fr-FR",
+ *   }
+ *  }
+ * }
+ * ```
+ *
  * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
  *
  * ## Access From Helpers
@@ -351,9 +365,11 @@ class Playwright extends Helper {
         return err.message.includes('context');
       },
     });
+
     if (this.options.restart && !this.options.manualStart) await this._startBrowser();
     if (!this.isRunning && !this.options.manualStart) await this._startBrowser();
 
+    this.isAuthenticated = false;
     if (this.isElectron) {
       this.browserContext = this.browser.context();
     } else if (this.userDataDir) {
@@ -364,8 +380,14 @@ class Playwright extends Helper {
         acceptDownloads: true,
         ...this.options.emulate,
       };
+      if (this.options.basicAuth) {
+        contextOptions.httpCredentials = this.options.basicAuth;
+        this.isAuthenticated = true;
+      }
       if (this.options.recordVideo) contextOptions.recordVideo = this.options.recordVideo;
       if (this.storageState) contextOptions.storageState = this.storageState;
+      if (this.options.userAgent) contextOptions.userAgent = this.options.userAgent;
+      if (this.options.locale) contextOptions.locale = this.options.locale;
       this.browserContext = await this.browser.newContext(contextOptions); // Adding the HTTPSError ignore in the context so that we can ignore those errors
     }
 
@@ -557,9 +579,14 @@ class Playwright extends Helper {
     this.page = page;
     if (!page) return;
     page.setDefaultNavigationTimeout(this.options.getPageTimeout);
+
+    page.on('crash', async () => {
+      console.log('ERROR: Page has crashed, closing page!');
+      await page.close();
+    });
     this.context = await this.page;
     this.contextLocator = null;
-    if (this.config.browser === 'chrome') {
+    if (this.options.browser === 'chrome') {
       await page.bringToFront();
     }
   }
@@ -714,9 +741,9 @@ class Playwright extends Helper {
       url = this.options.url + url;
     }
 
-    if (this.config.basicAuth && (this.isAuthenticated !== true)) {
+    if (this.options.basicAuth && (this.isAuthenticated !== true)) {
       if (url.includes(this.options.url)) {
-        await this.browserContext.setHTTPCredentials(this.config.basicAuth);
+        await this.browserContext.setHTTPCredentials(this.options.basicAuth);
         this.isAuthenticated = true;
       }
     }
@@ -775,7 +802,7 @@ class Playwright extends Helper {
     if (!customHeaders) {
       throw new Error('Cannot send empty headers.');
     }
-    return this.page.setExtraHTTPHeaders(customHeaders);
+    return this.browserContext.setExtraHTTPHeaders(customHeaders);
   }
 
   /**
@@ -1851,6 +1878,11 @@ class Playwright extends Helper {
 
   async _failed(test) {
     await this._withinEnd();
+
+    if (!test.artifacts) {
+      test.artifacts = {};
+    }
+
     if (this.options.recordVideo && this.page.video()) {
       test.artifacts.video = await this.page.video().path();
     }
@@ -2136,11 +2168,11 @@ class Playwright extends Helper {
   }
 
   /**
-   * Waits for a network request.
+   * Waits for a network response.
    *
    * ```js
    * I.waitForResponse('http://example.com/resource');
-   * I.waitForResponse(request => request.url() === 'http://example.com' && request.method() === 'GET');
+   * I.waitForResponse(response => response.url() === 'https://example.com' && response.status() === 200);
    * ```
    *
    * @param {string|function} urlOrPredicate
@@ -2226,16 +2258,6 @@ class Playwright extends Helper {
     return this.page.waitForNavigation(opts);
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null) {
-    console.log('This method will remove in CodeceptJS 1.4; use `waitForFunction` instead!');
-    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
-    const context = await this._getContext();
-    return context.waitForFunction(fn, { timeout: waitTimeout });
-  }
-
   async waitUntilExists(locator, sec) {
     console.log(`waitUntilExists deprecated:
     * use 'waitForElement' to wait for element to be attached
@@ -2652,13 +2674,10 @@ async function targetCreatedHandler(page) {
       });
   });
   page.on('console', (msg) => {
-    this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg._text || '') + msg.args().join(' '));
+    this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg.text && msg.text() || msg._text || '') + msg.args().join(' '));
     consoleLogStore.add(msg);
   });
 
-  if (this.options.userAgent) {
-    await page.setUserAgent(this.options.userAgent);
-  }
   if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
     await page.setViewportSize(parseWindowSize(this.options.windowSize));
   }

package/lib/helper/Protractor.js

@@ -838,11 +838,7 @@ class Protractor extends Helper {
   }
 
   /**
-   * Checks that title is equal to provided one.
-   *
-   * ```js
-   * I.seeTitleEquals('Test title.');
-   * ```
+   * {{> seeTitleEquals }}
    */
   async seeTitleEquals(text) {
     const title = await this.browser.getTitle();
@@ -1018,7 +1014,7 @@ class Protractor extends Helper {
   }
 
   /**
-     * {{> seeInCurrentUrl }}
+   * {{> seeInCurrentUrl }}
    */
   async seeInCurrentUrl(url) {
     return this.browser.getCurrentUrl().then(currentUrl => stringIncludes('url').assert(url, currentUrl));
@@ -1498,14 +1494,6 @@ class Protractor extends Helper {
     return this.browser.wait(() => this.browser.executeScript.call(this.browser, fn, ...args), aSec * 1000);
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null, timeoutMsg = null) {
-    const aSec = sec || this.options.waitForTimeout;
-    return this.browser.wait(fn, aSec * 1000, timeoutMsg);
-  }
-
   /**
    * {{> waitInUrl }}
    */

package/lib/helper/Puppeteer.js

@@ -264,7 +264,7 @@ class Puppeteer extends Helper {
   async _before() {
     this.sessionPages = {};
     recorder.retry({
-      retries: 5,
+      retries: 3,
       when: err => {
         if (!err || typeof (err.message) !== 'string') {
           return false;
@@ -554,10 +554,9 @@ class Puppeteer extends Helper {
     this.context = null;
     popupStore.clear();
     this.isAuthenticated = false;
+    await this.browser.close();
     if (this.isRemoteBrowser) {
       await this.browser.disconnect();
-    } else {
-      await this.browser.close();
     }
   }
 
@@ -774,11 +773,7 @@ class Puppeteer extends Helper {
   }
 
   /**
-   * Checks that title is equal to provided one.
-   *
-   * ```js
-   * I.seeTitleEquals('Test title.');
-   * ```
+   * {{> seeTitleEquals }}
    */
   async seeTitleEquals(text) {
     const title = await this.page.title();
@@ -2220,16 +2215,6 @@ class Puppeteer extends Helper {
     return this.page.waitForNavigation(opts);
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null) {
-    console.log('This method will remove in CodeceptJS 1.4; use `waitForFunction` instead!');
-    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
-    const context = await this._getContext();
-    return context.waitForFunction(fn, { timeout: waitTimeout });
-  }
-
   async waitUntilExists(locator, sec) {
     console.log(`waitUntilExists deprecated:
     * use 'waitForElement' to wait for element to be attached

package/lib/helper/REST.js

@@ -131,6 +131,7 @@ class REST extends Helper {
    * I.setRequestTimeout(10000); // In milliseconds
    * ```
    *
+   * @param {number} newTimeout - timeout in milliseconds
    */
   setRequestTimeout(newTimeout) {
     this.options.timeout = newTimeout;

package/lib/helper/WebDriver.js

@@ -481,7 +481,7 @@ class WebDriver extends Helper {
     try {
       require('webdriverio');
     } catch (e) {
-      return ['webdriverio@^5.2.2'];
+      return ['webdriverio@^6.12.1'];
     }
   }
 
@@ -582,7 +582,7 @@ class WebDriver extends Helper {
     this.context = this.root;
     if (this.options.restart && !this.options.manualStart) return this._startBrowser();
     if (!this.isRunning && !this.options.manualStart) return this._startBrowser();
-    this.$$ = this.browser.$$.bind(this.browser);
+    if (this.browser) this.$$ = this.browser.$$.bind(this.browser);
     return this.browser;
   }
 
@@ -875,7 +875,7 @@ class WebDriver extends Helper {
    * I.defineTimeout({ implicit: 10000, pageLoad: 10000, script: 5000 });
    * ```
    *
-   * @param {WebdriverIO.Timeouts} timeouts WebDriver timeouts object.
+   * @param {*} timeouts WebDriver timeouts object.
    */
   defineTimeout(timeouts) {
     return this._defineBrowserTimeout(this.browser, timeouts);
@@ -2353,18 +2353,6 @@ class WebDriver extends Helper {
     return this.browser.waitUntil(async () => this.browser.execute(fn, ...args), { timeout: aSec * 1000, timeoutMsg: '' });
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null, timeoutMsg = null, interval = null) {
-    const aSec = sec || this.options.waitForTimeout;
-    const _interval = typeof interval === 'number' ? interval * 1000 : null;
-    if (isWebDriver5()) {
-      return this.browser.waitUntil(fn, aSec * 1000, timeoutMsg, _interval);
-    }
-    return this.browser.waitUntil(fn, { timeout: aSec * 1000, timeoutMsg, interval: _interval });
-  }
-
   /**
    * {{> switchTo }}
    */

package/lib/index.js

@@ -32,6 +32,8 @@ module.exports = {
   within: require('./within'),
   /**  @type {typeof CodeceptJS.DataTable} */
   dataTable: require('./data/table'),
+  /**  @type {typeof CodeceptJS.DataTableArgument} */
+  dataTableArgument: require('./data/dataTableArgument'),
   /** @type {typeof CodeceptJS.store} */
   store: require('./store'),
   /** @type {typeof CodeceptJS.Locator} */

package/lib/interfaces/featureConfig.js

@@ -21,6 +21,9 @@ class FeatureConfig {
    * @returns {this}
    */
   timeout(timeout) {
+    console.log(`Feature('${this.suite.title}').timeout(${timeout}) is deprecated!`);
+    console.log(`Please use Feature('${this.suite.title}', { timeout: ${timeout / 1000} }) instead`);
+    console.log('Timeout should be set in seconds');
     this.suite.timeout(timeout);
     return this;
   }

package/lib/interfaces/gherkin.js

@@ -11,15 +11,19 @@ const transform = require('../transform');
 const parser = new Parser();
 parser.stopAtFirstError = false;
 
-module.exports = (text) => {
+module.exports = (text, file) => {
   const ast = parser.parse(text);
 
+  if (!ast.feature) {
+    throw new Error(`No 'Features' available in Gherkin '${file}' provided!`);
+  }
   const suite = new Suite(ast.feature.name, new Context());
   const tags = ast.feature.tags.map(t => t.name);
   suite.title = `${suite.title} ${tags.join(' ')}`.trim();
   suite.tags = tags || [];
   suite.comment = ast.feature.description;
   suite.feature = ast.feature;
+  suite.file = file;
   suite.timeout(0);
 
   suite.beforeEach('codeceptjs.before', () => scenario.setup(suite));
@@ -95,6 +99,7 @@ module.exports = (text) => {
           const title = `${child.name} ${JSON.stringify(current)} ${tags.join(' ')}`.trim();
           const test = new Test(title, async () => runSteps(addExampleInTable(exampleSteps, current)));
           test.tags = suite.tags.concat(tags);
+          test.file = file;
           suite.addTest(scenario.test(test));
         }
       }
@@ -104,6 +109,7 @@ module.exports = (text) => {
     const title = `${child.name} ${tags.join(' ')}`.trim();
     const test = new Test(title, async () => runSteps(child.steps));
     test.tags = suite.tags.concat(tags);
+    test.file = file;
     suite.addTest(scenario.test(test));
   }
 

package/lib/interfaces/scenarioConfig.js

@@ -45,6 +45,10 @@ class ScenarioConfig {
    * @returns {this}
    */
   timeout(timeout) {
+    console.log(`Scenario('${this.test.title}', () => {}).timeout(${timeout}) is deprecated!`);
+    console.log(`Please use Scenario('${this.test.title}', { timeout: ${timeout / 1000} }, () => {}) instead`);
+    console.log('Timeout should be set in seconds');
+
     this.test.timeout(timeout);
     return this;
   }

package/lib/listener/helpers.js

@@ -1,3 +1,4 @@
+const path = require('path');
 const event = require('../event');
 const container = require('../container');
 const recorder = require('../recorder');