codeceptjs 3.1.1 → 3.2.1

package/docs/plugins.md

@@ -409,6 +409,29 @@ Scenario('project update test', async (I) => {
 
 -   `config`  
 
+## coverage
+
+Dumps code coverage from Playwright/Puppeteer after every test.
+
+#### Configuration
+
+```js
+plugins: {
+   coverage: {
+     enabled: true
+   }
+}
+```
+
+Possible config options:
+
+-   `coverageDir`: directory to dump coverage files
+-   `uniqueFileName`: generate a unique filename by adding uuid
+
+### Parameters
+
+-   `config`  
+
 ## customLocator
 
 Creates a [custom locator][3] by using special attributes in HTML.
@@ -441,7 +464,7 @@ Using `data-test` attribute with `$` prefix:
 // in codecept.conf.js
 plugins: {
  customLocator: {
-   enabled: true
+   enabled: true,
    attribute: 'data-test'
  }
 }
@@ -460,7 +483,7 @@ Using `data-qa` attribute with `=` prefix:
 // in codecept.conf.js
 plugins: {
  customLocator: {
-   enabled: true
+   enabled: true,
    prefix: '=',
    attribute: 'data-qa'
  }
@@ -536,45 +559,6 @@ Enable it manually on each run via `-p` option:
 
     npx codeceptjs run -p pauseOnFail
 
-## puppeteerCoverage
-
-Dumps puppeteers code coverage after every test.
-
-#### Configuration
-
-Configuration can either be taken from a corresponding helper (deprecated) or a from plugin config (recommended).
-
-```js
-plugins: {
-   puppeteerCoverage: {
-     enabled: true
-   }
-}
-```
-
-Possible config options:
-
--   `coverageDir`: directory to dump coverage files
--   `uniqueFileName`: generate a unique filename by adding uuid
-
-    First of all, your mileage may vary!
-
-    To work, you need the client javascript code to be NOT uglified. They need to be built in "development" mode.
-    And the end of your tests, you'll get a directory full of coverage per test run.  Now what?
-    You'll need to convert the coverage code to something istanbul can read.  Good news is someone wrote the code
-    for you (see puppeteer-to-istanbul link below).  Then using istanbul you need to combine the converted
-    coverage and create a report.  Good luck!
-
-    Links:
-
--   [https://github.com/GoogleChrome/puppeteer/blob/v1.12.2/docs/api.md#class-coverage][7]
--   [https://github.com/istanbuljs/puppeteer-to-istanbul][8]
--   [https://github.com/gotwarlost/istanbul][9]
-
-### Parameters
-
--   `config`  
-
 ## retryFailedStep
 
 Retries each failed step in a test.
@@ -595,9 +579,9 @@ Run tests with plugin enabled:
 
 #### Configuration:
 
--   `retries` - number of retries (by default 5),
+-   `retries` - number of retries (by default 3),
 -   `when` - function, when to perform a retry (accepts error as parameter)
--   `factor` - The exponential factor to use. Default is 2.
+-   `factor` - The exponential factor to use. Default is 1.5.
 -   `minTimeout` - The number of milliseconds before starting the first retry. Default is 1000.
 -   `maxTimeout` - The maximum number of milliseconds between two retries. Default is Infinity.
 -   `randomize` - Randomizes the timeouts by multiplying with a factor between 1 to 2. Default is false.
@@ -642,6 +626,75 @@ Scenario('scenario tite', () => {
 
 -   `config`  
 
+## retryTo
+
+Adds global `retryTo` which retries steps a few times before failing.
+
+Enable this plugin in `codecept.conf.js` (enabled by default for new setups):
+
+```js
+plugins: {
+  retryTo: {
+    enabled: true
+  }
+}
+```
+
+Use it in your tests:
+
+```js
+// retry these steps 5 times before failing
+await retryTo((tryNum) => {
+  I.switchTo('#editor frame');
+  I.click('Open');
+  I.see('Opened')
+}, 5);
+```
+
+Set polling interval as 3rd argument (200ms by default):
+
+```js
+// retry these steps 5 times before failing
+await retryTo((tryNum) => {
+  I.switchTo('#editor frame');
+  I.click('Open');
+  I.see('Opened')
+}, 5, 100);
+```
+
+Default polling interval can be changed in a config:
+
+```js
+plugins: {
+  retryTo: {
+    enabled: true,
+    pollInterval: 500,
+  }
+}
+```
+
+Disables retryFailedStep plugin for steps inside a block;
+
+Use this plugin if:
+
+-   you need repeat a set of actions in flaky tests
+-   iframe was not rendered and you need to retry switching to it
+
+#### Configuration
+
+-   `pollInterval` - default interval between retries in ms. 200 by default.
+-   `registerGlobal` - to register `retryTo` function globally, true by default
+
+If `registerGlobal` is false you can use retryTo from the plugin:
+
+```js
+const retryTo = codeceptjs.container.plugins('retryTo');
+```
+
+### Parameters
+
+-   `config`  
+
 ## screenshotOnFail
 
 Creates screenshot on failure. Screenshot is saved into `output` directory.
@@ -673,14 +726,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][10] plugin automatically starts browsers and video recording.
+[Selenoid][7] plugin automatically starts browsers and video recording.
 Works with WebDriver helper.
 
 ### Prerequisite
 
 This plugin **requires Docker** to be installed.
 
-> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][11] tool from Selenoid
+> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][8] tool from Selenoid
 
 ### Usage
 
@@ -709,7 +762,7 @@ plugins: {
   }
 ```
 
-When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][12] and start Selenoid automatically.
+When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][9] and start Selenoid automatically.
 It will also create `browsers.json` file required by Selenoid.
 
 In automatic mode the latest version of browser will be used for tests. It is recommended to specify exact version of each browser inside `browsers.json` file.
@@ -721,10 +774,10 @@ In automatic mode the latest version of browser will be used for tests. It is re
 While this plugin can create containers for you for better control it is recommended to create and launch containers manually.
 This is especially useful for Continous Integration server as you can configure scaling for Selenoid containers.
 
-> Use [Selenoid Configuration Manager][11] to create and start containers semi-automatically.
+> Use [Selenoid Configuration Manager][8] to create and start containers semi-automatically.
 
 1.  Create `browsers.json` file in the same directory `codecept.conf.js` is located
-    [Refer to Selenoid documentation][13] to know more about browsers.json.
+    [Refer to Selenoid documentation][10] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -749,7 +802,7 @@ _Sample browsers.json_
 
 2.  Create Selenoid container
 
-Run the following command to create a container. To know more [refer here][14]
+Run the following command to create a container. To know more [refer here][11]
 
 ```bash
 docker create                                    \
@@ -782,7 +835,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 | enableVideo      | Enable video recording and use `video` folder of output (default: false)       |
 | enableLog        | Enable log recording and use `logs` folder of output (default: false)          |
 | deletePassed     | Delete video and logs of passed tests (default : true)                         |
-| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][15] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][12] to know more   |
 
 ### Parameters
 
@@ -790,7 +843,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 
 ## stepByStepReport
 
-![step-by-step-report][16]
+![step-by-step-report][13]
 
 Generates step by step report for a test.
 After each step in a test a screenshot is created. After test executed screenshots are combined into slideshow.
@@ -818,11 +871,81 @@ Possible config options:
 -   `fullPageScreenshots`: should full page screenshots be used. Default: false.
 -   `output`: a directory where reports should be stored. Default: `output`.
 -   `screenshotsForAllureReport`: If Allure plugin is enabled this plugin attaches each saved screenshot to allure report. Default: false.
+-   \`disableScreenshotOnFail : Disables the capturing of screeshots after the failed step. Default: true.
 
 ### Parameters
 
 -   `config` **any** 
 
+## stepTimeout
+
+Set timeout for test steps globally.
+
+Add this plugin to config file:
+
+```js
+plugins: {
+    stepTimeout: {
+       enabled: true
+    }
+}
+```
+
+Run tests with plugin enabled:
+
+    npx codeceptjs run --plugins stepTimeout
+
+#### Configuration:
+
+-   `timeout` - global step timeout, default 150 seconds
+-   `force` - whether to use timeouts set in plugin config to override step timeouts set in code with I.limitTime(x).action(...), default false
+-   `noTimeoutSteps` - an array of steps with no timeout. Default:
+
+    -   `amOnPage`
+    -   `wait*`
+
+    you could set your own noTimeoutSteps which would replace the default one.
+
+-   `customTimeoutSteps` - an array of step actions with custom timeout. Use it to override or extend noTimeoutSteps.
+    You can use step names or step prefixes ending with `*`. As such, `wait*` will match all steps starting with `wait`.
+
+#### Example
+
+```js
+plugins: {
+    stepTimeout: {
+        enabled: true,
+        force: true,
+        noTimeoutSteps: [
+          'scroll*', // ignore all scroll steps
+          /Cookie/, // ignore all steps with a Cookie in it (by regexp)
+        ],
+        customTimeoutSteps: [
+          ['myFlakyStep*', 1],
+          ['scrollWhichRequiresTimeout', 5],
+        ]
+    }
+}
+```
+
+### Parameters
+
+-   `config`  
+
+## subtitles
+
+Automatically captures steps as subtitle, and saves it as an artifact when a video is found for a failed test
+
+#### Configuration
+
+```js
+plugins: {
+ subtitles: {
+   enabled: true
+ }
+}
+```
+
 ## tryTo
 
 Adds global `tryTo` function inside of which all failed steps won't fail a test but will return true/false.
@@ -897,7 +1020,7 @@ This plugin allows to run webdriverio services like:
 -   browserstack
 -   appium
 
-A complete list of all available services can be found on [webdriverio website][17].
+A complete list of all available services can be found on [webdriverio website][14].
 
 #### Setup
 
@@ -909,7 +1032,7 @@ See examples below:
 
 #### Selenium Standalone Service
 
-Install `@wdio/selenium-standalone-service` package, as [described here][18].
+Install `@wdio/selenium-standalone-service` package, as [described here][15].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -928,7 +1051,7 @@ Please note, this service can be used with Protractor helper as well!
 
 #### Sauce Service
 
-Install `@wdio/sauce-service` package, as [described here][19].
+Install `@wdio/sauce-service` package, as [described here][16].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -970,28 +1093,22 @@ In the same manner additional services from webdriverio can be installed, enable
 
 [6]: /basics/#pause
 
-[7]: https://github.com/GoogleChrome/puppeteer/blob/v1.12.2/docs/api.md#class-coverage
-
-[8]: https://github.com/istanbuljs/puppeteer-to-istanbul
-
-[9]: https://github.com/gotwarlost/istanbul
-
-[10]: https://aerokube.com/selenoid/
+[7]: https://aerokube.com/selenoid/
 
-[11]: https://aerokube.com/cm/latest/
+[8]: https://aerokube.com/cm/latest/
 
-[12]: https://hub.docker.com/u/selenoid
+[9]: https://hub.docker.com/u/selenoid
 
-[13]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[10]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[14]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[11]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[15]: https://docs.docker.com/engine/reference/commandline/create/
+[12]: https://docs.docker.com/engine/reference/commandline/create/
 
-[16]: https://codecept.io/img/codeceptjs-slideshow.gif
+[13]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[17]: https://webdriver.io
+[14]: https://webdriver.io
 
-[18]: https://webdriver.io/docs/selenium-standalone-service.html
+[15]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[19]: https://webdriver.io/docs/sauce-service.html
+[16]: https://webdriver.io/docs/sauce-service.html

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.totalTimeout = timeout * 1000;
+    });
+
+    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.totalTimeout);
 
   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
@@ -130,7 +132,16 @@ class Codecept {
     let patterns = [pattern];
     if (!pattern) {
       patterns = [];
-      if (this.config.tests && !this.opts.features) patterns.push(this.config.tests);
+
+      // If the user wants to test a specific set of test files as an array or string.
+      if (this.config.tests && !this.opts.features) {
+        if (Array.isArray(this.config.tests)) {
+          patterns.push(...this.config.tests);
+        } else {
+          patterns.push(this.config.tests);
+        }
+      }
+
       if (this.config.gherkin.features && !this.opts.tests) {
         if (Array.isArray(this.config.gherkin.features)) {
           this.config.gherkin.features.forEach(feature => {
@@ -147,7 +158,9 @@ class Codecept {
         if (!fsPath.isAbsolute(file)) {
           file = fsPath.join(global.codecept_dir, file);
         }
-        this.testFiles.push(fsPath.resolve(file));
+        if (!this.testFiles.includes(fsPath.resolve(file))) {
+          this.testFiles.push(fsPath.resolve(file));
+        }
       });
     }
   }

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;