cli: esm support

[davidjgoss]

Motivation

#1304

Support ESM usage with minimal additional flags/configuration and without dropping support for Node 10.

Details

To allow importing cucumber functions from ESM support code, provide a "wrapper" mjs entry point for ESM projects as described in https://nodejs.org/api/packages.html#packages_approach_1_use_an_es_module_wrapper.

Usage:

cucumber-js --esm

The --esm flag causes us to use import() instead of require() for loading support code - the former works for both ESM and commonjs, where the latter only works for commonjs. When we drop Node 10 support, we'll be able to deprecate/remove the flag and just use import() across the board.

I think we need to consider usage of this in conjunction with on-the-fly transpilers as out of scope for now. For example ts-node is at a very experimental phase with ESM per TypeStrong/ts-node#1007.

Test project: https://github.com/davidjgoss/cucumber-esm-example

Todo

• Use import() or require() appropriately at runtime for support code
• Handle importing cucumber.js configuration file
• Handle importing custom formatters
• Handle importing snippets
• Handle parallel runtime
• Include .mjs files by default if using ESM
• Test usage with ESM in CI
• Resolve Windows issues
• Documentation

[coveralls]

Coverage decreased (-0.08%) to 98.494% when pulling 38febb5 on esm-maybe into 1109951 on master.

[davidjgoss]

@charlierudolph some work to do still but would be good to get your take on this.

We're dealing with this on two fronts:

• An alternative executable cucumber-es runs cucumber with an override that loads support code via dynamic imports
• A wrapper entry point for ESM so that support code can natively import cucumber functions

[charlierudolph]

Cool. I think approach makes sense to me.

To check my understanding we need a second binary as we need node to load things differently?

I would prefer if we could have a --esm flag on our main binary that then just calls to second binary so our users don't need to know about the second binary (thought not certain if that runs into issues)

[davidjgoss]

@charlierudolph

I would prefer if we could have a --esm flag on our main binary

Done - was able to make this work by keeping an importer abstraction off the TypeScript compilation path, works nicely.

The last part was Windows, where trying to await import() absolute file paths has issues - see nodejs/node#31710, followed the pattern there using pathToFileURL where we'll be dealing with an absolute file path.

[charlierudolph]

Is ESM purely additive (ie require is still supported)?

If not, would seem like using this requires custom formatters used would also need to be written in ESM

[davidjgoss]

ESM is additive. If enabled, it'll use import() to load all user code (steps/hooks, formatters, snippets, and config file). If any of this user code is CommonJS and has require()s in it, that will still work fine - you can import() CommonJS modules, but you can't require() ES modules.

Eventually (after dropping Node 12 support, I think) we'll be able to just always use import() and not need the flag.

(Hope I've understood the question right!)

[davidjgoss]

And I've pushed some documentation improvements to this effect.

[charlierudolph]

Looks good. Thanks!

[charlierudolph]

Thoughts on putting this in src and as part of building copy it into lib? Same for wrappers.mjs.

[davidjgoss]

Good point - done!

[charlierudolph]

Just the last comment about the location of a couple files. Otherwise looks great! Thanks for doing this!