fix(core): make the whole internal API realm-agnostic under tsx/cjs (#5635)

Generalizes the config fix to every stateful internal-API singleton. The internal
API (config, container, recorder, event, store, output) is documented to work from
tests, page objects and fragments — not only helpers — but test files are loaded
through Mocha's synchronous require() (the CommonJS realm) under a CJS loader such as
tsx/cjs, while the framework runs as native ESM. So importing any of these from a test
loaded a second, disconnected CJS copy: config.get() returned {}, the container had no
helpers, the recorder was never started, the event dispatcher had no listeners. Helpers
were unaffected because they load via import() (the ESM realm).

Add lib/realm.js with realmSingleton(key, factory), which stores each singleton on
globalThis so every realm resolves to the one the runner operates on (the ESM runner
loads these modules first during bootstrap, so it wins the key; later CJS copies reuse
it). Apply it to recorder, container state, the event dispatcher, store and output, and
refactor config.js to the same holder pattern. Under pure ESM the modules load once, so
there is no behavior change.

Broadens the regression fixture to assert config/container/recorder/event/store all
resolve to the live singletons from a test imported via tsx/cjs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: mirao

lib/config.js

@@ -3,6 +3,7 @@ import path from 'path'
 import { createRequire } from 'module'
 import { fileExists, isFile, deepMerge, deepClone, resolveImportModulePath } from './utils.js'
 import { transpileTypeScript, cleanupTempFiles, fixErrorStack } from './utils/typescript.js'
+import { realmSingleton } from './realm.js'
 
 const defaultConfig = {
   output: './_output',
@@ -35,20 +36,17 @@ const defaultConfig = {
 
 // Array<{ fn: (cfg) => void, ran: boolean, error?: Error }>
 let hooks = []
-let config = {}
-
-// Expose the live config object globally so a duplicate copy of the framework
-// (loaded as CommonJS when a test, page object or fragment does
-// `import { config } from 'codeceptjs'` through a CJS loader such as tsx/cjs)
-// reads the same config the runner actually loaded. Test files are loaded via
-// Mocha's synchronous require() (CJS realm) while the framework runs as ESM, so
-// the CJS copy would otherwise see its own empty module-scoped `config = {}`.
-// Helpers don't hit this because they're loaded via import() (the ESM realm).
-// Mirrors the globalThis bridges in recorder.js and container.js.
+
+// Shared across realms (see realm.js). config is reassigned wholesale by create/append/
+// reset, so the live value lives in a stable holder object that every realm resolves to.
+// A test, page object or fragment that does `import { config } from "codeceptjs"` is loaded
+// as CommonJS (Mocha's require()) while the runner is ESM; without the shared holder the
+// CJS copy reads its own empty `{}`. Helpers don't hit this — they load via import() (ESM).
+const configHolder = realmSingleton('__codeceptjs_config', () => ({ value: {} }))
+
 function setConfig(value) {
-  config = value
-  if (typeof globalThis !== 'undefined') globalThis.__codeceptjs_config = config
-  return config
+  configHolder.value = value
+  return value
 }
 
 // Apply a single hook against `cfg`, swallowing errors so one broken hook
@@ -86,8 +84,8 @@ class Config {
     // (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
+    for (const hook of hooks) applyHook(hook, configHolder.value)
+    return configHolder.value
   }
 
   /**
@@ -151,7 +149,7 @@ class Config {
    * @return {*}
    */
   static get(key, val) {
-    const cfg = (typeof globalThis !== 'undefined' && globalThis.__codeceptjs_config) || config
+    const cfg = configHolder.value
     if (key) {
       return cfg[key] || val
     }
@@ -175,7 +173,7 @@ class Config {
    * @param {Object<string, *>} [cfg] target config (defaults to the live singleton)
    * @return {boolean} true if any hook ran
    */
-  static runPendingHooks(cfg = config) {
+  static runPendingHooks(cfg = configHolder.value) {
     let ran = false
     for (const hook of hooks) {
       if (hook.ran) continue
@@ -210,7 +208,7 @@ class Config {
    * @return {Object<string, *>}
    */
   static append(additionalConfig) {
-    return setConfig(deepMerge(config, additionalConfig))
+    return setConfig(deepMerge(configHolder.value, additionalConfig))
   }
 
   /**

lib/container.js

@@ -25,6 +25,7 @@ import Result from './result.js'
 import ai from './ai.js'
 import actorFactory from './actor.js'
 import Config from './config.js'
+import { realmSingleton } from './realm.js'
 
 let asyncHelperPromise
 
@@ -33,7 +34,12 @@ let beforeCalledSet = new Set()
 export function getBeforeCalledSet() { return beforeCalledSet }
 export function resetBeforeCalledSet() { beforeCalledSet = new Set() }
 
-let container = {
+// Shared across realms (see realm.js): the runner (ESM) populates this state in
+// Container.create(); a test/page object that does `import { container } from "codeceptjs"`
+// is loaded as CommonJS and would otherwise read an empty, never-populated copy. Pointing
+// the module variable at the shared object means the static accessors in every realm
+// operate on the live helpers/support/plugins.
+let container = realmSingleton('__codeceptjs_container_state', () => ({
   helpers: {},
   support: {},
   proxySupport: {},
@@ -50,7 +56,7 @@ let container = {
   result: null,
   sharedKeys: new Set(), // Track keys shared via share() function
   tsFileMapping: null, // TypeScript file mapping for error stack fixing
-}
+}))
 
 /**
  * Dependency Injection Container

lib/event.js

@@ -2,12 +2,18 @@ import debugModule from 'debug'
 const debug = debugModule('codeceptjs:event')
 import events from 'events'
 import output from './output.js'
+import { realmSingleton } from './realm.js'
 
 const MAX_LISTENERS = 200
 
-const dispatcher = new events.EventEmitter()
-
-dispatcher.setMaxListeners(MAX_LISTENERS)
+// Shared across realms so listeners registered from a test (CJS realm, via
+// `import { event } from "codeceptjs"`) and events emitted by the runner (ESM realm)
+// reach the same EventEmitter. Without this the test subscribes to a dead dispatcher.
+const dispatcher = realmSingleton('__codeceptjs_dispatcher', () => {
+  const d = new events.EventEmitter()
+  d.setMaxListeners(MAX_LISTENERS)
+  return d
+})
 
 // Increase process max listeners to prevent warnings for beforeExit and other events
 if (typeof process.setMaxListeners === 'function') {

lib/output.js

@@ -1,6 +1,7 @@
 import colors from 'chalk'
 import figures from 'figures'
 import { maskData, shouldMaskData, getMaskConfig } from './utils/mask_data.js'
+import { realmSingleton } from './realm.js'
 
 const styles = {
   error: colors.bgRed.white.bold,
@@ -21,7 +22,7 @@ let newline = true
  * @alias output
  * @namespace
  */
-const output = {
+const output = realmSingleton('__codeceptjs_output', () => ({
   colors,
   styles,
   print,
@@ -302,7 +303,7 @@ const output = {
     msg += '  '
     print(status + style(msg) + colors.grey(` // ${duration}`))
   },
-}
+}))
 
 export default output
 

lib/realm.js

@@ -0,0 +1,25 @@
+/**
+ * Cross-realm singleton sharing.
+ *
+ * CodeceptJS 4.x runs as native ESM, but test files, page objects and fragments are
+ * loaded through Mocha's synchronous require() (the CommonJS realm) under a CJS loader
+ * such as tsx/cjs (the setup the official Quickstart generates). So when user code does
+ * `import { recorder } from "codeceptjs"`, Node materializes a SECOND, disconnected CJS
+ * copy of the lib modules and their singletons — a copy the runner never populates, so
+ * the internal API silently reads empty/never-started state. Helpers don't hit this
+ * because they're loaded via import() (the ESM realm) and share the live singletons.
+ *
+ * Resolving the instance from globalThis (a single object shared across realms) makes
+ * every realm use the very object the runner operates on. The runner (ESM) always loads
+ * these modules first during bootstrap, so it wins the `key`; later CJS copies reuse it.
+ * Under pure ESM the module loads once, so there is no behavior change.
+ *
+ * @template T
+ * @param {string} key
+ * @param {() => T} factory
+ * @returns {T}
+ */
+export function realmSingleton(key, factory) {
+  if (globalThis[key] === undefined) globalThis[key] = factory()
+  return globalThis[key]
+}

lib/recorder.js

@@ -5,6 +5,7 @@ import chalk from 'chalk'
 import { printObjectProperties } from './utils.js'
 import output from './output.js'
 import { TimeoutError } from './timeout.js'
+import { realmSingleton } from './realm.js'
 const MAX_TASKS = 100
 
 let promise
@@ -30,7 +31,7 @@ const defaultRetryOptions = {
  * @alias recorder
  * @interface
  */
-export default {
+const recorder = {
   /**
    * @type {Array<Object<string, *>>}
    * @inner
@@ -425,6 +426,8 @@ export default {
   },
 }
 
+export default realmSingleton('__codeceptjs_recorder', () => recorder)
+
 function getTimeoutPromise(timeoutMs, taskName) {
   let timer
   if (timeoutMs) debug(`Timing out in ${timeoutMs}ms`)

lib/store.js

@@ -1,8 +1,10 @@
+import { realmSingleton } from './realm.js'
+
 /**
  * Global store for current session
  * @namespace
  */
-const store = {
+const store = realmSingleton('__codeceptjs_store', () => ({
   // --- Required (set once via initialize(), immutable after) ---
 
   /** @type {string | null} */
@@ -110,6 +112,6 @@ const store = {
     this._codeceptDir = opts.codeceptDir
     this._outputDir = opts.outputDir
   },
-}
+}))
 
 export default store

test/data/config-tsx-cjs/config_test.ts

@@ -3,10 +3,10 @@ export const config: CodeceptJS.MainConfig = {
   output: "./output",
   helpers: {
     ConfigHelper: {
-      require: "./config_helper.js",
+      require: "./internal_api_helper.js",
       marker: "config-marker-123"
     }
   },
-  name: "config-tsx-cjs-test",
+  name: "internal-api-tsx-cjs-test",
   require: ["tsx/cjs"]
 };

test/data/config-tsx-cjs/codecept.conf.ts …ta/internal-api-tsx-cjs/codecept.conf.tstest/data/config-tsx-cjs/codecept.conf.ts renamed to test/data/internal-api-tsx-cjs/codecept.conf.ts test/data/config-tsx-cjs/codecept.conf.ts renamed to test/data/internal-api-tsx-cjs/codecept.conf.ts

@@ -6,8 +6,8 @@ const Config = ConfigModule.default || ConfigModule
 
 class ConfigHelper extends Helper {
   reportConfig() {
-    // Helper is loaded via import() (ESM realm), so it has always shared the live config.
-    console.log(`CONFIG_FROM_HELPER marker=${Config.get().helpers.ConfigHelper.marker}`)
+    // Helper is loaded via import() (the ESM realm), so it has always shared the live config.
+    console.log(`API_HELPER marker=${Config.get().helpers.ConfigHelper.marker}`)
   }
 }