📝 Docs: Mention top level ESM errors get swallowed and do not fail the suite in certain Node.js versions

[samuelhnrq]

Bug Report Checklist

• I have read and agree to Mocha's Code of Conduct and Contributing Guidelines
• I have searched for related issues and issues with the faq label, but none matched my issue.
• I have 'smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, my usage of Mocha, or Mocha itself.
• I want to provide a PR to resolve this

Expected

ESM errors thrown at top level gets silently swallowed (hidden) and does not fail the suite (as I assume is expected). Mocha ignores the error and keeps going. Makes it really annoying to debug whats wrong. Any it tests defined before the error do get "registered" normally though.

Actual

Nothing, simply ignores the error and keeps going

Minimal, Reproducible Example

given a test test/add.test.ts suite like this

import assert from 'node:assert/strict'

throw new Error()

it('should add stuff', () => {
    const b = 1 + 1;
    assert.equal(2, b)
})

Then mocha --extension ts will simply output

(node:64751) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)


  0 passing (0ms)

instead of exposing the error.

Versions

Mocha 11.7.1
Node v24.3.0

Additional Info

Conversely if you change it to

import assert from 'node:assert/strict'

it('should add stuff', () => {
    const b = 1 + 1;
    assert.equal(2, b)
})

throw new Error()

it will then output

Running main test suite...
(node:64877) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)


  ✔ should add stuff

  1 passing (1ms)

Still no mention of the error.

[JoshuaKGoldberg]

Confirmed, this is an unfortunate bug. Mocha should definitely report the error instead of swallowing it. Thanks for the report!

[samuelhnrq]

I might be interested on working on this. Gave it a 10 minutes look and already got confused by a meta-question:

AFAIK / guess this bug is due to some incompatibility with the built-in ESM + type stripping present in (non-experimental) what, node 24? Way higher then mocha's minimum, what's the policy to deal with cases like this? Does mocha have a per-node version test suite kind of thing?

EDIT: Did test on node 18 and cannot reproduce, top level CJS JS errors fail the suite normally 😕, trying to transpile it would be pointless because its invisible to mocha, the actual executed code would just have a top level CJS throw which I just tested works :/

EDIT 2: Maybe I'm overthinking this and I could just write a normal spec with if (nodeversion() < 24) return on top, , if so then it becomes more of a question of what is the test runner's version/setup

If the answer to this question is already somewhere please point me in the right direction 😅 (E.g. documentation, good past PR...)

[samuelhnrq]

Two developments:

Firstly, Its also reproductible on node 22 which would make testing much easier, my aforementioned if (nodeversion() < 22) return at the top of the test suite should suffice I reckon

I Found the root cause. 🕵️

Node.js new built-in, enabled by default --no-experimental-require-module flag (HERE) seems to have a subtle bug where if you try to require() an ESM file with a top level error, the require call does throw with the top level error as expected but the interop code seems to somehow taint the module cache, because if you later try to await import() the same "bad" ESM module node.js itself swallows the error and the subsequent import call does not throw

It therefore causes this bug because mocha's ESM fallback code (here) always ignores the first require() error assuming that if the error was non-ESM related the same errors would be thrown again (e.g. if you try to await import the same file), turns out that's not the case.

Possible next steps

1. This error has a simple workaround, adding --no-experimental-require-module fixes the problem (while we merge a real fix)
2. Should even mocha do anything about this? This behaviour seems very fishy from node maybe we just file a issue there
3. Since this is affecting users right now we could simply update the documentation to mention the workaround?
4. I do could try to change the fallback code to be more defensive and make sure the exceptions it swallows and falls back to ESM are actually ESM related (e.g. syntax error)

Not sure what would be the best course of action here.

[JoshuaKGoldberg]

Great investigation! 🕵

This behaviour seems very fishy from node maybe we just file a issue there

Oof, filing an issue upstream does sound reasonable to me. If the error swallowing and cache population are intentional then it'd be good to know why.

change the fallback code to be more defensive ... are actually ESM related

That sounds promising, but is also somewhat risky. We've seen a lot of churn recently from trying to implement similar error heuristics. My hunch is we should wait to hear back from Node.js folks on whether all this is intentional, and whether there's a recommended workaround.

cc @legendecas - sorry to keep bringing you more work 😅, but this seems like something you might know things about if you have time?

[samuelhnrq]

Quick status update, upstream confirmed its indeed a bug, so I think code changes on our end should be pointless, should we add a disclaimer to the docs (with the --no-experimental-require-module workaround) ? Apparently all versions from node 22 ~ 24 seems to be affected...

[JoshuaKGoldberg]

Good question. Let's see what the resolution on the Node.js side is. We might be able to learn from it / adapt our behavior there. Thanks for filing the issue & pushing this forward!