docs: ESM update #13191

iamWing · 2022-08-30T06:19:34Z

Summary

As discussed in #13135, this PR:

documented that there's no hoisting on jest.mock with ESM support activated and added example of putting the mock calls before import statements to properly load the import modules.
updated Using with ES module imports in ManulMocks.md to point out the hoisting mentioned there does not applied when ESM support is activated with link to ECMAScriptModules.md.

Additionally, I've updated the Node version number mentioned in ECMAScriptModules.md to reflect the fact that vm.Module is still considered experimental in 18.8.0.

@mrazauskas I've found that already a link to #10025 in ECMAScriptModules.md, do you want to add some documentations for jest.unstable_mock there as well or you think it's fine just leave it like this for now?

Test plan

No test plan. Only docs are updated.

- Added link to `ECMAScriptModules` in section `Using with ES module imports`.

- To reflect the most updated status.

- Replace hard coded link to `ECMAScriptModules` documentation in `ManualMocks.md` with a relative link to `ECMAScriptModules.md`.

mrazauskas

Thanks!

Yes, it would be very useful to have jest.unstable_mock() documented as well. If a paragraph on jest.mock() is added, then someone trying to mock ESM module might be not happy (;

docs/ECMAScriptModules.md

mrazauskas · 2022-08-30T06:44:44Z

By the way, jest.unstable_mock() shipped with Jest 27.1.1. See #9430 (comment). It should be documented only in docs of v27 and up.

iamWing · 2022-08-30T07:25:25Z

Thanks!

Yes, it would be very useful to have jest.unstable_mock() documented as well. If a paragraph on jest.mock() is added, then someone trying to mock ESM module might be not happy (;

Okay. One question tho, am I right that jest.mock doesn't work for ESM but CJS modules with ESM support activated? So jest.unstable_mock is meant to mock the ESM?

mrazauskas · 2022-08-31T04:00:03Z

Oh.. Sorry there was a typo. The method is called jest.unstable_mockModule(). It mocks only ESModules, hence the Module at the end of the name.

Your example with electron is very good. It shows how mock CJS module from in an ESM test. I think next to it there must be an example how to mock ESM module in an ESM test. Something similar to #10025 (comment)

docs/ManualMocks.md

- Also clarified that the limitation comes from ESM, not Jest.

iamWing · 2022-08-31T17:16:21Z

@mrazauskas I've added a fairly simple example for unstable_mockModule at the bottom of ECMAScriptModules.md. I think that should be enough for now? Maybe we can also put it in JestObjectAPI.md but not sure if you guys want it there as well. I'm assuming it's going to be deprecated soon after jest.mock is able to support ESM`.

Javidmj

Good

docs/ECMAScriptModules.md

SimenB · 2022-09-01T08:14:17Z

docs/ECMAScriptModules.md

@@ -38,4 +38,51 @@ import.meta.jest.useFakeTimers();
 // jest === import.meta.jest => true
 ```

+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.


why do we talk about "dynamic import()", and then go on to use require?

I've made the change to also mention require there, with the example now showing both require and dynamic import() usage. Personally I prefer require for CJS modules but I think it's better to show both on the docs so the users aren't going to think that either is more preferable.

docs/ECMAScriptModules.md

mrazauskas · 2022-09-02T13:29:18Z

Thanks for your patience and collaboration. This is shaping up nicely!

- Diabled `no-redeclare`.

- Chagned to the suggested version.

iamWing · 2022-09-02T13:46:35Z

Thanks for your patience and collaboration. This is shaping up nicely!

Yeah we're getting close to finalise it.

I do think this doc is much needed for people migrating to ESM syntax. In fact, a fellow developer using my Electron boilerplate with ESM enabled got confused with this recently. There should be a lot less confusion for the users once we have the updated doc goes live.

mrazauskas · 2022-09-02T13:50:39Z

docs/ECMAScriptModules.md

@@ -38,4 +38,57 @@ import.meta.jest.useFakeTimers();
 // jest === import.meta.jest => true
 ```

-Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use `require` or dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.


Last idea from my side:

Suggested change

Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use `require` or dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.

## Module mocking in ESM

Since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use `require` or dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.

How about we have this title added on v27+ only? We can only mock CJS modules before v27 even with ESM support enabled right? Plus I've noticed that the ECMAScript Modules page doesn't show up on v25's sidebar. Is that list a generated one or we have to update the sidebars.json manually?

Right, it makes sense only with v27+. I will take a look at the sidebars later. Can it be there was no ESM support in v25? No sure.

Looked around quickly. Seems like first steps with ESM support were released in v25. So you are right here too, that link is missing in the sidebar and must be added. Thanks!

- Added section title `MOdule mocking in ESM` on `v27+` only.

SimenB

this is looking great! just some minor nits

docs/ECMAScriptModules.md

docs/ManualMocks.md

SimenB · 2022-09-03T12:59:33Z

thanks!

github-actions · 2022-10-04T00:14:34Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

iamWing added 4 commits August 29, 2022 17:40

Add jest.mock ESM example

27ea279

Update ManualMocks doc for ESM

658b12a

- Added link to `ECMAScriptModules` in section `Using with ES module imports`.

Update Node version for experimental ESM support

3a8816d

- To reflect the most updated status.

Fix link

4fdcbb2

- Replace hard coded link to `ECMAScriptModules` documentation in `ManualMocks.md` with a relative link to `ECMAScriptModules.md`.

facebook-github-bot added the cla signed label Aug 30, 2022

mrazauskas reviewed Aug 30, 2022

View reviewed changes

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

Update modified docs for format suggested

7e562df

mrazauskas reviewed Aug 31, 2022

View reviewed changes

docs/ManualMocks.md Outdated Show resolved Hide resolved

Fix caution section in ManualMocks

e21e657

- Also clarified that the limitation comes from ESM, not Jest.

iamWing changed the title ~~Docs/esm update~~ docs: ESM update Aug 31, 2022

iamWing added 2 commits August 31, 2022 16:26

Prefer require for CJS module imports

6945cfc

Document jest.unstable_mockModule

3d06b0a

Javidmj reviewed Sep 1, 2022

View reviewed changes

SimenB requested changes Sep 1, 2022

View reviewed changes

SimenB reviewed Sep 1, 2022

View reviewed changes

docs/ECMAScriptModules.md Show resolved Hide resolved

Reorder examples

87f81ba

mrazauskas reviewed Sep 2, 2022

View reviewed changes

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

mrazauskas reviewed Sep 2, 2022

View reviewed changes

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

iamWing added 2 commits September 2, 2022 14:31

Override ESLint rule for docs

7c58f12

- Diabled `no-redeclare`.

Improve unstable_mockModule doc

a0f9271

- Chagned to the suggested version.

mrazauskas reviewed Sep 2, 2022

View reviewed changes

iamWing added 2 commits September 2, 2022 16:04

Add doc section in ECMAScriptModules

3c0755f

- Added section title `MOdule mocking in ESM` on `v27+` only.

Fix v25 sidebar

d8f155e

SimenB approved these changes Sep 3, 2022

View reviewed changes

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

docs/ECMAScriptModules.md Outdated Show resolved Hide resolved

docs/ManualMocks.md Outdated Show resolved Hide resolved

Refine wordings

f6ed55e

SimenB merged commit 0cfc2ad into jestjs:main Sep 3, 2022

github-actions bot locked as resolved and limited conversation to collaborators Oct 4, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: ESM update #13191

docs: ESM update #13191

iamWing commented Aug 30, 2022

mrazauskas left a comment

mrazauskas commented Aug 30, 2022

iamWing commented Aug 30, 2022

mrazauskas commented Aug 31, 2022

iamWing commented Aug 31, 2022

Javidmj left a comment

SimenB Sep 1, 2022 •

edited

Loading

iamWing Sep 2, 2022

mrazauskas commented Sep 2, 2022

iamWing commented Sep 2, 2022

mrazauskas Sep 2, 2022

iamWing Sep 2, 2022

mrazauskas Sep 2, 2022

mrazauskas Sep 2, 2022

SimenB left a comment

SimenB commented Sep 3, 2022

github-actions bot commented Oct 4, 2022

-Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use `require` or dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+## Module mocking in ESM
+Since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use `require` or dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.

docs: ESM update #13191

docs: ESM update #13191

Conversation

iamWing commented Aug 30, 2022

Summary

Test plan

mrazauskas left a comment

Choose a reason for hiding this comment

mrazauskas commented Aug 30, 2022

iamWing commented Aug 30, 2022

mrazauskas commented Aug 31, 2022

iamWing commented Aug 31, 2022

Javidmj left a comment

Choose a reason for hiding this comment

SimenB Sep 1, 2022 • edited Loading

Choose a reason for hiding this comment

iamWing Sep 2, 2022

Choose a reason for hiding this comment

mrazauskas commented Sep 2, 2022

iamWing commented Sep 2, 2022

mrazauskas Sep 2, 2022

Choose a reason for hiding this comment

iamWing Sep 2, 2022

Choose a reason for hiding this comment

mrazauskas Sep 2, 2022

Choose a reason for hiding this comment

mrazauskas Sep 2, 2022

Choose a reason for hiding this comment

SimenB left a comment

Choose a reason for hiding this comment

SimenB commented Sep 3, 2022

github-actions bot commented Oct 4, 2022

SimenB Sep 1, 2022 •

edited

Loading