refactor(config): for-of hook loops, swallow per-hook errors via applyHook

Three changes asked for on the previous hook refactor:

- Replace the for-i loops in Config.create and Config.runPendingHooks
  with for-of. Both rely on Array iterator semantics — newly pushed
  hooks (e.g. a hook that registers another hook) are still picked up
  in the same pass because the iterator re-checks length on each step.

- Centralize hook execution in a single applyHook() helper that wraps
  the call in try/finally. A broken hook now logs through
  globalThis.codeceptjs.output (or stderr when the runner isn't up
  yet) and is marked ran=true regardless, so a poison entry can't
  block the rest of the pass or get retried by runPendingHooks.
  Callers don't touch hook.ran themselves.

- Tighten the comment over the globalThis.codeceptjs block in
  lib/codecept.js. The previous wording implied end-user projects
  didn't need it — they do, because @codeceptjs/configure is
  typically imported at the top of a user's codecept.conf.js and
  registers hooks via the in-process registry before Config.load
  even returns. setup.mjs handles the same contract for mocha tests
  via .mocharc require.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DavertMik

lib/codecept.js

@@ -33,12 +33,12 @@ import globalRetryListener from './listener/globalRetry.js'
 import exitListener from './listener/exit.js'
 import emptyRunListener from './listener/emptyRun.js'
 
-// Register an in-process handle so companion packages (@codeceptjs/configure,
-// @codeceptjs/expect-helper, @codeceptjs/helper) can reach the running
-// framework without doing a top-level `import 'codeceptjs'` — that bare
-// specifier doesn't resolve in this repo's own checkout (the project IS the
-// codeceptjs package). End-user projects don't need this either way; npm
-// resolves `codeceptjs` from their node_modules and the bare import works.
+// Companion packages (@codeceptjs/configure, @codeceptjs/expect-helper,
+// @codeceptjs/helper) read framework singletons through globalThis.codeceptjs.
+// `@codeceptjs/configure` in particular runs at the top of a user's
+// codecept.conf.js, before `Config.load` returns — so the registry has to
+// exist by the time this module is imported, not later during init.
+// In tests we install the same handle from .mocharc → test/support/setup.mjs.
 if (!globalThis.codeceptjs) {
   globalThis.codeceptjs = { config: Config, container, event, output, recorder, Helper }
 }

lib/config.js

@@ -32,10 +32,27 @@ const defaultConfig = {
   ],
 }
 
-// Array<{ fn: (cfg) => void, ran: boolean }>
+// Array<{ fn: (cfg) => void, ran: boolean, error?: Error }>
 let hooks = []
 let config = {}
 
+// Apply a single hook against `cfg`, swallowing errors so one broken hook
+// can't take down the whole run. The failure is logged through the
+// framework's own output module (when available) so it shows up in test
+// reports; the hook is still marked ran so it doesn't get retried.
+function applyHook(hook, cfg) {
+  try {
+    hook.fn(cfg)
+  } catch (err) {
+    hook.error = err
+    const out = globalThis.codeceptjs?.output
+    if (out && typeof out.error === 'function') out.error(`config hook failed: ${err.message}`)
+    else console.error('config hook failed:', err)
+  } finally {
+    hook.ran = true
+  }
+}
+
 const configFileNames = ['codecept.config.js', 'codecept.conf.js', 'codecept.js', 'codecept.config.cjs', 'codecept.conf.cjs', 'codecept.config.ts', 'codecept.conf.ts']
 
 /**
@@ -50,12 +67,11 @@ class Config {
    */
   static create(newConfig) {
     config = deepMerge(deepClone(defaultConfig), newConfig)
-    // Re-apply every hook against the freshly built config and mark them ran;
-    // hooks added later (e.g. from plugin boot) stay pending until runPendingHooks.
-    for (let i = 0; i < hooks.length; i++) {
-      hooks[i].fn(config)
-      hooks[i].ran = true
-    }
+    // Re-apply every hook against the freshly built config; hooks added later
+    // (e.g. from plugin boot) stay pending until runPendingHooks. Array
+    // iterators re-check length on each step, so hooks pushed during a hook
+    // execution are visited in this same pass.
+    for (const hook of hooks) applyHook(hook, config)
     return config
   }
 
@@ -132,23 +148,22 @@ class Config {
 
   /**
    * Run every hook that hasn't been applied to the current config yet.
-   * Hooks added after `Config.create()` (e.g. by a plugin's boot code) stay
+   * Hooks added after `Config.create()` (e.g. from plugin boot code) stay
    * pending until this is called; once it runs, they're marked applied so
-   * subsequent calls are no-ops.
+   * subsequent calls are no-ops. Hooks added while pending hooks are running
+   * are picked up in the same pass (the array iterator re-checks length).
    *
-   * Hooks registered while pending hooks are running are picked up too —
-   * the loop re-checks length on each iteration.
+   * Failures are logged through `output.error` and don't abort the loop —
+   * a broken hook can't poison the run, but its error is visible.
    *
    * @param {Object<string, *>} [cfg] target config (defaults to the live singleton)
    * @return {boolean} true if any hook ran
    */
   static runPendingHooks(cfg = config) {
     let ran = false
-    for (let i = 0; i < hooks.length; i++) {
-      const h = hooks[i]
-      if (h.ran) continue
-      h.fn(cfg)
-      h.ran = true
+    for (const hook of hooks) {
+      if (hook.ran) continue
+      applyHook(hook, cfg)
       ran = true
     }
     return ran