EDIT: quick guide for getting started:https://jestjs.io/docs/ecmascript-modules

ESM support will be unflagged in a future release of Node 12 (maybe not before Aprilnodejs/node#29866 (comment)) and it is already unflagged in Node 13.2, so I think it's time to evaluate how we can add native support in Jest. I'll try to list which features Jest currently provides that are impacted by ESM support, and how we can solve/investigate them.

There is issue#4842, but I think that's more of a discussion issue, while this issue will be geared towards actually implementing support and more suitable to track for those who just want to get the current implementation status. Any comments added to this issuenot related to how we can implement support for the below enumerated features will be marked as spam - please direct any workarounds/discussions to separate issues. Also feel free to tell us if anything related to ESM features is missing from the list!

Please note that Jest will use thevm API (https://nodejs.org/api/vm.html) and as of writing (nodev13.6 v16.10) the ESM parts of this API is still flagged (--experimental-vm-modules). So saying ESM is unflagged is a bit of a misnomer at the moment. But I think we should start experimenting and potentially provide feedback to theModules WG.

EDIT: Tracking issue for stabilization in Node:nodejs/node#37648

Lastly, I'm writing this issue mostly for people who will implement support, so it'll be somewhat low-level and specific to how Jest works. For people whojust want to know whether support has landed or not, I recommend using GH's wonderful "custom notification" and only subscribe to notifications on closing/reopening.

• Running the module in the correct context

We achieve sandboxes by running a script within a givenvm.Context (either provided by JSDOM or node core APIs). We need to do the same for ESM, but we'll need access to thecontext during construction of the module, not just when executing the module. I've opened up#9428 which adds the necessary APIs toJestEnvironment.

• Globals

expect,test,beforeEach etc will still be added as globals, nothing should change here.jasmine global will also still be here.

• jest "global" property

This is not really a global - it's injected into the module scope. Since the module scope is gone in ESM, we need to move it somewhere. Adding it toimport.meta seems natural - there's an option calledinitializeImportMeta which we can use.

EDIT: Solution here is to fetch it viaimport {jest} from '@jest/globals'. We might still add it viaimport.meta in the future, but this should be enough for now.

• jest.(do|un)mock

Since ESM has different "stages" when evaluating a module,jest.mock will not work for static imports. It can work for dynamic imports though, so I think we just have to be clear in the docs about what it supports and what it doesn't.

jest.mock calls are hoisted, but that doesn't help in ESM. We might consider transformingimport 'thing' toimport('thing') which should allow hoisting to work, but then it's async. Using top-levelawait is probably a necessity for such an approach. I also think it's invasive enough to warrant a separate option. Something to discuss - we don't need to support everythingjest.mock can for for an initial release.

PR:#10976

• jest.requireActual

Not sure if how it should behave in ESM. Should we provide ajest.importActual and letrequireActual evaluate inCJS always?

• import.meta

Node hasurl as its only property (for now, at least). We need to make sure it's populated in Jest as well. We provideidentifier instead offilename when constructing the module so I don't think it'll happen automatically, buturl is essentiallyfilename passed thoughpathToFileURL.

There's also an open PR forimport.meta.resolve:nodejs/node#31032

• import thing from 'thing'

This should actually be fairly straightforward, we just need to implement alinker where we can also transform the source before returning it, meaning we don't need the loader API (which doesn't exist yet). This allows us to return mocks as well (albeit they'll have to come from a__mocks__ directory).

• import('thing')

Essentially the same as above, but passed asimportModuleDynamically when constructing the module. Will also supportjest.mock,jest.resetModules etc more cleanly, so likely to be used quite a bit.

This can also be done forvm.Script via the same option.

• Handling errors during evaluation

Right now it's a runtime error (e.g. module not found), but that's not necessarily true with ESM. Does it matter for us? We should verify errors still look nice.

• module.createRequire

We need to deal with this for people wanting to use CJS from ESM. I've opened up#9426 to track this separately as implementing it is not really related to ESM support.

EDIT: Implemented in#9469

• module.syncBuiltinESMExports

https://nodejs.org/api/modules.html#modules_module_syncbuiltinesmexports. Do we care about it, or is just making it a no-op enough? Not sure what the use case in Jest would be. Messing with the builtins is already breaking the sandbox and I don't think this should matter.

EDIT:#9469 made this into a no-op. I think that's fine?

• Detect if a file is supposed to be ESM or CJS mode

Inspectingtype field in a module'spackage.json seems reasonable:https://nodejs.org/api/esm.html#esm_enabling. Should we also have our own config flag? Also needs to respect file endings.

nodejs/node#49446

• moduleNameMapper

Not sure if this impacts anything. Ithink not since we'll be linking the modules together ourselves. Needs investigation, though.

EDIT: This is all resolution logic, which we control. So no changes here.

• jest.config.mjs

Through#9291 we supportjest.config.cjs - do we need to do anything special for.mjs? Probably useimport('path/to/configFile.mjs') which means it'll have to be async. Is this an issue? Might be worth making config resolutionasync in Jest 25 so it's not a blocker for incremental support of ESM in Jest 25.

EDIT:#9431

• Package Exports

Node supportspackage exports, which sorta maps to Jest'smoduleNameMapper, but also provides encapsulation features. Hopefullyresolve will implement this, but if they do not we'll need to do something. Might be enough to use thepathFilter option? Unsure.

EDIT:#9771

• JSON/WASM module

https://nodejs.org/api/esm.html#esm_experimental_json_modules. Do we need to care? Probably, especially forjson. It's trivial for us to supportimport thing from './package.json' since we control the linking phase, but we probably shouldn't do it by default as it'll differ from default node. Should we force people to define a transform for it?

WASM:#13505

• Code coverage

Does it matter? I don't think it's affected as we can still transform the source with babel (maybe it'll be confused byimport statements, probably not) and V8 coverage definitely shouldn't care. We should verify though.

• Async code resolution

This is absolutely no blocker as sync resolution will work just fine. But wecan use async resolution now, which is great. I wonder if we should look into just using theresolve module off of npm again, as it already supports async. See#9505.

• Async code transformation

Similar to above, not blocking, but would be nice to support it. Might make@jest/transformer more usable in other environments as well. See#9504.

EDIT:#9889 &#11191

• Bad performance when accessing globals

Due to#5163 we have theextraGlobals option as a workaround - that workaround is no longer viable in ESM. I've opened up and issue with node here:nodejs/node#31658

• Import assertions

https://nodejs.org/api/esm.html#import-assertions