codeceptjs 4.0.0-rc.20 → 4.0.0-rc.21

package/bin/mcp-server.js

@@ -60,9 +60,7 @@ function aiTraceHint() {
 }
 
 function applyMochaGrep(grep) {
-  if (!grep) return
-  const mocha = typeof container.mocha === 'function' ? container.mocha() : container.mocha
-  if (mocha && typeof mocha.grep === 'function') mocha.grep(grep)
+  if (grep) container.mocha().grep(grep)
 }
 
 function pauseAtMatcher(pauseAt) {
@@ -401,14 +399,16 @@ async function cancelRun() {
   abortRun = true
   if (typeof pendingRunCleanup === 'function') { try { pendingRunCleanup() } catch {} }
   if (pausedController) { try { pausedController.resolveContinue() } catch {} ; pausedController = null }
+
+  try { container.mocha().runner?.abort() } catch {}
+
   if (pendingRunPromise) {
-    try { await Promise.race([pendingRunPromise.catch(() => {}), new Promise(r => setTimeout(r, 5000))]) } catch {}
+    try { await pendingRunPromise.catch(() => {}) } catch {}
   }
   pendingRunPromise = null
   pendingRunResults = null
   pendingTestFile = null
   pendingStepInfo = null
-  abortRun = false
   return true
 }
 
@@ -1032,6 +1032,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               pendingRunCleanup = null
             }
 
