fix(workers): make hardcoded run-workers overall timeout configurable

The `run-workers` command has had a hardcoded 10-minute overall timeout
since #5370 ("fix workers crash"). When the timeout fires, ALL still-running
workers are force-terminated and only results from naturally-finished workers
make it into the aggregated summary.

For suites whose total wall-clock with N workers is in the same ballpark
as 10 minutes, this guarantees a portion of tests will be silently dropped
from the report — even on a healthy run. There is currently no CLI flag,
env var, or config option to override.

Make the timeout configurable, with `600000` ms (10 min) preserved as
default for backward compatibility:

1. `CODECEPT_WORKERS_TIMEOUT` env var (ms) — highest precedence
2. `workersTimeout` field in codecept.conf (ms)
3. Default `600000`

Setting the value to `0` (or any non-positive number) disables the
timeout entirely.

Adds 6 unit tests covering resolution order, env-over-config precedence,
disabled mode, and non-numeric fallback.

Author: gololdf1sh

lib/workers.js

@@ -501,6 +501,26 @@ class Workers extends EventEmitter {
     return runHook(this.codecept.config.teardownAll, 'teardownAll')
   }
 
+  /**
+   * Resolves the overall `run-workers` timeout in milliseconds.
+   *
+   * Resolution order:
+   * 1. `CODECEPT_WORKERS_TIMEOUT` env var (numeric, ms)
+   * 2. `workersTimeout` in codecept.conf (ms)
+   * 3. Default: 600000 (10 minutes)
+   *
+   * Set the value to `0` (or any non-positive number) to disable the timeout entirely.
+   *
+   * @returns {number} timeout in milliseconds
+   */
+  _getWorkersTimeoutMs() {
+    const envTimeout = parseInt(process.env.CODECEPT_WORKERS_TIMEOUT, 10)
+    if (Number.isFinite(envTimeout)) return envTimeout
+    const configTimeout = this.codecept?.config?.workersTimeout
+    if (Number.isFinite(configTimeout)) return configTimeout
+    return 600000
+  }
+
   async run() {
     await this._ensureInitialized()
     recorder.startUnlessRunning()
@@ -521,22 +541,27 @@ class Workers extends EventEmitter {
       // Workers are already running, this is just a placeholder step
     })
 
-    // Add overall timeout to prevent infinite hanging
-    const overallTimeout = setTimeout(() => {
-      console.error('[Main] Overall timeout reached (10 minutes). Force terminating remaining workers...')
-      workerThreads.forEach(w => {
-        try {
-          w.terminate()
-        } catch (e) {
-          // ignore
-        }
-      })
-      this._finishRun()
-    }, 600000) // 10 minutes
+    // Overall timeout to prevent infinite hanging. See _getWorkersTimeoutMs() for resolution rules.
+    const overallTimeoutMs = this._getWorkersTimeoutMs()
+    let overallTimeout
+    if (overallTimeoutMs > 0) {
+      overallTimeout = setTimeout(() => {
+        const minutes = (overallTimeoutMs / 60000).toFixed(1)
+        console.error(`[Main] Overall timeout reached (${minutes} minutes). Force terminating remaining workers...`)
+        workerThreads.forEach(w => {
+          try {
+            w.terminate()
+          } catch (e) {
+            // ignore
+          }
+        })
+        this._finishRun()
+      }, overallTimeoutMs)
+    }
 
     return new Promise(resolve => {
       this.on('end', () => {
-        clearTimeout(overallTimeout)
+        if (overallTimeout) clearTimeout(overallTimeout)
         resolve()
       })
     })

test/unit/worker_test.js

@@ -382,4 +382,55 @@ describe('Workers', function () {
 
     workers.run()
   })
+
+  describe('_getWorkersTimeoutMs', () => {
+    let savedEnv
+    let workers
+
+    beforeEach(() => {
+      savedEnv = process.env.CODECEPT_WORKERS_TIMEOUT
+      delete process.env.CODECEPT_WORKERS_TIMEOUT
+      workers = new Workers(1, { by: 'test', testConfig: './test/data/sandbox/codecept.workers.conf.js' })
+      // Stub the codecept config so we don't need to await initialization for this pure-logic test
+      workers.codecept = { config: {} }
+    })
+
+    afterEach(() => {
+      if (savedEnv === undefined) {
+        delete process.env.CODECEPT_WORKERS_TIMEOUT
+      } else {
+        process.env.CODECEPT_WORKERS_TIMEOUT = savedEnv
+      }
+    })
+
+    it('returns default 10 minutes when nothing is configured', () => {
+      expect(workers._getWorkersTimeoutMs()).to.equal(600000)
+    })
+
+    it('uses CODECEPT_WORKERS_TIMEOUT env var when set', () => {
+      process.env.CODECEPT_WORKERS_TIMEOUT = '90000'
+      expect(workers._getWorkersTimeoutMs()).to.equal(90000)
+    })
+
+    it('uses workersTimeout from config when env is not set', () => {
+      workers.codecept.config.workersTimeout = 120000
+      expect(workers._getWorkersTimeoutMs()).to.equal(120000)
+    })
+
+    it('env var takes precedence over config', () => {
+      process.env.CODECEPT_WORKERS_TIMEOUT = '15000'
+      workers.codecept.config.workersTimeout = 999999
+      expect(workers._getWorkersTimeoutMs()).to.equal(15000)
+    })
+
+    it('returns 0 when env var is "0" so the timeout can be disabled in run()', () => {
+      process.env.CODECEPT_WORKERS_TIMEOUT = '0'
+      expect(workers._getWorkersTimeoutMs()).to.equal(0)
+    })
+
+    it('falls back to default when env var is non-numeric', () => {
+      process.env.CODECEPT_WORKERS_TIMEOUT = 'not-a-number'
+      expect(workers._getWorkersTimeoutMs()).to.equal(600000)
+    })
+  })
 })

typings/index.d.ts

@@ -360,6 +360,13 @@ declare namespace CodeceptJS {
      */
     teardownAll?: (() => Promise<void>) | boolean | string
 
+    /**
+     * Overall timeout for `run-workers` (milliseconds). After this time, any worker
+     * still running is force-terminated and the run finishes. Default: `600000` (10 min).
+     * Set to `0` to disable. Can also be overridden via `CODECEPT_WORKERS_TIMEOUT` env var.
+     */
+    workersTimeout?: number
+
     /** Enable [localized test commands](https://codecept.io/translation/) */
     translation?: string