codeceptjs 3.3.8-beta.1 → 3.4.0-beta.1

package/docs/plugins.md

@@ -11,7 +11,9 @@ title: Plugins
 
 Allure reporter
 
-![][1]
+> ⚠️ This plugin was moved to its [own package][1]
+
+![][2]
 
 Enables Allure reporter.
 
@@ -43,7 +45,7 @@ Launch Allure server and see the report like on a screenshot above:
 -   `outputDir` - a directory where allure reports should be stored. Standard output directory is set by default.
 -   `enableScreenshotDiffPlugin` - a boolean flag for add screenshot diff to report.
      To attach, tou need to attach three files to the report - "diff.png", "actual.png", "expected.png".
-     See [Allure Screenshot Plugin][2]
+     See [Allure Screenshot Plugin][3]
 
 #### Public API
 
@@ -71,7 +73,20 @@ const allure = codeceptjs.container.plugins('allure');
     });
 ```
 
-![Created Step Image][3]
+![Created Step Image][4]
+
+-   `addScreenDiff(name, expectedImg, actualImg, diffImg)` - add a special screen diff block to the current test case
+    image must be a string representing the contents of the expected image file encoded in base64
+    Example of usage:
+
+```js
+const expectedImg = fs.readFileSync('expectedImg.png', { encoding: 'base64' });
+...
+allure.addScreenDiff('Screen Diff', expectedImg, actualImg, diffImg);
+```
+
+![Overlay][5]
+![Diff][6]
 
 -   `severity(value)` - adds severity label
 -   `epic(value)` - adds epic label
@@ -449,7 +464,7 @@ Possible config options:
 
 ## customLocator
 
-Creates a [custom locator][4] by using special attributes in HTML.
+Creates a [custom locator][7] by using special attributes in HTML.
 
 If you have a convention to use `data-test-id` or `data-qa` attributes to mark active elements for e2e tests,
 you can enable this plugin to simplify matching elements with these attributes:
@@ -599,9 +614,9 @@ This method works with WebDriver, Playwright, Puppeteer, Appium helpers.
 Function parameter `el` represents a matched element.
 Depending on a helper API of `el` can be different. Refer to API of corresponding browser testing engine for a complete API list:
 
--   [Playwright ElementHandle][5]
--   [Puppeteer][6]
--   [webdriverio element][7]
+-   [Playwright ElementHandle][8]
+-   [Puppeteer][9]
+-   [webdriverio element][10]
 
 #### Configuration
 
@@ -615,17 +630,17 @@ const eachElement = codeceptjs.container.plugins('eachElement');
 
 ### Parameters
 
--   `purpose` **[string][8]** 
+-   `purpose` **[string][11]** 
 -   `locator` **CodeceptJS.LocatorOrString** 
--   `fn` **[Function][9]** 
+-   `fn` **[Function][12]** 
 
-Returns **([Promise][10]<any> | [undefined][11])** 
+Returns **([Promise][13]<any> | [undefined][14])** 
 
 ## fakerTransform
 
-Use the [faker.js][12] package to generate fake data inside examples on your gherkin tests
+Use the [faker.js][15] package to generate fake data inside examples on your gherkin tests
 
-![Faker.js][13]
+![Faker.js][16]
 
 #### Usage
 
@@ -663,7 +678,7 @@ Scenario Outline: ...
 
 ## pauseOnFail
 
-Automatically launches [interactive pause][14] when a test fails.
+Automatically launches [interactive pause][17] when a test fails.
 
 Useful for debugging flaky tests on local environment.
 Add this plugin to config file:
@@ -679,6 +694,10 @@ Enable it manually on each run via `-p` option:
 
     npx codeceptjs run -p pauseOnFail
 
+## reporter
+
+Type: Allure
+
 ## retryFailedStep
 
 Retries each failed step in a test.
@@ -846,14 +865,14 @@ Possible config options:
 
 ## selenoid
 
-[Selenoid][15] plugin automatically starts browsers and video recording.
+[Selenoid][18] 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][16] tool from Selenoid
+> If you have issues starting Selenoid with this plugin consider using the official [Configuration Manager][19] tool from Selenoid
 
 ### Usage
 
@@ -882,7 +901,7 @@ plugins: {
   }
 ```
 
-When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][17] and start Selenoid automatically.
+When `autoCreate` is enabled it will pull the [latest Selenoid from DockerHub][20] 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.
@@ -894,10 +913,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][16] to create and start containers semi-automatically.
+> Use [Selenoid Configuration Manager][19] 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][18] to know more about browsers.json.
+    [Refer to Selenoid documentation][21] to know more about browsers.json.
 
 _Sample browsers.json_
 
@@ -922,7 +941,7 @@ _Sample browsers.json_
 
 2.  Create Selenoid container
 
-Run the following command to create a container. To know more [refer here][19]
+Run the following command to create a container. To know more [refer here][22]
 
 ```bash
 docker create                                    \
@@ -955,7 +974,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][20] to know more   |
+| additionalParams | example: `additionalParams: '--env TEST=test'` [Refer here][23] to know more   |
 
 ### Parameters
 
@@ -963,7 +982,7 @@ When `allure` plugin is enabled a video is attached to report automatically.
 
 ## stepByStepReport
 
-![step-by-step-report][21]
+![step-by-step-report][24]
 
 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.
@@ -1144,7 +1163,7 @@ This plugin allows to run webdriverio services like:
 -   browserstack
 -   appium
 
-A complete list of all available services can be found on [webdriverio website][22].
+A complete list of all available services can be found on [webdriverio website][25].
 
 #### Setup
 
@@ -1156,7 +1175,7 @@ See examples below:
 
 #### Selenium Standalone Service
 
-Install `@wdio/selenium-standalone-service` package, as [described here][23].
+Install `@wdio/selenium-standalone-service` package, as [described here][26].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `selenium-standalone` service:
@@ -1175,7 +1194,7 @@ Please note, this service can be used with Protractor helper as well!
 
 #### Sauce Service
 
-Install `@wdio/sauce-service` package, as [described here][24].
+Install `@wdio/sauce-service` package, as [described here][27].
 It is important to make sure it is compatible with current webdriverio version.
 
 Enable `wdio` plugin in plugins list and add `sauce` service:
@@ -1205,50 +1224,56 @@ In the same manner additional services from webdriverio can be installed, enable
 
 -   `config`  
 
-[1]: https://user-images.githubusercontent.com/220264/45676511-8e052800-bb3a-11e8-8cbb-db5f73de2add.png
+[1]: https://github.com/codeceptjs/allure-plugin
+
+[2]: https://user-images.githubusercontent.com/220264/45676511-8e052800-bb3a-11e8-8cbb-db5f73de2add.png
+
+[3]: https://github.com/allure-framework/allure2/blob/master/plugins/screen-diff-plugin/README.md
+
+[4]: https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png
 
-[2]: https://github.com/allure-framework/allure2/blob/master/plugins/screen-diff-plugin/README.md
+[5]: https://user-images.githubusercontent.com/63167966/215404458-9a325668-819e-4289-9b42-5807c49ebddb.png
 
-[3]: https://user-images.githubusercontent.com/63167966/139339384-e6e70a62-3638-406d-a224-f32473071428.png
+[6]: https://user-images.githubusercontent.com/63167966/215404645-73b09da0-9e6d-4352-a123-80c22f7014cd.png
 
-[4]: https://codecept.io/locators#custom-locators
+[7]: https://codecept.io/locators#custom-locators
 
-[5]: https://playwright.dev/docs/api/class-elementhandle
+[8]: https://playwright.dev/docs/api/class-elementhandle
 
-[6]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
+[9]: https://pptr.dev/#?product=Puppeteer&show=api-class-elementhandle
 
-[7]: https://webdriver.io/docs/api
+[10]: https://webdriver.io/docs/api
 
-[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
 
-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
-[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
+[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
 
-[12]: https://www.npmjs.com/package/faker
+[15]: https://www.npmjs.com/package/faker
 
-[13]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
+[16]: https://raw.githubusercontent.com/Marak/faker.js/master/logo.png
 
-[14]: /basics/#pause
+[17]: /basics/#pause
 
-[15]: https://aerokube.com/selenoid/
+[18]: https://aerokube.com/selenoid/
 
-[16]: https://aerokube.com/cm/latest/
+[19]: https://aerokube.com/cm/latest/
 
-[17]: https://hub.docker.com/u/selenoid
+[20]: https://hub.docker.com/u/selenoid
 
-[18]: https://aerokube.com/selenoid/latest/#_prepare_configuration
+[21]: https://aerokube.com/selenoid/latest/#_prepare_configuration
 
-[19]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
+[22]: https://aerokube.com/selenoid/latest/#_option_2_start_selenoid_container
 
-[20]: https://docs.docker.com/engine/reference/commandline/create/
+[23]: https://docs.docker.com/engine/reference/commandline/create/
 
-[21]: https://codecept.io/img/codeceptjs-slideshow.gif
+[24]: https://codecept.io/img/codeceptjs-slideshow.gif
 
-[22]: https://webdriver.io
+[25]: https://webdriver.io
 
-[23]: https://webdriver.io/docs/selenium-standalone-service.html
+[26]: https://webdriver.io/docs/selenium-standalone-service.html
 
-[24]: https://webdriver.io/docs/sauce-service.html
+[27]: https://webdriver.io/docs/sauce-service.html

package/docs/reports.md

@@ -183,62 +183,6 @@ plugins: {
 [Testomat.io](https://testomat.io) reporter works in the cloud, so it doesn't require you to install additional software. It can be integrated with your CI service to rerun only failed tests, launch new runs from UI, and send report notifications by email or in Slack, MS Teams, or create issue in Jira.
 
 
-## Allure
-
-
-[Allure reporter](https://allure.qatools.ru/#) is a tool to store and display test reports.
-It provides nice web UI which contains all important information on test execution.
-CodeceptJS has built-in support for Allure reports. Inside reports you will have all steps, substeps and screenshots.
-
-![](https://user-images.githubusercontent.com/220264/45676511-8e052800-bb3a-11e8-8cbb-db5f73de2add.png)
-
-> ▶ Allure is a standalone tool. Please refer to [Allure documentation](https://docs.qameta.io/allure/) to learn more about using Allure reports.
-
-Allure requires **Java 8** to work. Then Allure can be installed via NPM:
-
-```
-npm install -g allure-commandline --save-dev
-```
-
-Add [Allure plugin](/plugins/#allure) in config under `plugins` section.
-
-```js
-plugins: {
-    allure: {
-  }
-}
-```
-
-Run tests with allure plugin enabled:
-
-```
-npx codeceptjs run --plugins allure
-```
-
-(optionally) To enable allure plugin permanently include `"enabled": true` into plugin config:
-
-
-```js
-"plugins": {
-    "allure": {
-      "enabled": true
-    }
-}
-```
-
-Launch Allure server and see the report like on a screenshot above:
-
-```
-allure serve output
-```
-
-Allure reporter aggregates data from other plugins like [*stepByStepReport*](/plugins/#stepByStepReport) and [*screenshotOnFail*](/plugins/#screenshotOnFail)
-
-Allure reports can also be generated for `dry-run` command. So you can get the first report with no tests actually being executed. Enable allure plugin in dry-run options, and pass `--debug` option to print all tests on screen.
-
-```
-npx codeceptjs dry-run --debug -p allure
-```
 
 ## ReportPortal
 

package/docs/typescript.md

@@ -41,16 +41,10 @@ Then select TypeScript as the first question:
 
 Then a config file and new tests will be created in TypeScript format.
 
-If a config file is set in TypeScript format (`codecept.conf.ts`) package `node-ts` will be used to run tests. 
+If a config file is set in TypeScript format (`codecept.conf.ts`) package `ts-node` will be used to run tests. 
 
 ## Promise-Based Typings
 
-If you plan to write tests in TypeScript you will probably want to enable "promise-based typings" as you will be asked in `init` command about it:
-
-```js
-? Would you prefer to use promise-based typings and explicitly use `await` for all I.* commands?
-```
-
 By default, CodeceptJS tests are written in synchronous mode. This is a regular CodeceptJS test:
 
 ```js
