Preserve import order for ESM

[znewsham]

Summary

Ensure Jest behaves the same was as Node when loading ESM modules - by linking and evaluating up the import tree - rather than fully linking and evaluating asynchronously.

I'm aware this is likely a divisive, opinionated change - I'd be totally fine with this behaviour being hidden behind a flag. If this has already been suggested and rejected - I apologies, I did look for similar issues/PRs but found none.

In many projects (including some of those I'm involved with) the code depends on load order, which undeniably it shouldn't. However it isn't always trivial to clean up these implicit depenencies - particularly where globals are involved, defined in third party packages. When running this project in node, imports are fully evaluated before their siblings are loaded - unless top level await is used.

However, when running jest - imports are linked and evaluated in parallel - while this is completely correct ESM behaviour, it massively differs from node's behaviour, making jest hard to use in many large, legacy projects with complex dependency trees (any of which may fall victim to this).

A potential repro would be:

// file1.js
import './emptyFile.js'
globalThis.whatever = "Hello";

// file2.js
console.log(globalThis.whatever);

// file3.js
import "./file1.js";
import "./file2.js";

In node, this will output Hello - in jest, it will output undefined - because file2 evaluates before file1 does. Note - I've not tested this case specifically, where I observed it was more complex - but the concept is the same.

Test plan

I've tested this on a complex project - if necessary I can throw together a repro. Without this change, jest will log undefined with the change it will log Hello

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: znewsham / name: Zack (61d49d6, 05c1a93, 7337080, 2ee1bf7, 4e5fba3, 1713139, f079261, 10a9009, cd817fb, c8d5ceb, b602925, d70ff0d, be8978d, b3c7883, 4cfcf6f, bc6deab)

[netlify]

✅ Deploy Preview for jestjs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	b3c7883
🔍 Latest deploy log	https://app.netlify.com/sites/jestjs/deploys/663105b0216c0f0007d4689b
😎 Deploy Preview	https://deploy-preview-15031--jestjs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[SimenB]

Huh, I didn't know Node did that 😅

This should be behind a flag, yes 👍 It also needs integration tests

[SimenB]

oops, wrong button 😅

(also changelog entry)

[znewsham]

@SimenB Thanks for the response, it turns out this is a bit more nuanced than I thought - though the cause and the solution I believe are the same, I was only able to repro this by mixing ESM and CJS. I ended up using almost the exact repro that my project had (albeit simpler) I'm confident there are other situations it would appear in too.

It ended up being more complicated than I thought to add the preserveLoadOrder flag - please let me know if I've done it totally wrong

[znewsham]

@SimenB tests passing and changelog provided - it was fairly cumbersome adding the new option (the same change required in lots of files) please let me know if I got it wrong

[G-Rath]

it was fairly cumbersome adding the new option

Yeah I was caught out by that in #15016 - I do wonder if it might be worth trying to colocate some of the changes or have a template-ish doc outlining the different places that should be changed.

fwiwi it looks like you've just missed updating jest-config/src/Descriptions.ts which should have a description of your new config option; that'll also result in needing to update a create-jest snapshot. There is also jest/cli/src/args.ts but from what I understand of this change it doesn't seem like something that would make much sense to be arg-based i.e. it feels like something you'd either want to configure as always on or always off.

[SimenB]

thanks for adding tests!

Could you update the docs as well? Add the new option to https://jestjs.io/docs/configuration

[znewsham]

@SimenB tests actually passing now 🤣 and I believe I updated the documentation too (though wasn't sure exactly which file relates to the website)

[znewsham]

@SimenB don't review this yet - just found that when you have circular dependencies jest now hangs because of this change - looking into it