codeceptjs 3.3.5-beta.3 → 3.3.5-beta.6

package/docs/configuration.md

@@ -11,25 +11,24 @@ After running `codeceptjs init` it should be saved in test root.
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `bootstrap` | `Function` \| `boolean` \| `string` | Execute JS code before tests are run. https://codecept.io/bootstrap/ Can be either JS module file or async function:  ```js bootstrap: async () => server.launch(), ``` or ```js bootstrap: 'bootstrap.js', ``` |
-| `bootstrapAll` | `Function` \| `boolean` \| `string` | Execute JS code before launching tests in parallel mode.  https://codecept.io/bootstrap/#bootstrapall-teardownall |
-| `gherkin?` | { `features`: `string` \| `string`[] ; `steps`: `string`[]  } | Enable BDD features. https://codecept.io/bdd/#configuration   Sample configuration: ```js gherkin: {   features: "./features/*.feature",   steps: ["./step_definitions/steps.js"] } ``` |
+| `bootstrap?` | () => `Promise`<`void`\> \| `boolean` \| `string` | [Execute code before](https://codecept.io/bootstrap/) tests are run.  Can be either JS module file or async function:  ```bootstrap: async () => server.launch(), ``` or ```bootstrap: 'bootstrap.js', ``` |
+| `bootstrapAll?` | () => `Promise`<`void`\> \| `boolean` \| `string` | [Execute code before launching tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall) |
+| `gherkin?` | { `features`: `string` \| `string`[] ; `steps`: `string`[]  } | Enable [BDD features](https://codecept.io/bdd/#configuration).   Sample configuration: ```gherkin: {   features: "./features/*.feature",   steps: ["./step_definitions/steps.js"] } ``` |
 | `gherkin.features` | `string` \| `string`[] | load feature files by pattern. Multiple patterns can be specified as array |
 | `gherkin.steps` | `string`[] | load step definitions from JS files |
-| `grep` | `string` | Pattern to filter tests by name |
-| `helpers?` | { `[key: string]`: `any`;  } | Enabled and configured helpers   ```js helpers: {   Playwright: {     url: 'https://mysite.com',     browser: 'firefox'   } } ``` |
-| `include?` | `any` | Include page objects to access them via dependency injection  ```js I: "./custom_steps.js", loginPage: "./pages/Login.js", User: "./pages/User.js", ``` Configured modules can be injected by name in a Scenario:  ```js Scenario('test', { I, loginPage, User }) ``` |
-| `mocha?` | `any` | [Mocha test runner options](https://mochajs.org/#configuring-mocha-nodejs), additional [reporters](https://codecept.io/reports/#xml) can be configured here.  Example:  ```js mocha: {    "mocha-junit-reporter": {      stdout: "./output/console.log",      options: {        mochaFile: "./output/result.xml",        attachments: true //add screenshot for a failed test      }   } } ``` |
+| `grep?` | `string` | Pattern to filter tests by name. This option is useful if you plan to use multiple configs for different environments.  To execute only tests with  @firefox tag use  ```grep: '@firefox' ``` |
+| `helpers?` | {} | Enable and configure helpers:  ```helpers: {   Playwright: {     url: 'https://mysite.com',     browser: 'firefox'   } } ``` |
+| `include?` | `any` | Include page objects to access them via dependency injection  ```I: "./custom_steps.js", loginPage: "./pages/Login.js", User: "./pages/User.js", ``` Configured modules can be injected by name in a Scenario:  ```Scenario('test', { I, loginPage, User }) ``` |
+| `mocha?` | `any` | [Mocha test runner options](https://mochajs.org/#configuring-mocha-nodejs), additional [reporters](https://codecept.io/reports/#xml) can be configured here.  Example:  ```mocha: {   "mocha-junit-reporter": {      stdout: "./output/console.log",      options: {        mochaFile: "./output/result.xml",        attachments: true //add screenshot for a failed test      }   } } ``` |
 | `noGlobals?` | `boolean` | Disable registering global functions (Before, Scenario, etc). Not recommended |
-| `output` | `string` | Where to store failure screenshots, artifacts, etc |
-| `plugins?` | `any` | [Enabled plugins](https://codecept.io/plugins/) |
-| `require?` | `string`[] | Require additional JS modules. https://codecept.io/configuration/#require   Example: ``` require: ["ts-node/register", "should"] ``` |
-| `teardown` | `Function` \| `boolean` \| `string` | Execute JS code after tests are run. https://codecept.io/bootstrap/ Can be either JS module file or async function:  ```js teardown: async () => server.stop(), ``` or ```js teardown: 'teardown.js', ``` |
-| `teardownAll` | `Function` \| `boolean` \| `string` | Execute JS code after finishing tests in parallel mode.  https://codecept.io/bootstrap/#bootstrapall-teardownall |
-| `tests` | `string` | Pattern to locate CodeceptJS tests.  Allows to enter glob pattern or an Array<string> of patterns to match tests / test file names.   For tests in JavaScript:  ```js tests: 'tests/**.test.js' ```  For tests in TypeScript:  ```js tests: 'tests/**.test.ts' ``` |
-| `timeout?` | `number` | Set default tests timeout in seconds.  Tests will be killed on no response after timeout.  ```js timeout: 20, ``` |
-| `translation?` | `string` | Enable localized test commands https://codecept.io/translation/ |
-
+| `output` | `string` | Where to store failure screenshots, artifacts, etc   ```output: './output' ``` |
+| `plugins?` | `any` | Enable CodeceptJS plugins. Example:  ```plugins: {   autoDelay: {     enabled: true   }  } ``` |
+| `require?` | `string`[] | [Require additional JS modules](https://codecept.io/configuration/#require)  Example: ``` require: ["should"] ``` |
+| `teardown?` | () => `Promise`<`void`\> \| `boolean` \| `string` | [Execute code after tests](https://codecept.io/bootstrap/) finished.   Can be either JS module file or async function:  ```teardown: async () => server.stop(), ``` or ```teardown: 'teardown.js', ``` |
+| `teardownAll?` | () => `Promise`<`void`\> \| `boolean` \| `string` | [Execute JS code after finishing tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall) |
+| `tests` | `string` | Pattern to locate CodeceptJS tests. Allows to enter glob pattern or an Array<string> of patterns to match tests / test file names.  For tests in JavaScript:  ```tests: 'tests/**.test.js' ``` For tests in TypeScript:  ```tests: 'tests/**.test.ts' ``` |
+| `timeout?` | `number` | Set default tests timeout in seconds. Tests will be killed on no response after timeout.  ```timeout: 20, ``` |
+| `translation?` | `string` | Enable [localized test commands](https://codecept.io/translation/) |
 
 
 ## Require

package/lib/command/init.js

@@ -30,9 +30,10 @@ const packages = [];
 let isTypeScript = false;
 let extension = 'js';
 
-const configHeader = `const { setHeadlessWhen, setCommonPlugins } = require('@codeceptjs/configure');
-
+const requireCodeceptConfigure = "const { setHeadlessWhen, setCommonPlugins } = require('@codeceptjs/configure');";
+const importCodeceptConfigure = "import { setHeadlessWhen, setCommonPlugins } from '@codeceptjs/configure';";
 
+const configHeader = `
 // turn on headless mode when running with HEADLESS=true environment variable
 // export HEADLESS=true && npx codeceptjs run
 setHeadlessWhen(process.env.HEADLESS);
@@ -174,18 +175,21 @@ module.exports = function (initPath) {
         print(`Steps file created at ${stepFile}`);
       }
 
-      let configSource = beautify(`/** @type {CodeceptJS.MainConfig} */\nexports.config = ${inspect(config, false, 4, false)}`);
-
-      if (require.resolve('@codeceptjs/configure') && isLocal && !initPath) {
-        // prepend @codeceptjs/configure only when this module can be required in config
-        configSource = configHeader + configSource;
-      }
+      let configSource;
+      const hasConfigure = isLocal && !initPath;
 
       if (isTypeScript) {
         configSource = beautify(`export const config : CodeceptJS.MainConfig = ${inspect(config, false, 4, false)}`);
+
+        if (hasConfigure) configSource = importCodeceptConfigure + configHeader + configSource;
+
         fs.writeFileSync(typeScriptconfigFile, configSource, 'utf-8');
         print(`Config created at ${typeScriptconfigFile}`);
       } else {
+        configSource = beautify(`/** @type {CodeceptJS.MainConfig} */\nexports.config = ${inspect(config, false, 4, false)}`);
+
+        if (hasConfigure) configSource = requireCodeceptConfigure + configHeader + configSource;
+
         fs.writeFileSync(configFile, configSource, 'utf-8');
         print(`Config created at ${configFile}`);
       }

package/lib/config.js

@@ -5,7 +5,6 @@ const {
   isFile,
   deepMerge,
   deepClone,
-  requireWithFallback,
 } = require('./utils');
 
 const defaultConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.3.5-beta.3",
+  "version": "3.3.5-beta.6",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -133,6 +133,8 @@
     "testcafe": "^1.18.3",
     "ts-morph": "^3.1.3",
     "tsd-jsdoc": "https://github.com/englercj/tsd-jsdoc.git",
+    "typedoc": "^0.23.10",
+    "typedoc-plugin-markdown": "^3.13.4",
     "typescript": "^4.4.3",
     "wdio-docker-service": "^1.5.0",
     "webdriverio": "^7.16.14",

package/typings/index.d.ts

@@ -32,12 +32,27 @@ declare namespace CodeceptJS {
      * ```
      */
     tests: string;
-    /** Where to store failure screenshots, artifacts, etc */
+    /** 
+     * Where to store failure screenshots, artifacts, etc 
+     * 
+     * ```js
+     * output: './output'
+     * ```
+     */
     output: string;
-    /** Pattern to filter tests by name */
+    /** 
+     * Pattern to filter tests by name.
+     * This option is useful if you plan to use multiple configs for different environments.
+     * 
+     * To execute only tests with @firefox tag
+     * 
+     * ```js
+     * grep: '@firefox'
+     * ```
+     */
     grep?: string;
     /**
-     * Enabled and configured helpers
+     * Enable and configure helpers:
      *
      * ```js
      * helpers: {
@@ -49,17 +64,90 @@ declare namespace CodeceptJS {
      * ```
     */
     helpers?: {
-      /** Run web tests controlling browsers via Playwright engine. https://codecept.io/playwright */
+      /** 
+       * Run web tests controlling browsers via Playwright engine. 
+       *
+       * https://codecept.io/helpers/playwright 
+       * 
+       * Available commands:
+       * ```js
+       * I.amOnPage('/');
+       * I.click('Open');
+       * I.see('Welcome');
+       * ```
+       */
       Playwright?: PlaywrightConfig;
-      /** Run web tests controlling browsers via Puppeteer engine. https://codecept.io/puppeteer */
+      /** 
+       * Run web tests controlling browsers via Puppeteer engine. 
+       * 
+       * https://codecept.io/helpers/puppeteer 
+       * 
+       * Available commands:
+       * ```js
+       * I.amOnPage('/');
+       * I.click('Open');
+       * I.see('Welcome');
+       * ```
+       */
       Puppeteer?: PuppeteerConfig;
-      /** Run web tests controlling browsers via WebDriver engine. https://codecept.io/webdriver */
+
+      /** 
+       * Run web tests controlling browsers via WebDriver engine. 
+       * 
+       * Available commands:
+       * ```js
+       * I.amOnPage('/');
+       * I.click('Open');
+       * I.see('Welcome');
+       * ```
+       * 
+       * https://codecept.io/helpers/webdriver 
+       */
       WebDriver?: WebDriverConfig;
-      /** Execute REST API requests for API testing or to assist web testing. https://codecept.io/api/ */
+      /** 
+       * Execute REST API requests for API testing or to assist web testing. 
+       * 
+       * https://codecept.io/helpers/REST 
+       * 
+       * Available commands:
+       * ```js
+       * I.sendGetRequest('/');
+       * ```
+       */
       REST?: RESTConfig;
+
+      /** 
+       * Use JSON assertions for API testing.
+       * Can be paired with REST or GraphQL helpers.
+       * 
+       * https://codecept.io/helpers/JSONResponse 
+       * 
+       * Available commands:
+       * ```js
+       * I.seeResponseContainsJson({ user: { email: 'jon@doe.com' } });
+       * ```
+       */
+      JSONResponse?: any;      
+
       [key: string]: any;
     },
-    /** [Enabled plugins](https://codecept.io/plugins/)  */
+    /** 
+     * Enable CodeceptJS plugins. 
+     * 
+     * https://codecept.io/plugins/
+     * 
+     * Plugins listen to test events and extend functionality of CodeceptJS.
+     * 
+     * Example:
+     * 
+     * ```js
+     * plugins: {
+     *   autoDelay: {
+     *     enabled: true
+     *   }
+      }
+     * ```
+     */
     plugins?: any;
     /**
      * Include page objects to access them via dependency injection
@@ -106,7 +194,8 @@ declare namespace CodeceptJS {
      */
     mocha?: any;
     /**
-     * Execute JS code before tests are run. https://codecept.io/bootstrap/
+     * [Execute code before](https://codecept.io/bootstrap/) tests are run.
+     * 
      * Can be either JS module file or async function:
      *
      * ```js
@@ -119,7 +208,8 @@ declare namespace CodeceptJS {
     */
     bootstrap?: () => Promise<void> | boolean | string;
     /**
-     * Execute JS code after tests are run. https://codecept.io/bootstrap/
+     * [Execute code after tests](https://codecept.io/bootstrap/) finished. 
+     * 
      * Can be either JS module file or async function:
      *
      * ```js
@@ -132,30 +222,29 @@ declare namespace CodeceptJS {
     */
     teardown?: () => Promise<void> | boolean | string;
     /**
-     * Execute JS code before launching tests in parallel mode.
-     * https://codecept.io/bootstrap/#bootstrapall-teardownall
-    */
+     * [Execute code before launching tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)
+     * 
+     */
     bootstrapAll?: () => Promise<void> | boolean | string;
     /**
-     * Execute JS code after finishing tests in parallel mode.
-     * https://codecept.io/bootstrap/#bootstrapall-teardownall
+     * [Execute JS code after finishing tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)
     */
     teardownAll?: () => Promise<void> | boolean | string;
-    /** Enable localized test commands https://codecept.io/translation/ */
+    /** Enable [localized test commands](https://codecept.io/translation/) */
     translation?: string;
     /**
-     * Require additional JS modules. https://codecept.io/configuration/#require
+     * [Require additional JS modules](https://codecept.io/configuration/#require)
      *
      * Example:
      * ```
-     * require: ["ts-node/register", "should"]
+     * require: ["should"]
      * ```
     */
     require?: Array<string>;
 
     /**
-     * Enable BDD features. https://codecept.io/bdd/#configuration
-     *
+     * Enable [BDD features](https://codecept.io/bdd/#configuration). 
+     * 
      * Sample configuration:
      * ```js
      * gherkin: {