+            abortRun = false
             let runError = null
             const runPromise = (async () => {
               try {
@@ -1126,6 +1127,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               pendingRunCleanup = null
             }
 
+            abortRun = false
             let runError = null
             const runPromise = (async () => {
               try {

package/docs/agents.md

@@ -5,6 +5,38 @@ title: Agentic Testing
 
 # Agentic Testing
 
+## What Makes CodeceptJS Agent-friendly
+
+CodeceptJS 4 is designed for agent testing. It ships with its own MCP and official skills that teach agents best practices in test automation—how to write tests, choose locators, test them live in the browser, and refactor to page objects.
+
+Agents get full control over test and browser execution: 
+
+- **Full HTML access and ARIA snapshots.** Agents see buttons with icons, empty labels, and other elements Playwright MCP's accessibility tree omits.
+
+- **Query HTML directly with CSS, ARIA, Semantic Locators or XPath** Agents can freely run XPath or CSS to efficiently search over HTML.
+
+- **Browser logs and page state as files.** Agents read via native filesystem tools instead of extra requests, eliminating redundant context dumps.
+
+- **Same locators for tests and agents.** Tests and agent scripts share identical selectors. No elements by reference indexes, no clicks by coordinates. Agents inherit battle-tested patterns without guessing.
+
+- **Testing-first framework, not browser control.** CodeceptJS is built for testing, so agents stay focused on test scenarios instead of raw browser commands.
+
+CodeceptJS is token-efficient: it stores HTML, ARIA, logs, and HTTP request data as files instead of streaming them through MCP. Agents read these files with their native shell tools—no extra API calls, no redundant context.
+
+## The loop
+
+Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
+
+1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
+2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
+3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
+4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
+5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
+6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
+
+
+## How It Works
+
 CodeceptJS ships an **MCP server and a skillset** that lets an AI agent (Claude Code, Cursor, Codex, others) write and fix tests by driving the real browser. The agent runs the same `I.*` commands the test does, reads how the page responds, and only commits the lines that succeeded.
 
 ## Why MCP
@@ -30,16 +62,6 @@ This lets the agent get a test working in one iteration. The agent can live-writ
 
 The MCP server is the agent-facing equivalent of the `pause()` REPL — same access, driven by tool calls instead of keystrokes. Full tool reference at [/mcp](/mcp).
 
-## The loop
-
-Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
-
-1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
-2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
-3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
-4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
-5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
-6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
 
 ## How the agent reads the page
 

package/docs/environment-variables.md

@@ -0,0 +1,131 @@
+---
+permalink: /environment-variables
+title: Environment Variables
+---
+
+# Environment Variables
+
+CodeceptJS reads several environment variables that change runtime behavior. They are useful for tuning CI runs, enabling extra logging, configuring the MCP server, or wiring values into the generated `codecept.conf.js`.
+
+This page is a reference for every `process.env.*` switch CodeceptJS reads or sets internally.
+
+## Quick Reference
+
+| Variable | Category | Default | Purpose |
+| :--- | :--- | :--- | :--- |
+| `profile` | Test execution | _unset_ | Profile name forwarded from `--profile`; readable from config and helpers. |
+| `CI` | Test execution | _unset_ | Auto-set by every CI provider; enables CI-aware behavior. |
+| `DONT_FAIL_ON_EMPTY_RUN` | Test execution | _unset_ | When set, do not fail CI if zero tests were executed. |
+| `RUNS_WITH_WORKERS` | Workers | _unset_ | Set to `true` while running in workers; read by helpers/plugins to branch behavior. |
+| `CODECEPT_WORKER_TIMEOUT` | Workers | `5m` | Hung-worker watchdog timeout. Accepts [ms](https://github.com/vercel/ms) strings (`30s`, `2m`, `1h`). |
+| `CODECEPT_AUTO_EXIT_TIMEOUT` | Workers | `2000` | Time in ms allowed for helper cleanup before forced `process.exit`. Set to `0` to disable. |
+| `DEBUG` | Debug | _unset_ | `debug` package namespace filter, e.g. `codeceptjs:*`, `codeceptjs:heal`. |
+| `HEADLESS` | Init template | _unset_ | Read by `setHeadlessWhen()` in the generated config to toggle headless mode. |
+| `BASE_URL` | Init template | `http://localhost` | Default URL written into the generated Playwright config. |
+
+## Test Execution
+
+### `profile`
+
+Set automatically when you pass `--profile <name>` to `run`, `run-workers`, `run-rerun`, `run-multiple`, or `interactive`. The value is available inside `codecept.conf.js`, helpers, and plugins via `process.env.profile`, which is the standard way to switch configuration based on environment:
+
+```js
+exports.config = {
+  helpers: {
+    Playwright: {
+      url: process.env.profile === 'staging' ? 'https://staging.example.com' : 'http://localhost:3000',
+    },
+  },
+}
+```
+
+### `CI`
+
+A de-facto standard variable exported by every major CI provider (GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis, etc.). CodeceptJS uses it for two CI-aware behaviors:
+
+- Extends the polling timeout for `submittedData()` to 60s (vs 2s locally).
+- Fails the run with exit code `1` if no tests were executed (see `DONT_FAIL_ON_EMPTY_RUN`).
+
+You should not need to set this manually.
+
+### `DONT_FAIL_ON_EMPTY_RUN`
+
+By default, when `CI` is set and no tests are executed (e.g. an over-restrictive `--grep`), CodeceptJS fails the run to surface false-positive green builds. Set `DONT_FAIL_ON_EMPTY_RUN=true` to keep the run green even when nothing ran.
+
+```yaml
+# .github/workflows/tests.yml
+env:
+  DONT_FAIL_ON_EMPTY_RUN: 'true'
+```
+
+## Workers
+
+### `RUNS_WITH_WORKERS`
+
+Automatically set to `'true'` while a `run-workers` invocation is active and reset to `'false'` when it finishes. Read it from helpers or plugins when you need to behave differently in worker mode — for example, to disable an interactive feature or change reporter output:
+
+```js
+if (process.env.RUNS_WITH_WORKERS === 'true') {
+  // running in a worker thread
+}
+```
+
+Do not set this manually.
+
+### `CODECEPT_WORKER_TIMEOUT`
+
+Per-worker hung-process watchdog. If a worker produces no output for this duration, it is auto-terminated and reported as failed. Accepts any string parsed by the [`ms`](https://github.com/vercel/ms) package: `30s`, `2m`, `5m`, `1h`. Defaults to `5m`.
+
+```sh
+CODECEPT_WORKER_TIMEOUT=10m npx codeceptjs run-workers 4
+```
+
+### `CODECEPT_AUTO_EXIT_TIMEOUT`
+
+Time in **milliseconds** that CodeceptJS waits for helper `_cleanup()` hooks to complete before calling `process.exit()`. Defaults to `2000`. Set to `0` to disable the auto-exit and let the Node event loop drain naturally — useful when long-running async work (e.g. report uploads) must complete after the test run.
+
+```sh
+CODECEPT_AUTO_EXIT_TIMEOUT=0 npx codeceptjs run
+```
+
+## Debug
+
+### `DEBUG`
+
+Standard [`debug`](https://www.npmjs.com/package/debug) package selector. CodeceptJS emits debug output under the `codeceptjs:*` namespace. Useful namespaces:
+
+| Namespace | Source |
+| :--- | :--- |
+| `codeceptjs:*` | All internal logs |
+| `codeceptjs:recorder` | Recorder/promise queue |
+| `codeceptjs:event` | Event dispatcher |
+| `codeceptjs:container` | DI container |
+| `codeceptjs:steps` | Step lifecycle |
+| `codeceptjs:exit` | Exit listener |
+| `codeceptjs:timeout` | Global timeout listener |
+| `codeceptjs:pause` | Interactive pause |
+| `codeceptjs:ai` | AI features |
+| `codeceptjs:heal` | Heal plugin |
+| `codeceptjs:analyze` | Analyze plugin |
+| `codeceptjs:retryFailedStep` | retryFailedStep plugin |
+| `codeceptjs:bdd` | Gherkin/BDD |
+
+```sh
+DEBUG="codeceptjs:*" npx codeceptjs run --verbose
+DEBUG="codeceptjs:heal" npx codeceptjs run
+DEBUG="codeceptjs:retryFailedStep" npx codeceptjs run
+```
+
+When `DEBUG` includes a `codeceptjs:` selector, the `heal` plugin keeps healing enabled in `--debug` mode (which otherwise disables it).
+
+## Init Template
+
+These variables are read by the configuration scaffolded by `codeceptjs init`. They have no effect unless your project's generated `codecept.conf.js` references them.
+
+### `HEADLESS`
+
+Read by [`setHeadlessWhen()`](https://www.npmjs.com/package/@codeceptjs/configure) in the generated config. When truthy, the browser starts headless. The init template wires this in so you can run `HEADLESS=true npx codeceptjs run` on CI without changing the config.
+
+### `BASE_URL`
+
+The init template uses `BASE_URL` (falling back to `http://localhost`) as the Playwright `url` value. After scaffolding, edit the generated config to change this default.

package/lib/codecept.js

@@ -316,7 +316,7 @@ class Codecept {
 
       try {
         event.emit(event.all.before, this)
-        mocha.run(async (failures) => await done(failures))
+        mocha.runner = mocha.run(async (failures) => await done(failures))
       } catch (e) {
         output.error(e.stack)
         reject(e)

package/lib/command/run-workers.js

@@ -87,19 +87,5 @@ export default async function (workerCount, selectedRuns, options) {
     process.exitCode = 1
   } finally {
     await workers.teardownAll()
-    
-    // Force exit if event loop doesn't clear naturally
-    // This is needed because worker threads may leave handles open
-    // even after proper cleanup, preventing natural process termination
-    if (!options.noExit) {
-      // Use beforeExit to ensure we run after all other exit handlers
-      // have set the correct exit code
-      process.once('beforeExit', (code) => {
-        // Give cleanup a moment to complete, then force exit with the correct code
-        setTimeout(() => {
-          process.exit(code || process.exitCode || 0)
-        }, 100)
-      })
-    }
   }
 }

package/lib/command/run.js

@@ -1,8 +1,7 @@
-import { getConfig, printError, getTestRoot, createOutputDir } from './utils.js'
+import { getConfig, printError, getTestRoot, createOutputDir, autoExit } from './utils.js'
 import Config from '../config.js'
 import store from '../store.js'
 import Codecept from '../codecept.js'
-import container from '../container.js'
 
 export default async function (test, options) {
   // registering options globally to use in config
@@ -43,19 +42,6 @@ export default async function (test, options) {
     process.exitCode = 1
   } finally {
     await codecept.teardown()
-
-    // Schedule a delayed exit to prevent process hanging due to browser helper event loops
-    // Only needed for Playwright/Puppeteer which keep the event loop alive
-    // Wait 1 second to allow final cleanup and output to complete
-    if (!process.env.CODECEPT_DISABLE_AUTO_EXIT) {
-      const helpers = container.helpers()
-      const hasBrowserHelper = helpers && (helpers.Playwright || helpers.Puppeteer || helpers.WebDriver)
-      
-      if (hasBrowserHelper) {
-        setTimeout(() => {
-          process.exit(process.exitCode || 0)
-        }, 1000).unref()
-      }
-    }
+    await autoExit()
   }
 }

package/lib/command/utils.js

@@ -107,6 +107,20 @@ export const createOutputDir = (config, testRoot) => {
   }
 }
 
+export async function autoExit() {
+  const timeout = parseInt(process.env.CODECEPT_AUTO_EXIT_TIMEOUT, 10)
+  if (timeout === 0) return
+  const exitTimeout = timeout || 2000
+
+  const { default: container } = await import('../container.js')
+  const helpers = container.helpers()
+  if (!helpers || !Object.values(helpers).some(h => typeof h._cleanup === 'function')) return
+
+  const { default: recorder } = await import('../recorder.js')
+  await Promise.race([recorder.promise(), new Promise(resolve => setTimeout(resolve, exitTimeout))])
+  process.exit(process.exitCode || 0)
+}
+
 export const findConfigFile = testsPath => {
   const extensions = ['js', 'ts']
   for (const ext of extensions) {

package/lib/heal.js

@@ -54,7 +54,9 @@ class Heal {
 
   async getCodeSuggestions(context) {
     const suggestions = []
+    const stepName = context.step?.name
     const recipes = matchRecipes(this.recipes, this.contextName)
+      .filter(r => !r.steps || !stepName || r.steps.includes(stepName))
 
     debug('Recipes', recipes)
 

package/lib/helper/Playwright.js

@@ -755,6 +755,11 @@ class Playwright extends Helper {
   }
 
   async _afterSuite() {
+    // Reset leftover test-level cleanup state (e.g. screenshot failures)
+    // so only errors from this suite teardown are evaluated below.
+    this.hasCleanupError = false
+    this.testFailures = []
+
     // Stop browser after suite completes
     // For restart strategies: stop after each suite
     // For session mode (restart:false): stop after the last suite

package/lib/plugin/aiTrace.js

@@ -92,6 +92,7 @@ export default function (config = {}) {
   let testStartTime
   let currentUrl = null
   let testFailed = false
+  let pendingArtifactCapture = null
   let firstFailedStepSaved = false
 
   const reportDir = config.output ? path.resolve(store.codeceptDir, config.output) : defaultConfig.output
@@ -129,6 +130,7 @@ export default function (config = {}) {
     currentUrl = null
     testFailed = false
     firstFailedStepSaved = false
+    pendingArtifactCapture = null
   })
 
   event.dispatcher.on(event.step.after, step => {
@@ -162,13 +164,12 @@ export default function (config = {}) {
       return
     }
 
-    const stepPersistPromise = persistStep(step).catch(err => {
+    recorder.add(`aiTrace step persistence: ${step.toString()}`, () => persistStep(step).catch(err => {
       output.debug(`aiTrace: Error saving step: ${err.message}`)
-    })
-    recorder.add(`wait aiTrace step persistence: ${step.toString()}`, () => stepPersistPromise, true)
+    }), true)
   })
 
-  event.dispatcher.on(event.step.failed, async step => {
+  event.dispatcher.on(event.step.failed, step => {
     if (!currentTest) return
     if (step.status === 'queued' && testFailed) {
       output.debug(`aiTrace: Skipping queued failed step "${step.toString()}" - testFailed: ${testFailed}`)
@@ -188,11 +189,9 @@ export default function (config = {}) {
       }
       existingStep.status = 'failed'
 
-      try {
-        await captureArtifactsForStep(step, existingStep, existingStep.prefix)
-      } catch (err) {
+      pendingArtifactCapture = captureArtifactsForStep(step, existingStep, existingStep.prefix).catch(err => {
         output.debug(`aiTrace: Error updating failed step: ${err.message}`)
-      }
+      })
     } else {
       if (stepNum === -1) return
       if (isStepIgnored(step)) return
@@ -218,11 +217,9 @@ export default function (config = {}) {
       steps.push(stepData)
       firstFailedStepSaved = true
 
-      try {
-        await captureArtifactsForStep(step, stepData, stepPrefix)
-      } catch (err) {
+      pendingArtifactCapture = captureArtifactsForStep(step, stepData, stepPrefix).catch(err => {
         output.debug(`aiTrace: Error capturing failed step artifacts: ${err.message}`)
-      }
+      })
     }
   })
 
@@ -238,7 +235,13 @@ export default function (config = {}) {
     if (hookName === 'BeforeSuite' || hookName === 'AfterSuite') {
       return
     }
-    persist(test, 'failed')
+    recorder.add('aiTrace:persist failed', async () => {
+      if (pendingArtifactCapture) {
+        await pendingArtifactCapture
+        pendingArtifactCapture = null
+      }
+      persist(test, 'failed')
+    }, true)
   })
 
   async function persistStep(step) {

package/lib/plugin/analyze.js

@@ -12,6 +12,7 @@ const ai = aiModule.default || aiModule
 import colors from 'chalk'
 import ora from 'ora'
 import event from '../event.js'
+import recorder from '../recorder.js'
 
 import output from '../output.js'
 
@@ -227,14 +228,14 @@ export default function (config = {}) {
     console.log('Enabled AI analysis')
   })
 
-  event.dispatcher.on(event.all.result, async result => {
+  event.dispatcher.on(event.all.result, result => {
     if (!isMainThread) return // run only on main thread
     if (!ai.isEnabled) {
       console.log('AI is disabled, no analysis will be performed. Run tests with --ai flag to enable it.')
       return
     }
 
-    printReport(result)
+    recorder.add('analyze:print-ai-report', () => printReport(result), true)
   })
 
   event.dispatcher.on(event.workers.result, async result => {
@@ -248,7 +249,7 @@ export default function (config = {}) {
       return
     }
 
-    printReport(result)
+    await printReport(result)
   })
 
   async function printReport(result) {
@@ -294,7 +295,7 @@ export default function (config = {}) {
       console.error('Error analyzing failed tests', err)
     }
 
-    if (!Object.keys(container.plugins()).includes('pageInfo')) {
+    if (!Object.keys(Container.plugins()).includes('pageInfo')) {
       console.log('To improve analysis, enable pageInfo plugin to get more context for failed tests.')
     }
   }

package/lib/plugin/heal.js

@@ -80,6 +80,7 @@ export default function (config = {}) {
   event.dispatcher.on(event.test.before, test => {
     currentTest = test
     healedSteps = 0
+    healTries = 0
     caughtError = null
   })
 
@@ -94,7 +95,9 @@ export default function (config = {}) {
     if (trigger.on === 'file' && !matchStepFile(step, trigger.path, trigger.line)) return
 
     recorder.catchWithoutStop(async err => {
+      if (healTries >= config.healLimit) throw err
       isHealing = true
+      healTries++
       if (caughtError === err) throw err // avoid double handling
       caughtError = err
 
@@ -121,8 +124,6 @@ export default function (config = {}) {
 
       await heal.healStep(step, err, { test })
 
-      healTries++
-
       recorder.add('close healing session', () => {
         recorder.reset()
         recorder.session.restore('heal')

package/lib/plugin/pageInfo.js

@@ -40,10 +40,10 @@ const defaultConfig = {
 export default function (config = {}) {
   config = Object.assign(defaultConfig, config)
 
-  const helper = pickActingHelper(Container.helpers())
-  if (!helper) return
-
   event.dispatcher.on(event.test.failed, test => {
+    const helper = pickActingHelper(Container.helpers())
+    if (!helper) return
+
     const pageState = {}
 
     recorder.add('pageInfo capture', async () => {
@@ -60,8 +60,6 @@ export default function (config = {}) {
         if (captured.html) {
           const htmlPath = path.join(store.outputDir, captured.html)
           pageState.htmlSnapshot = htmlPath
-          // Scan raw HTML (pre-cleanHtml) so error classes containing digits
-          // or trash-class prefixes aren't stripped before detection.
           const htmlForScan = captured.htmlRaw || (() => {
             try { return fs.readFileSync(htmlPath, 'utf8') } catch { return '' }
           })()
@@ -90,7 +88,7 @@ export default function (config = {}) {
           } catch {}
         }
       } catch {}
-    })
+    }, true)
 
     recorder.add('Save page info', () => {
       test.addNote('pageInfo', pageStateToMarkdown(pageState))
@@ -99,7 +97,7 @@ export default function (config = {}) {
       fs.writeFileSync(pageStateFileName, pageStateToMarkdown(pageState))
       test.artifacts.pageInfo = pageStateFileName
       return pageState
-    })
+    }, true)
   })
 }
 

package/lib/plugin/retryFailedStep.js

@@ -1,7 +1,10 @@
+import debugModule from 'debug'
 import event from '../event.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
 
+const debug = debugModule('codeceptjs:retryFailedStep')
+
 const defaultConfig = {
   retries: 3,
   defaultIgnoredSteps: ['amOnPage', 'wait*', 'send*', 'execute*', 'run*', 'have*'],
@@ -147,9 +150,7 @@ export default function (config) {
     test.opts.conditionalRetries = config.retries
     test.opts.stepRetryPriority = stepRetryPriority
 
-    if (process.env.DEBUG_RETRY_PLUGIN) {
-      console.log('[retryFailedStep] applying retries =', config.retries, 'for test', test.title)
-    }
+    debug('applying retries = %d for test %s', config.retries, test.title)
     recorder.retry(config)
   })
 

package/lib/plugin/screencast.js

@@ -106,6 +106,12 @@ function wireScreencast(mode, options) {
     state.startedAt = options.subtitles ? Date.now() : null
   })
 
+  event.dispatcher.on(event.test.started, test => {
+    if (!options.video || state.startQueued) return
+    state.startQueued = true
+    recorder.add('screencast:start', async () => startScreencast(state.test, options, state), true)
+  })
+
   event.dispatcher.on(event.step.started, step => {
     if (state.steps) {
       const at = Date.now()
@@ -116,10 +122,6 @@ function wireScreencast(mode, options) {
         title: stepTitle(step),
       }
     }
-    if (!options.video || state.startQueued || !state.test) return
-    state.startQueued = true
-    const test = state.test
-    recorder.add('screencast:start', async () => startScreencast(test, options, state), true)
   })
 
   if (options.subtitles) {

package/lib/workers.js

@@ -547,10 +547,11 @@ class Workers extends EventEmitter {
     if (this.isPoolMode) {
       this.activeWorkers.set(worker, { available: true, workerIndex: null })
     }
-    
+
     // Track last activity time to detect hanging workers
     let lastActivity = Date.now()
     let currentTest = null
+    let autoTerminated = false
     const workerTimeout = process.env.CODECEPT_WORKER_TIMEOUT ? ms(process.env.CODECEPT_WORKER_TIMEOUT) : ms('5m')
     
     const timeoutChecker = setInterval(() => {
@@ -611,6 +612,13 @@ class Workers extends EventEmitter {
             })
           }
 
+          const exitTimeout = parseInt(process.env.CODECEPT_AUTO_EXIT_TIMEOUT, 10)
+          if (exitTimeout === 0) break
+          setTimeout(() => {
+            autoTerminated = true
+            worker.terminate()
+          }, exitTimeout || 2000)
+
           break
         case event.suite.before:
           {
@@ -741,8 +749,8 @@ class Workers extends EventEmitter {
     worker.on('exit', (code) => {
       clearInterval(timeoutChecker)
       this.closedWorkers += 1
-      
-      if (code !== 0) {
+
+      if (code !== 0 && !autoTerminated) {
         console.error(`[Main] Worker exited with code ${code}`)
         if (currentTest) {
           console.error(`[Main] Last test running: ${currentTest}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.0-rc.20",
+  "version": "4.0.0-rc.21",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [