fix(core): make the whole internal API work from tests/page objects under tsx/cjs (#5635)

[mirao]

Fixes #5635

Problem

The internal API (https://codecept.io/architecture#the-internal-api) is supposed to work from tests, page objects and fragments — not only helpers. In 4.x it works only from helpers:

import { config } from "codeceptjs";

Scenario("test something", ({ I }) => {
  // TypeError: Cannot read properties of undefined (reading 'Playwright')
  console.log(config.get().helpers.Playwright.browser);
});

config was just the reported symptom — container, recorder, event and store are affected the same way. Works fine in 3.x.

Root cause

Same dual-realm split as #5634, but for the public singletons.

CodeceptJS 4.x is native ESM, but Mocha loads test files through a synchronous require() (the CommonJS realm). Under a CJS loader such as tsx/cjs (the setup the official Quickstart generates), a test that imports the internal API gets a second, disconnected CJS copy of each lib module and its singleton — a copy the runner never populates:

• config.get() returns {},
• container has no helpers/support/plugins,
• recorder is never started (so effects short-circuit),
• the event dispatcher has no listeners.

Helpers don't hit this because they're loaded via import() (lib/container.js), i.e. the ESM realm, so they share the live singletons — which is why the bug looked like "helpers only".

Fix

Share each stateful singleton across realms through globalThis, the same mechanism used for the recorder/container bridges in #5634, generalized:

• lib/realm.js (new) — realmSingleton(key, factory) stores the instance 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.
• Applied to lib/recorder.js (recorder object), lib/container.js (state object), lib/event.js (dispatcher), lib/store.js and lib/output.js.
• lib/config.js refactored to the same holder pattern.

Under pure ESM the modules load once, so there is no behavior change on the ESM path.

Tests

Adds a runner regression test driving a real tsx/cjs project:

• test/data/internal-api-tsx-cjs/ — fixture (config with require: ["tsx/cjs"], a helper, and a test that imports the internal API through the CJS loader).
• test/runner/internal_api_tsx_test.js — asserts config, container, recorder, event and store all resolve to the live singletons from a test, and that a helper (ESM realm) sees the same config.

It fails without the fix and passes with it. The full unit suite (747 passing) and runner suite continue to pass.

🤖 Generated with Claude Code

[DavertMik]

what is realm? 🙄

[DavertMik]

I think Claude took the wrong path here

First: what the actual problem is? What we are trying to achieve?
Which exact internal API should work from tests?

I don't think that most of internal APIs should work from tests, as tests are business logic driven, and internal APIs are implementation details. I'd rather not to explose implementatoin details into tests / page objetcs themselves and keeped correct level of abstractoin

[mirao]

I think Claude took the wrong path here

First: what the actual problem is? What we are trying to achieve? Which exact internal API should work from tests?

I don't think that most of internal APIs should work from tests, as tests are business logic driven, and internal APIs are implementation details. I'd rather not to explose implementatoin details into tests / page objetcs themselves and keeped correct level of abstractoin

In 3.x I used import { container } from "codeceptjs" or import { config } from "codeceptjs" in tests, because I wanted to get some configuration stuff without calling a helper method for it, e.g. browser or environment.

After the migration to 4.x it stopped working 😞 .

Also the stuff like

import { within } from "codeceptjs";
import { tryTo } from "codeceptjs/effects";

stopped working (#5632) in 4.x

Therefore I needed some solution.

[DavertMik]

Thanks! I will try to ask my claude about this
I think importing config is good point, while importing container into tests is not

[mirao]

OK, thanks. Maybe https://codecept.io/architecture#the-internal-api should be then updated so that the scope of internal API is more clear for users (where and which methods can be used).

As for the issue with the effects such as tryTo(), within(), they should definitely work from tests or page objects (actually their usage in helpers doesn't make sense, but who knows). I reported it in the issue #5632 and this PR #5636 was intended to solve the issue as well.