fix(mocha-runner): clear error when require esm (#3015)

Provide a clear error message when users configure `mochaOptions.require` to include `"esm"`. You should provide it as a node argument instead.

```diff
{
  "$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
  "testRunner": "mocha",
  "mochaOptions": {
-   "require": ["esm"]
  },
+ "testRunnerNodeArgs": ["--require", "esm"]
}
```

Fixes #3014

docs/mocha-runner.md

@@ -104,6 +104,8 @@ Default: `[]`
 
 Set mocha's [`require` option](https://mochajs.org/#-r---require-module-name)
 
+_Note:_ if you want to require [`esm`](https://www.npmjs.com/package/esm), you will need to use `"testRunnerNodeArgs": ["--require", "esm"]` instead. See [#3014](https://github.com/stryker-mutator/stryker-js/issues/3014) for more information.
+
 ### `mochaOptions.async-only` [`boolean`]
 
 Default: `false`

packages/mocha-runner/src/mocha-test-runner.ts

@@ -51,6 +51,11 @@ export class MochaTestRunner implements TestRunner {
     this.mochaOptions = this.loader.load(this.options as MochaRunnerWithStrykerOptions);
     this.testFileNames = this.mochaAdapter.collectFiles(this.mochaOptions);
     if (this.mochaOptions.require) {
+      if (this.mochaOptions.require.includes('esm')) {
+        throw new Error(
+          'Config option "mochaOptions.require" does not support "esm", please use `"testRunnerNodeArgs": ["--require", "esm"]` instead. See https://github.com/stryker-mutator/stryker-js/issues/3014 for more information.'
+        );
+      }
       this.rootHooks = await this.mochaAdapter.handleRequires(this.mochaOptions.require);
     }
   }

packages/mocha-runner/test/unit/mocha-test-runner.spec.ts

@@ -92,6 +92,14 @@ describe(MochaTestRunner.name, () => {
 
       expect(sut.rootHooks).eq(expectedRootHooks);
     });
+
+    it('should reject when requires contains "esm" (see #3014)', async () => {
+      const requires = ['esm', 'ts-node/require'];
+      mochaOptionsLoaderMock.load.returns(createMochaOptions({ require: requires }));
+      await expect(sut.init()).rejectedWith(
+        'Config option "mochaOptions.require" does not support "esm", please use `"testRunnerNodeArgs": ["--require", "esm"]` instead. See https://github.com/stryker-mutator/stryker-js/issues/3014 for more information.'
+      );
+    });
   });
 
   describe(MochaTestRunner.prototype.dryRun.name, () => {