fix(core): load Mocha test files as ES Modules (fixes internal-API imports from tests, #5636)

[DavertMik]

Problem

A test that imports the internal API — import { config } from "codeceptjs" — gets a value that looks empty/disconnected from the running session (#5636).

Root cause: Mocha loads test files with synchronous require(). Under tsx/cjs that creates a second CommonJS copy of every lib/* module, each with its own module-level singletons (config, container, recorder, event, store). The test imports the second copy, whose singletons were never populated by the runner. Helpers don't have this problem because the container loads them with await import() (ESM).

Fix

Load test files the same way helpers are loaded — through await import() — so the whole run shares one ES module graph and the plain import resolves to the live instance. No bridge, no globalThis indirection.

New lib/mocha/loadTests.js mirrors Mocha's own loadFiles (lazyLoadFiles(true) so mocha.run() won't sync-require, then per file emit pre-require → await import() → require/post-require). That preserves:

• teardown hooks (attached in mocha/ui.js on post-require),
• the gherkin .feature path,
• the duplicate / missing-Feature validation.

All synchronous mocha.loadFiles() sites converted: codecept.run(), rerun, workers (parent grouping + worker threads), dry-run, check. The factory's loadFiles override is removed.

TypeScript loader migration

tsx/cjs is a require hook and can't transpile files loaded via import(). So:

• requireModules() auto-maps tsx/cjs → tsx/esm with a deprecation notice (existing configs keep working),
• tsx/esm requires "type": "module" in package.json — init now writes it, and an ERR_REQUIRE_CYCLE_MODULE guard tells users to add it,
• docs (typescript, configuration, installation, parallel) updated.

⚠️ Breaking changes

• Programmatic Workers grouping API is now async: createGroupsOfTests, createGroupsOfSuites, addTestFiles, splitTestsByGroups return Promises (you cannot load ES modules synchronously). Callers must await. Docs + unit tests updated.
• TypeScript projects must set "type": "module" in package.json. Projects on tsx/cjs without it will hit ERR_REQUIRE_CYCLE_MODULE until they add it (the error message says so). The require value itself is auto-migrated.

Verification

• New regression test: a test does import { config } from "codeceptjs" and asserts config.get('name') equals the running config — proves the second-copy bug is gone.
• TS tsx/esm + "type":"module" fixture loads end-to-end with all four hooks firing.
• ~190 existing tests green across run / gherkin / within / dry-run / rerun / workers (incl. pool mode) / container / config / pageobject / interface / retry / etc. — no regressions.

Alternative to #5636 that keeps the abstraction (no realm.js / globalThis singletons).

🤖 Generated with Claude Code

[DavertMik]

@mirao can you check this implementation?
can it be taken instead?

this solves the root cause of the issue (with some breaking changes)

[mirao]

I see. You replaced tsx/cjs by tsx/esm.

In my production CodeceptJS 4.x project now I have setup both tsx/cjs (because of CodeceptJS 4.x) and tsx/esm (because of imports, e.g. "dayjs/plugin/utc" etc. to be working in CodeceptJS 4.x)
Not sure how things such as codeceptjs-dbhelper (thiagodp/codeceptjs-dbhelper#16) will work with your changes, but it might be independent.

I can test it with a beta version if you release it. With the beta I could remove the patch I did because of the internal API issues locally and test the beta without them.

[DavertMik]

@mirao I would prefer the most simple and consistent fix here. Seems like migrating everything to ESM is the right path here. Instead of maintaining 2 loader types better to stick to one.

Sure. I will release beta with this one!

I think such a big change should load as 4.1.0 not less

Here is beta version to test:

https://github.com/codeceptjs/CodeceptJS/releases/tag/4.1.0-beta.1-esm-mocha

[mirao]

Here is beta version to test:
https://github.com/codeceptjs/CodeceptJS/releases/tag/4.1.0-beta.1-esm-mocha

OK. In my production projects where I tested it, I needed to add "type": "module" to package.json and removed "tsx/cjs" from a CodeceptJS config (and kept only "tsx/esm").

The beta works for me and solves the issues #5632 and #5635 . The original issue #5641 is solved as well. Note that still DataTable() fails, see #5641 (comment). It's an issue that doesn't depend on CJS/ESM. I fixed it by a patch in my project.

I run all my productions tests (web + mobile, all in TypeScript). They all pass and no more issue found (when comparing with 4.0.x).

So from my point of view, the version 4.1 works well (or at least it's not worse than 4.0 😄 )