Merge branch 'codeceptjs:3.x' into patch-9

Author: danielrentz

.github/dependabot.yml

@@ -5,13 +5,13 @@ updates:
     directory: '/'
     schedule:
       interval: 'weekly'
-    target-branch: '3.x'
+    target-branch: '4.x'
   # npm
   - package-ecosystem: 'npm'
     directory: '/'
     schedule:
       interval: 'weekly'
-    target-branch: '3.x'
+    target-branch: '4.x'
     ignore:
       - dependency-name: 'escape-string-regexp'
         versions: ['>=5.0']

docs/parallel.md

@@ -95,20 +95,23 @@ npx codeceptjs run-workers --suites 2
 CodeceptJS supports three different strategies for distributing tests across workers:
 
 #### Default Strategy (`--by test`)
+
 Tests are pre-assigned to workers at startup, distributing them evenly across all workers. Each worker gets a predetermined set of tests to run.
 
 ```sh
 npx codeceptjs run-workers 3 --by test
 ```
 
 #### Suite Strategy (`--by suite`)
+
 Test suites are pre-assigned to workers, with all tests in a suite running on the same worker. This ensures better test isolation but may lead to uneven load distribution.
 
 ```sh
 npx codeceptjs run-workers 3 --by suite
 ```
 
 #### Pool Strategy (`--by pool`) - **Recommended for optimal performance**
+
 Tests are maintained in a shared pool and distributed dynamically to workers as they become available. This provides the best load balancing and resource utilization.
 
 ```sh
@@ -121,19 +124,19 @@ The pool mode enables dynamic test distribution for improved worker load balanci
 
 ### Benefits of Pool Mode
 
-* **Better load balancing**: Workers never sit idle while others are still running long tests
-* **Improved performance**: Especially beneficial when tests have varying execution times
-* **Optimal resource utilization**: All CPU cores stay busy until the entire test suite is complete
-* **Automatic scaling**: Workers continuously process tests until the pool is empty
+- **Better load balancing**: Workers never sit idle while others are still running long tests
+- **Improved performance**: Especially beneficial when tests have varying execution times
+- **Optimal resource utilization**: All CPU cores stay busy until the entire test suite is complete
+- **Automatic scaling**: Workers continuously process tests until the pool is empty
 
 ### When to Use Pool Mode
 
 Pool mode is particularly effective in these scenarios:
 
-* **Uneven test execution times**: When some tests take significantly longer than others
-* **Large test suites**: With hundreds or thousands of tests where load balancing matters
-* **Mixed test types**: When combining unit tests, integration tests, and end-to-end tests
-* **CI/CD pipelines**: For consistent and predictable test execution times
+- **Uneven test execution times**: When some tests take significantly longer than others
+- **Large test suites**: With hundreds or thousands of tests where load balancing matters
+- **Mixed test types**: When combining unit tests, integration tests, and end-to-end tests
+- **CI/CD pipelines**: For consistent and predictable test execution times
 
 ### Usage Examples
 
@@ -144,7 +147,7 @@ npx codeceptjs run-workers 4 --by pool
 # Pool mode with grep filtering
 npx codeceptjs run-workers 3 --by pool --grep "@smoke"
 
-# Pool mode in debug mode  
+# Pool mode in debug mode
 npx codeceptjs run-workers 2 --by pool --debug
 
 # Pool mode with specific configuration
@@ -165,7 +168,7 @@ npx codeceptjs run-workers 3 --by pool -c codecept.conf.js
 # Traditional mode - tests pre-assigned, some workers may finish early
 npx codeceptjs run-workers 3 --by test   # ✓ Good for uniform test times
 
-# Suite mode - entire suites assigned to workers  
+# Suite mode - entire suites assigned to workers
 npx codeceptjs run-workers 3 --by suite  # ✓ Good for test isolation
 
 # Pool mode - tests distributed dynamically
@@ -437,17 +440,17 @@ async function runWorkers() {
 Inside `event.all.result` you can obtain test results from all workers, so you can customize the report:
 
 ```js