@@ -82,7 +76,7 @@ Otherwise they will still return promises but it won't be relfected in type defi
 To introduce promise-based typings into a current project edit `codecept.conf.ts`:
 
 ```ts
-  fullPromiseBased: true;
+fullPromiseBased: true;
 ```
 
 and rebuild type definitions with

package/lib/actor.js

@@ -16,8 +16,9 @@ class Actor {
    * add print comment method`
    * @param {string} msg
    * @param {string} color
-   * @return {Promise<any> | undefined}
    * @inner
+   *
+   * ⚠️ returns a promise which is synchronized internally by recorder
    */
   say(msg, color = 'cyan') {
     return recorder.add(`say ${msg}`, () => {

package/lib/cli.js

@@ -40,7 +40,7 @@ class Cli extends Base {
 
     runner.on('fail', (test) => {
       if (test.ctx.currentTest) {
-        this.loadedTests.push(test.ctx.currentTest.id);
+        this.loadedTests.push(test.ctx.currentTest.uid);
       }
       if (showSteps && test.steps) {
         return output.scenario.failed(test);
@@ -57,7 +57,7 @@ class Cli extends Base {
       } else {
         skipTestConfig(test, null);
       }
-      this.loadedTests.push(test.id);
+      this.loadedTests.push(test.uid);
       cursor.CR();
       output.test.skipped(test);
     });
@@ -111,7 +111,7 @@ class Cli extends Base {
       let skippedCount = 0;
       const grep = runner._grep;
       for (const test of suite.tests) {
-        if (!test.state && !this.loadedTests.includes(test.id)) {
+        if (!test.state && !this.loadedTests.includes(test.uid)) {
           if (matchTest(grep, test.title)) {
             if (!test.opts) {
               test.opts = {};

package/lib/codecept.js

@@ -67,8 +67,8 @@ class Codecept {
     global.output_dir = fsPath.resolve(dir, this.config.output);
 
     if (!this.config.noGlobals) {
+      global.Helper = global.codecept_helper = require('@codeceptjs/helper');
       global.actor = global.codecept_actor = require('./actor');
-      global.Helper = global.codecept_helper = require('./helper');
       global.pause = require('./pause');
       global.within = require('./within');
       global.session = require('./session');
@@ -98,6 +98,7 @@ class Codecept {
     runHook(require('./listener/artifacts'));
     runHook(require('./listener/config'));
     runHook(require('./listener/helpers'));
+    runHook(require('./listener/retry'));
     runHook(require('./listener/timeout'));
     runHook(require('./listener/exit'));
 

package/lib/command/generate.js

@@ -128,7 +128,9 @@ module.exports.pageObject = function (genPath, opts) {
     const name = lcfirst(result.name) + ucfirst(kind);
     let data = readConfig(configFile);
     config.include[name] = result.filename;
-    data = data.replace(/include[\s\S][^\}]*/i, `include: ${JSON.stringify(config.include).slice(0, -1)}`);
+    const currentInclude = `${data.match(/include:[\s\S][^\}]*/i)[0]}\n ${name}:${JSON.stringify(config.include[name])}`;
+
+    data = data.replace(/include:[\s\S][^\}]*/i, `${currentInclude}`);
 
     fs.writeFileSync(configFile, beautify(data), 'utf-8');
 

package/lib/command/gherkin/snippets.js

@@ -1,6 +1,7 @@
 const escapeStringRegexp = require('escape-string-regexp');
 const fs = require('fs');
-const { Parser } = require('gherkin');
+const Gherkin = require('@cucumber/gherkin');
+const Messages = require('@cucumber/messages');
 const glob = require('glob');
 const fsPath = require('path');
 
@@ -9,7 +10,10 @@ const Codecept = require('../../codecept');
 const output = require('../../output');
 const { matchStep } = require('../../interfaces/bdd');
 
-const parser = new Parser();
+const uuidFn = Messages.IdGenerator.uuid();
+const builder = new Gherkin.AstBuilder(uuidFn);
+const matcher = new Gherkin.GherkinClassicTokenMatcher();
+const parser = new Gherkin.Parser(builder, matcher);
 parser.stopAtFirstError = false;
 
 module.exports = function (genPath, options) {
@@ -85,8 +89,8 @@ module.exports = function (genPath, options) {
   const parseFile = (file) => {
     const ast = parser.parse(fs.readFileSync(file).toString());
     for (const child of ast.feature.children) {
-      if (child.type === 'ScenarioOutline') continue; // skip scenario outline
-      parseSteps(child.steps).map((step) => {
+      if (child.scenario.keyword === 'Scenario Outline') continue; // skip scenario outline
+      parseSteps(child.scenario.steps).map((step) => {
         return Object.assign(step, { file: file.replace(global.codecept_dir, '').slice(1) });
       }).map((step) => newSteps.set(`${step.type}(${step})`, step));
     }

package/lib/command/init.js

@@ -126,13 +126,6 @@ module.exports = function (initPath) {
       default: './output',
       message: 'Where should logs, screenshots, and reports to be stored?',
     },
-    {
-      name: 'promise',
-      type: 'confirm',
-      default: false,
-      message: 'Would you prefer to use promise-based typings for all I.* commands? http://bit.ly/3XIMq6n',
-      when: (answers) => answers.typescript,
-    },
     {
       name: 'translation',
       type: 'list',
@@ -155,7 +148,6 @@ module.exports = function (initPath) {
     config.tests = result.tests;
     if (isTypeScript) {
       config.tests = `${config.tests.replace(/\.js$/, `.${extension}`)}`;
-      config.fullPromiseBased = result.promise;
     }
 
     // create a directory tests if it is included in tests path

package/lib/command/run-workers.js

@@ -1,16 +1,10 @@
 // For Node version >=10.5.0, have to use experimental flag
-const { satisfyNodeVersion } = require('./utils');
 const { tryOrDefault } = require('../utils');
 const output = require('../output');
 const event = require('../event');
 const Workers = require('../workers');
 
 module.exports = async function (workerCount, options) {
-  satisfyNodeVersion(
-    '>=11.7.0',
-    'Required minimum Node version of 11.7.0 to work with "run-workers"',
-  );
-
   process.env.profile = options.profile;
 
   const { config: testConfig, override = '' } = options;
@@ -46,6 +40,9 @@ module.exports = async function (workerCount, options) {
   try {
     await workers.bootstrapAll();
     await workers.run();
+  } catch (err) {
+    output.error(err);
+    process.exit(1);
   } finally {
     await workers.teardownAll();
   }

package/lib/command/utils.js

@@ -1,6 +1,5 @@
 const fs = require('fs');
 const path = require('path');
-const semver = require('semver');
 const util = require('util');
 const mkdirp = require('mkdirp');
 
@@ -71,15 +70,6 @@ function safeFileWrite(file, contents) {
 
 module.exports.safeFileWrite = safeFileWrite;
 
-module.exports.satisfyNodeVersion = (
-  version,
-  failureMessage = `Required Node version: ${version}`,
-) => {
-  if (!semver.satisfies(process.version, version)) {
-    fail(failureMessage);
-  }
-};
-
 module.exports.captureStream = (stream) => {
   let oldStream;
   let buffer = '';

package/lib/command/workers/runTests.js

@@ -68,7 +68,7 @@ function filterTests() {
   mocha.loadFiles();
 
   for (const suite of mocha.suite.suites) {
-    suite.tests = suite.tests.filter(test => tests.indexOf(test.id) >= 0);
+    suite.tests = suite.tests.filter(test => tests.indexOf(test.uid) >= 0);
   }
 }
 
@@ -124,7 +124,7 @@ function initializeListeners() {
     return {
       opts: test.opts || {},
       tags: test.tags || [],
-      id: test.id,
+      uid: test.uid,
       workerIndex,
       retries: test._retries,
       title: test.title,

package/lib/config.js

@@ -79,7 +79,11 @@ class Config {
     configFile = path.resolve(configFile || '.');
 
     if (!fileExists(configFile)) {
-      throw new Error(`Config file ${configFile} does not exist. Execute 'codeceptjs init' to create config`);
+      configFile = configFile.replace('.js', '.ts');
+
+      if (!fileExists(configFile)) {
+        throw new Error(`Config file ${configFile} does not exist. Execute 'codeceptjs init' to create config`);
+      }
     }
 
     // is config file

package/lib/helper/ApiDataFactory.js

@@ -1,6 +1,6 @@
 const path = require('path');
 
-const Helper = require('../helper');
+const Helper = require('@codeceptjs/helper');
 const REST = require('./REST');
 
 /**
@@ -46,8 +46,8 @@ const REST = require('./REST');
  * ```js
  * // tests/factories/posts.js
  *
- * const Factory = require('rosie').Factory;
- * const faker = require('@faker-js/faker');
+ * const { Factory } = require('rosie');
+ * const { faker } = require('@faker-js/faker');
  *
  * module.exports = new Factory()
  *    // no need to set id, it will be set by REST API
@@ -262,8 +262,8 @@ class ApiDataFactory extends Helper {
    * ```
    *
    * @param {*} factory factory to use
-   * @param {*} params predefined parameters
-   * @param {*} options options for programmatically generate the attributes
+   * @param {*} [params] predefined parameters
+   * @param {*} [options] options for programmatically generate the attributes
    * @returns {Promise<*>}
    */
   have(factory, params, options) {
@@ -288,8 +288,8 @@ class ApiDataFactory extends Helper {
    *
    * @param {*} factory
    * @param {*} times
-   * @param {*} params
-   * @param {*} options
+   * @param {*} [params]
+   * @param {*} [options]
    */
   haveMultiple(factory, times, params, options) {
     const promises = [];