From ecee1559834894594d305e9cf113032c4b571e15 Mon Sep 17 00:00:00 2001
From: Jan W <jan.we@exodus.io>
Date: Tue, 17 Dec 2024 11:27:33 +0100
Subject: [PATCH] docs: clarify mocking differences to jest

---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index c5f9117..a9f85ae 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,35 @@ Just use `"test": "exodus-test"`
 
 - `--test-force-exit` -- force exit after tests are done (useful in integration tests where it could be unfeasible to resolve all open handles)
 
+## Jest compatibility
+
+The `--jest` mode is mostly compatible with Jest. There are some noteworthy differences though.
+This tool does not hoist mocks, so it is important that a mock is defined before the module that uses it is imported.
+In ESM, this can be achieved with dynamic imports:
+
+```js
+jest.mock('./hogwarts.js', () => {
+  return {
+    __esModule: true,
+    default: jest.fn(),
+  }
+})
+
+const { default: getEntryQualification } = await import('./hogwarts.js')
+const { qualifiesForHogwarts } = await import('./wizard.js') // module importing ./hogwarts.js
+
+test('qualifies for Hogwarts', () => {
+  // doSomething is a mock function
+  getEntryQualification.mockReturnValue(['lumos'])
+
+  expect(qualifiesForHogwarts('potter')).toBe(false)
+  getEntryQualification.mockReturnValue([])
+  expect(qualifiesForHogwarts('potter')).toBe(true)
+})
+```
+
+Note that all modules that transitively import `hogwarts.js` will have to be imported after the mock is defined.
+
 ## License
 
 [MIT](./LICENSE)