-workers.on(event.all.result, (status, completedTests, workerStats) => {
+workers.on(event.all.result, result => {
   // print output
-  console.log('Test status : ', status ? 'Passes' : 'Failed ');
+  console.log('Test status : ', result.hasFailed() ? 'Failed' : 'Passed');
 
   // print stats
-  console.log(`Total tests : ${workerStats.tests}`);
-  console.log(`Passed tests : ${workerStats.passes}`);
-  console.log(`Failed test tests : ${workerStats.failures}`);
+  console.log(`Total tests : ${result.stats.tests}`);
+  console.log(`Passed tests : ${result.stats.passes}`);
+  console.log(`Failed test tests : ${result.stats.failures}`);
 
-  // If you don't want to listen for failed and passed test separately, use completedTests object
-  for (const test of Object.values(completedTests)) {
+  // If you don't want to listen for failed and passed test separately, use `tests` array
+  for (const test of result.tests) {
     console.log(`Test status: ${test.err===null}, `, `Test : ${test.title}`);
   }
 }
@@ -498,7 +501,7 @@ workers.on('message', data => {
   console.log(data)
 })
 
-workers.on(event.all.result, (status, completedTests, workerStats) => {
+workers.on(event.all.result, result => {
   // logic
 })
 ```

docs/reports.md

@@ -35,6 +35,7 @@ GitHub --
 ```
 
 output steps use `--steps` option:
+
 ```
 npx codeceptjs run --steps
 ```
@@ -73,12 +74,10 @@ GitHub --
 
 To get additional information about test execution use `--debug` option.
 
-
 ```
 npx codeceptjs run --debug
 ```
 
-
 This will show execution steps
 as well as notices from test runner. To get even more information with more technical details like error stack traces,
 and global promises, or events use `--verbose` mode.
@@ -141,7 +140,6 @@ npx codecepjs dry-run --debug
 
 > ℹ If you use custom JavaScript code inside tests, or rely on values from `grab*` commands, dry-run may produce error output.
 
-
 ## Testomat.io
 
 [Testomat.io](https://testomat.io) is a modern test management tool focused on CodeceptJS and **created by CodeceptJS team**.
@@ -153,18 +151,17 @@ Testomat.io is commercial SaaS service that can receive run reports from local r
 
 To receive run reports you should:
 
-* [Sign up](https://app.testomat.io/users/sign_up) at Testomat.io
-* Create a new "Classical" project (select "BDD" project if you use CodeceptJS in BDD mode)
-* Select "Import from Source Code"
-* Select "CodeceptJS" as testing framework and JavaScript or TypeScript as a language. If you use BDD select "Gherkin" as language.
-* Execute provided command in a terminal with your project. This will be "check-tests" or "check-cucmber" command. It scans all your test files and imports them into Testomat.io. This way all your e2e tests will be visible in one UI.
-* After tests are imported, go to Runs tab and select "Setup automated tests".
-* Follow the instructions:
-
+- [Sign up](https://app.testomat.io/users/sign_up) at Testomat.io
+- Create a new "Classical" project (select "BDD" project if you use CodeceptJS in BDD mode)
+- Select "Import from Source Code"
+- Select "CodeceptJS" as testing framework and JavaScript or TypeScript as a language. If you use BDD select "Gherkin" as language.
+- Execute provided command in a terminal with your project. This will be "check-tests" or "check-cucmber" command. It scans all your test files and imports them into Testomat.io. This way all your e2e tests will be visible in one UI.
+- After tests are imported, go to Runs tab and select "Setup automated tests".
+- Follow the instructions:
 
 ![image](https://user-images.githubusercontent.com/77803888/151834217-5da44d92-a59a-458d-8856-64ce61bf3a38.png)
 
-* You will need to install `@testomatio/reporter` package and enable it as a plugin in codeceptjs config:
+- You will need to install `@testomatio/reporter` package and enable it as a plugin in codeceptjs config:
 
 ```js
 plugins: {
@@ -176,14 +173,11 @@ plugins: {
 }
 ```
 
-* Run tests with `TESTOMATIO=` env variable and API key provided by Testomat.io
-* See the run report is created and updated in realtime.
-
+- Run tests with `TESTOMATIO=` env variable and API key provided by Testomat.io
+- See the run report is created and updated in realtime.
 
 [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.
 
-
-
 ## ReportPortal
 
 For enterprise grade we reporting we recommend using [ReportPortal](https://reportportal.io).
@@ -195,7 +189,6 @@ Think of it as Kibana but for test reports.
 
 Use official [CodeceptJS Agent for ReportPortal](https://github.com/reportportal/agent-js-codecept/) to start publishing your test results.
 
-
 ## XML
 
 Use default xunit reporter of Mocha to print xml reports. Provide `--reporter xunit` to get the report to screen.
@@ -226,6 +219,21 @@ codeceptjs run --reporter mocha-junit-reporter
 
 Result will be located at `output/result.xml` file.
 
+Alternatively, the reporter name can be added to the configuration file as well. In this case, CodeceptJS can be executed without additional CLI options.
+
+```json
+  "mocha": {
+    "reporter": "mocha-junit-reporter",
+    "reporterOptions": {
+        "mochaFile": "output/result.xml"
+    }
+  },
+```
+
+```sh
+codeceptjs run
+```
+
 ## Html
 
 ### Built-in HTML Reporter
@@ -252,13 +260,13 @@ exports.config = {
   plugins: {
     htmlReporter: {
       enabled: true,
-      output: './output',              // Directory for the report
-      reportFileName: 'report.html',   // Name of the HTML file
-      includeArtifacts: true,          // Include screenshots/artifacts
-      showSteps: true,                 // Show individual test steps
-      showSkipped: true                // Show skipped tests
-    }
-  }
+      output: './output', // Directory for the report
+      reportFileName: 'report.html', // Name of the HTML file
+      includeArtifacts: true, // Include screenshots/artifacts
+      showSteps: true, // Show individual test steps
+      showSkipped: true, // Show skipped tests
+    },
+  },
 }
 ```
 
@@ -299,6 +307,7 @@ npm i mochawesome
 ```
 
 If you get an error like this
+
 ```sh
 "mochawesome" reporter not found
 
@@ -321,14 +330,29 @@ Configure it to use `output` directory to print HTML reports:
   },
 ```
 
-Execute CodeceptJS with HTML reporter:
+Execute CodeceptJS with mochawesome reporter:
 
 ```sh
 codeceptjs run --reporter mochawesome
 ```
 
 Result will be located at `output/index.html` file.
 
+Alternatively, the reporter name can be added to the configuration file as well. In this case, CodeceptJS can be executed without additional CLI options.
+
+```json
+  "mocha": {
+    "reporter": "mochawesome",
+    "reporterOptions": {
+        "reportDir": "output"
+    }
+  },
+```
+
+```sh
+codeceptjs run
+```
+
 ### Advanced usage
 
 Want to have screenshots for failed tests?
@@ -349,7 +373,7 @@ Then tests with failure will have screenshots.
 This helper should be configured in codecept.conf.ts
 
 - `uniqueScreenshotNames` (optional, default: false) - option to prevent screenshot override if you have scenarios with the same name in different suites. This option should be the same as in common helper.
-- `disableScreenshots` (optional, default: false)  - don't save screenshot on failure. This option should be the same as in common helper.
+- `disableScreenshots` (optional, default: false) - don't save screenshot on failure. This option should be the same as in common helper.
 
 Also if you will add Mochawesome helper, then you will able to add custom context in report:
 
@@ -358,21 +382,22 @@ Also if you will add Mochawesome helper, then you will able to add custom contex
 Adds context to executed test in HTML report:
 
 ```js
-I.addMochawesomeContext('simple string');
-I.addMochawesomeContext('http://www.url.com/pathname');
-I.addMochawesomeContext('http://www.url.com/screenshot-maybe.jpg');
-I.addMochawesomeContext({title: 'expected output',
-                         value: {
-                           a: 1,
-                           b: '2',
-                           c: 'd'
-                         }
-});
+I.addMochawesomeContext('simple string')
+I.addMochawesomeContext('http://www.url.com/pathname')
+I.addMochawesomeContext('http://www.url.com/screenshot-maybe.jpg')
+I.addMochawesomeContext({
+  title: 'expected output',
+  value: {
+    a: 1,
+    b: '2',
+    c: 'd',
+  },
+})
 ```
 
 ##### Parameters
 
-- `context`  string, url, path to screenshot, object. See [this](https://www.npmjs.com/package/mochawesome#adding-test-context)
+- `context` string, url, path to screenshot, object. See [this](https://www.npmjs.com/package/mochawesome#adding-test-context)
 
 ## Multi Reports
 
@@ -422,6 +447,20 @@ npx codeceptjs run --reporter mocha-multi
 
 This will give you cli with steps in console and HTML report in `output` directory.
 
+Alternatively, the reporter name can be added to the configuration file as well. In this case, CodeceptJS can be executed without additional CLI options.
+
+```json
+  "mocha": {
+    "reporter": "mocha-multi",
+    "reporterOptions": {
+      ...
+    }
+  }
+```
+
+```sh
+codeceptjs run
+```
 
 ## Testrail
 
@@ -440,7 +479,6 @@ npm i codeceptjs-testrail --save
 Now there is new feature, add the configuration to test run of test plan
 ![Attachemnt for failed case](http://g.recordit.co/uQLvQUq7cT.gif)
 
-
 ## Tesults
 
 Submit test results data from CodeceptJS to [Tesults](https://www.tesults.com) easily with the [codeceptjs-tesults](https://www.npmjs.com/package/codeceptjs-tesults) plugin. Test results data is submitted automatically after a test run completes.

lib/listener/globalTimeout.js

@@ -20,14 +20,29 @@ module.exports = function () {
 
   // disable timeout for BeforeSuite/AfterSuite hooks
   // add separate configs to them?
+  // When a BeforeSuite/AfterSuite hook starts we want to disable the
+  // per-test timeout during that hook execution only. Previously the
+  // code cleared `suiteTimeout` permanently which caused the suite
+  // level timeout to be lost for subsequent tests. Save previous
+  // values and restore them when the hook finishes.
+  let __prevTimeout = undefined
+  let __prevSuiteTimeout = undefined
+
   event.dispatcher.on(event.hook.started, hook => {
-    if (hook instanceof BeforeSuiteHook) {
+    if (hook instanceof BeforeSuiteHook || hook instanceof AfterSuiteHook) {
+      __prevTimeout = timeout
+      // copy array to preserve original values
+      __prevSuiteTimeout = suiteTimeout.slice()
       timeout = null
       suiteTimeout = []
     }
-    if (hook instanceof AfterSuiteHook) {
-      timeout = null
-      suiteTimeout = []
+  })
+
+  event.dispatcher.on(event.hook.finished, hook => {
+    if (hook instanceof BeforeSuiteHook || hook instanceof AfterSuiteHook) {
+      // restore previously stored values
+      timeout = __prevTimeout
+      suiteTimeout = __prevSuiteTimeout.slice()
     }
   })
 

lib/plugin/retryFailedStep.js

@@ -108,6 +108,7 @@ module.exports = config => {
   event.dispatcher.on(event.test.before, test => {
     // pass disableRetryFailedStep is a preferred way to disable retries
     // test.disableRetryFailedStep is used for backward compatibility
+    if (!test.opts) test.opts = {}
     if (test.opts.disableRetryFailedStep || test.disableRetryFailedStep) {
       store.autoRetries = false
       return // disable retry when a test is not active