unhelpful error messages while using asynch in before()

[jric]

Prerequisites

• Checked that your issue hasn't already been filed by cross-referencing issues with the faq label
• Checked next-gen ES issues and syntax problems by using the same environment and/or transpiler configuration without Mocha to ensure it isn't just a feature that actually isn't supported in the environment in question or a bug in your code.
• 'Smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, your usage of Mocha, or Mocha itself
• Ensured that there is no discrepancy between the locally and globally installed versions of Mocha. You can find them with: node_modules/.bin/mocha --version(Local) and mocha --version(Global). We recommend that you not install Mocha globally.

Description

Being a noob with ESM, I did not realize that I could not simply follow the documentation at the top of https://mochajs.org/. After following the "prerequisites" steps for filing a ticket, I found my error and eventually found https://mochajs.org/#nodejs-native-esm-support. However, I believe I had some unneeded frustration. The error message I got was:

SyntaxError[ @/Users/jric/dev/socialvoter/src/server/js/test/test.js ]: Unexpected reserved word
    at Loader.moduleStrategy (node:internal/modules/esm/translators:146:18)
    at async link (node:internal/modules/esm/module_job:67:21)

for which I found very little actionable information, mostly in this ticket: nodejs/node#49441

Steps to Reproduce

create package.json with "type"="module"

create this test file, and run it with mocha

var assert = require('assert');
function myAsyncFunction() { return new Promise(() => {}, () => {}); }
describe('Server', function() {
    before(function() {
        await myAsyncFunction();
    });
});

Expected behavior:

I expect to see an error, such as I get when I remove the "await" from the test code above.

ReferenceError: require is not defined in ES module scope, you can use import instead

As another simple fix, I expect to see a qualification at the top of the documentation that specifies that the sample code is only for using the common module system, and it could link down to the alternate code for using ESM.

Actual behavior:
As mentioned above, I dutifully follow the sample code and get a very cryptic error.

Reproduces how often: 100%

Versions

• The output of mocha --version and node_modules/.bin/mocha --version:

jric@Alexs-MacBook-Pro-3 js % mocha --version
zsh: command not found: mocha
jric@Alexs-MacBook-Pro-3 js % node_modules/.bin/mocha --version
9.2.1

• The output of node --version:

jric@Alexs-MacBook-Pro-3 js % node --version
v16.6.1

• Your operating system
  • name and version:
    macOS Monterey 12.2.1
  • architecture (32 or 64-bit):
    64 bit
• Your shell (e.g., bash, zsh, PowerShell, cmd):
  zsh
• Your browser and version (if running browser tests): N/A
• Any third-party Mocha-related modules (and their versions): N/A
• Any code transpiler (e.g., TypeScript, CoffeeScript, Babel) being used (and its version): N/A

Additional Information

N/A

[juergba]

@jric I understand Being a noob with ESM can be frustrating sometimes, but I don't think we are going to pursue this issue. We don't have the bandwith to cover basic javascript or Node features tutorial-like in our docs.

You have two mistakes in your test sample:

• async/await: await can be used only within an async function, this is plain javascript (except top-level awaits in ESM). IMO removing await is not the correct solution, better to add async to the before callback. This issue probably triggers your SyntaxError.
• esm: require instead of import, a basic Node feature.

SyntaxError[ @/Users/jric/dev/socialvoter/src/server/js/test/test.js ]: Unexpected reserved word

I agree this error message is suboptimal, it's a known Node issue. We already tried to improve the information, see #4557, it's a hack until Node has fixed the issue permanently.

[jric]

I certainly am not suggesting an ESM tutorial in the mocha docs, but I appreciate that I may ask too much, @juergba. At least the next unsuspecting soul may find this ticket in a keyword search and save themselves some time.

ESM is recommended by some popular projects and usage will increase over time. I think this confusion is likely to happen with increasing frequency before it gets resolved by the Node community.

Thank you for considering my proposal and guiding me away from ESM for now.

[juergba]

[...] guiding me away from ESM for now.

Mocha has been supporting Node's native ESM since 2020-02-26, with very few issues reported.
But well, it's your decision. Closing.