Quibble ESM support

testdouble · May 1, 2020 · f430e8c · f430e8c
1 parent e83d9b7
commit f430e8c
Show file tree

Hide file tree

Showing 25 changed files with 5,647 additions and 419 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,3 @@ npm-debug.log*
 
 #ignore node_modules, as the node project is not "deployed" per se: http://www.mikealrogers.com/posts/nodemodules-in-git.html
 /node_modules
-
diff --git a/.travis.yml b/.travis.yml
@@ -1,7 +1,9 @@
 language: node_js
 node_js:
-  - 6
   - 8
   - 10
+  - 12
+  - 13
+  - 14
 before_install: npm i -g npm@6
 script: npm run test:ci
diff --git a/README.md b/README.md
@@ -66,6 +66,69 @@ after the absolute path resolved to by `'./some/path'`.
 
 Spiffy!
 
+> Note: `defaultFakeCreator` is not supported for ES Module stubbing
+
+## ES Modules support
+
+Quibble supports ES Modules. Quibble implements ES module support using [ES Module
+Loaders](https://nodejs.org/api/esm.html#esm_experimental_loaders) which are the official way to
+"patch" Node.js' module loading mechanism for ESM.
+
+> Note that Loader support is currently experimental and unstable. We will be doing our best
+  to track the changes in the specification for the upcoming Node.js versions. Also note that
+  Quibble ESM support is tested only for versions 13 and above.
+
+To use Quibble support, you must run Node with the `quibble` package as the loader:
+
+```sh
+node --loader=quibble ...
+```
+
+Most test runners allow you to specify this in their command line, e.g. for Mocha:
+
+```sh
+mocha --loader=quibble ...
+```
+
+The `quibble` loader will enable the replacement of the ES modules with the stubs you specify, and
+without it, the stubbing will be ignored.
+
+### Restrictions on ESM
+
+* Quibble currently supports stubbing only modules that are paths (e.g. `../foo/bar.mjs`). Bare
+  specificiers (e.g. `lodash`) are not yet supported.
+* `defaultFakeCreator` is not yet supported.
+
+### `quibble` ESM API
+
+The API is similar to the CommonJS API, and uses the same `quibble` function:
+
+```js
+// a-module.mjs (ESM)
+export const life = 42;
+export default 'universe';
+
+// uses-a-module.mjs
+import universe, {life} from './a-module.mjs';
+
+console.log(life, universe);
+
+(async function () {
+  quibble('./a-module.mjs', {life: 41}, 'replacement universe');
+
+  await import('./uses-some-module.mjs');
+  // ==> logs: 41, replacement universe
+})();
+```
+
+The parameters to `quibble` for ESM modules are:
+
+1. the module path: similar to CommonJS, the path is relative to the directory you are in. It is
+   resolved the ESM way, so if you're using a relative path, you must specify the filename,
+   including the extension.
+
+* `quibble.reset` works the same as for CommonJS modules
+
 ## How's it different?
 
 A few things that stand out about quibble:

diff --git a/example-esm/.gitignore b/example-esm/.gitignore
@@ -0,0 +1 @@
+/node_modules
diff --git a/example-esm/lib/animals/bear.mjs b/example-esm/lib/animals/bear.mjs
@@ -0,0 +1 @@
+export default function () { return 'a real bear' }
diff --git a/example-esm/lib/animals/lion.mjs b/example-esm/lib/animals/lion.mjs
@@ -0,0 +1 @@
+export default function () { return 'a real lion' }
diff --git a/example-esm/lib/zoo.mjs b/example-esm/lib/zoo.mjs
@@ -0,0 +1,11 @@
+import lion from './animals/lion.mjs'
+import bear from './animals/bear.mjs'
+
+export default function () {
+  return {
+    animals: [
+      lion(),
+      bear()
+    ]
+  }
+}