☕️ Classic, reliable, trusted test framework for Node.js and the browser
Support --require of ESM; closes #4281 (#4304)
JacobLey273dbbbf4c21
diff --git a/docs/index.md b/docs/index.mdindex cd2ed9c3..ad26db22 100644--- a/docs/index.md+++ b/docs/index.md@@ -1007,6 +1007,8 @@ Modules required in this manner are expected to do work synchronously; Mocha wonNote you cannot use `--require` to set a global `beforeEach()` hook, for example — use `--file` instead, which allows you to specify an explicit order in which test files are loaded.+> As of v7.3.0, Mocha supports `--require` for [NodeJS native ESM](#nodejs-native-esm-support). There is no separate `--import` flag.+### `--sort, -S`Sort test files (by absolute path) using [Array.prototype.sort][mdn-array-sort].@@ -1450,7 +1452,6 @@ Node.JS native ESM support still has status: **Stability: 1 - Experimental**- [Watch mode](#-watch-w) does not support ES Module test files- [Custom reporters](#third-party-reporters) and [custom interfaces](#interfaces)can only be CommonJS files-- [Required modules](#-require-module-r-module) can only be CommonJS files- [Configuration file](#configuring-mocha-nodejs) can only be a CommonJS file (`.mocharc.js` or `.mocharc.cjs`)- When using module-level mocks via libs like `proxyquire`, `rewiremock` or `rewire`, hold off on using ES modules for your test files- Node.JS native ESM support does not work with [esm][npm-esm] modulediff --git a/lib/cli/run-helpers.js b/lib/cli/run-helpers.jsindex e09338f2..017d914f 100644--- a/lib/cli/run-helpers.js+++ b/lib/cli/run-helpers.js@@ -15,6 +15,7 @@ const collectFiles = require('./collect-files');const {type} = require('../utils');const {format} = require('util');const {createInvalidPluginError, createUnsupportedError} = require('../errors');+const {requireOrImport} = require('../esm-utils');/*** Exits Mocha when tests + code under test has finished execution (default)@@ -81,16 +82,21 @@ exports.list = str =>* @returns {Promise<MochaRootHookObject|MochaRootHookFunction>} Any root hooks* @private*/-exports.handleRequires = async (requires = []) =>- requires.reduce((acc, mod) => {+exports.handleRequires = async (requires = []) => {+ const acc = [];+ for (const mod of requires) {let modpath = mod;// this is relative to cwdif (fs.existsSync(mod) || fs.existsSync(`${mod}.js`)) {modpath = path.resolve(mod);debug('resolved required file %s to %s', mod, modpath);}- const requiredModule = require(modpath);- if (type(requiredModule) === 'object' && requiredModule.mochaHooks) {+ const requiredModule = await requireOrImport(modpath);+ if (+ requiredModule &&+ typeof requiredModule === 'object' &&+ requiredModule.mochaHooks+ ) {const mochaHooksType = type(requiredModule.mochaHooks);if (/function$/.test(mochaHooksType) || mochaHooksType === 'object') {debug('found root hooks in required file %s', mod);@@ -102,8 +108,9 @@ exports.handleRequires = async (requires = []) =>}}debug('loaded required module "%s"', mod);- return acc;- }, []);+ }+ return acc;+};/*** Loads root hooks as exported via `mochaHooks` from required files.diff --git a/lib/esm-utils.js b/lib/esm-utils.jsindex df2b5fed..604f883d 100644--- a/lib/esm-utils.js+++ b/lib/esm-utils.js@@ -1,11 +1,16 @@-const url = require('url');const path = require('path');+const url = require('url');-const requireOrImport = async file => {- file = path.resolve(file);+const formattedImport = async file => {+ if (path.isAbsolute(file)) {+ return import(url.pathToFileURL(file));+ }+ return import(file);+};+exports.requireOrImport = async file => {if (path.extname(file) === '.mjs') {- return import(url.pathToFileURL(file));+ return formattedImport(file);}// This is currently the only known way of figuring out whether a file is CJS or ESM.// If Node.js or the community establish a better procedure for that, we can fix this code.@@ -15,7 +20,7 @@ const requireOrImport = async file => {return require(file);} catch (err) {if (err.code === 'ERR_REQUIRE_ESM') {- return import(url.pathToFileURL(file));+ return formattedImport(file);} else {throw err;}@@ -25,7 +30,7 @@ const requireOrImport = async file => {exports.loadFilesAsync = async (files, preLoadFunc, postLoadFunc) => {for (const file of files) {preLoadFunc(file);- const result = await requireOrImport(file);+ const result = await exports.requireOrImport(path.resolve(file));postLoadFunc(file, result);}};diff --git a/test/integration/fixtures/options/require/esm/package.json b/test/integration/fixtures/options/require/esm/package.jsonnew file mode 100644index 00000000..5ffd9800--- /dev/null+++ b/test/integration/fixtures/options/require/esm/package.json@@ -0,0 +1 @@+{ "type": "module" }diff --git a/test/integration/fixtures/options/require/esm/root-hook-defs-esm.fixture.js b/test/integration/fixtures/options/require/esm/root-hook-defs-esm.fixture.jsnew file mode 100644index 00000000..3e0a2f77--- /dev/null+++ b/test/integration/fixtures/options/require/esm/root-hook-defs-esm.fixture.js@@ -0,0 +1,8 @@+export const mochaHooks = () => ({+ beforeEach() {+ console.log('esm beforeEach');+ },+ afterEach() {+ console.log('esm afterEach');+ },+});diff --git a/test/integration/fixtures/options/require/root-hook-defs-esm.fixture.mjs b/test/integration/fixtures/options/require/root-hook-defs-esm.fixture.mjsnew file mode 100644index 00000000..6597d65b--- /dev/null+++ b/test/integration/fixtures/options/require/root-hook-defs-esm.fixture.mjs@@ -0,0 +1,8 @@+export const mochaHooks = {+ beforeAll() {+ console.log('mjs beforeAll');+ },+ afterAll() {+ console.log('mjs afterAll');+ },+};diff --git a/test/integration/options/require.spec.js b/test/integration/options/require.spec.jsindex ca50af86..11b869a5 100644--- a/test/integration/options/require.spec.js+++ b/test/integration/options/require.spec.js@@ -1,6 +1,7 @@'use strict';var invokeMochaAsync = require('../helpers').invokeMochaAsync;+var utils = require('../../../lib/utils');describe('--require', function() {describe('when mocha run in serial mode', function() {@@ -45,6 +46,46 @@ describe('--require', function() {/beforeAll[\s\S]+?beforeAll array 1[\s\S]+?beforeAll array 2[\s\S]+?beforeEach[\s\S]+?beforeEach array 1[\s\S]+?beforeEach array 2[\s\S]+?afterEach[\s\S]+?afterEach array 1[\s\S]+?afterEach array 2[\s\S]+?afterAll[\s\S]+?afterAll array 1[\s\S]+?afterAll array 2/);});++ describe('support ESM when style=module or .mjs extension', function() {+ before(function() {+ if (!utils.supportsEsModules()) this.skip();+ });++ it('should run root hooks when provided via mochaHooks', function() {+ return expect(+ invokeMochaAsync(+ [+ '--require=' ++ require.resolve(+ // as object+ '../fixtures/options/require/root-hook-defs-esm.fixture.mjs'+ ),+ '--require=' ++ require.resolve(+ // as function+ '../fixtures/options/require/esm/root-hook-defs-esm.fixture.js'+ ),+ '--require=' ++ require.resolve(+ // mixed with commonjs+ '../fixtures/options/require/root-hook-defs-a.fixture.js'+ ),+ require.resolve(+ '../fixtures/options/require/root-hook-test.fixture.js'+ )+ ].concat(+ +process.versions.node.split('.')[0] >= 13+ ? []+ : '--experimental-modules'+ )+ )[1],+ 'when fulfilled',+ 'to contain output',+ /mjs beforeAll[\s\S]+?beforeAll[\s\S]+?esm beforeEach[\s\S]+?beforeEach[\s\S]+?esm afterEach[\s\S]+?afterEach[\s\S]+?mjs afterAll[\s\S]+?afterAll/+ );+ });+ });});describe('when mocha in parallel mode', function() {