cli: esm support (cucumber#1589)

* add mjs wrapper

* use import instead of require for support code

* support es2018 compile target

* separate cli for esm, override importer fn

* include mjs wrapper in package

* add feature for testing with esm

* for now, bail if on windows

* all same exports as cjs entry point

* pivot to single binary with flag and hack to import import

* fix feature file wording

* fix lint and test

* skip esm scenario if not node 12 or higher

* make it fail with imports in cucumber.js file

* make it work for cucumber.js file

* make it fail for a custom formatter

* avoid collision

* make importing formatters work

* make custom snippets work

* Include .mjs files by default if using ESM

* test with and without parallel

* unignore windows in esm tests

* add cli doc

* add changelog entry

* rename this

* sometimes use `pathToFileURL` as appropriate

* readd semi

* rework config builder tests

* further resimplify test

* improve doco

* include importer.js in src, copy at build time

* link to docs from changelog entry

* put wrapper.mjs in src as well

Author: davidjgoss

CHANGELOG.md

@@ -11,6 +11,8 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
 
 ### Added
 
+* Experimental support for native ES modules via the [`--esm` flag](./docs/cli.md#es-modules-experimental-nodejs-12) ([#1589](https://github.com/cucumber/cucumber-js/pull/1589))
+
 ### Changed
 
 ### Deprecated

dependency-lint.yml

@@ -43,6 +43,7 @@ requiredModules:
       - 'dist/**/*'
       - 'lib/**/*'
       - 'node_modules/**/*'
+      - 'src/importers.js'
       - 'tmp/**/*'
     root: '**/*.{js,ts}'
   stripLoaders: false

docs/cli.md

@@ -81,6 +81,22 @@ You can pass in format options with `--format-options <JSON>`. The JSON string m
 
 * Suggested use: add with profiles so you can define an object and use `JSON.stringify` instead of writing `JSON` manually.
 
+## ES Modules (experimental) (Node.js 12+)
+
+You can optionally write your support code (steps, hooks, etc) with native ES modules syntax - i.e. using `import` and `export` statements without transpiling.
+
+To enable this, run with the `--esm` flag.
+
+This will also expand the default glob for support files to include the `.mjs` file extension.
+
+As well as support code, these things can also be in ES modules syntax:
+
+- Custom formatters
+- Custom snippets
+- Your `cucumber.js` config file
+
+You can use ES modules selectively/incrementally - the module loading strategy that the `--esm` flag activates supports both ES modules and CommonJS.
+
 ## Colors
 
 Colors can be disabled with `--format-options '{"colorsEnabled": false}'`

features/esm.feature

@@ -0,0 +1,80 @@
+Feature: ES modules support
+
+  cucumber-js works with native ES modules, via a Cli flag `--esm`
+
+  @esm
+  Scenario Outline: native module syntax works when using --esm
+    Given a file named "features/a.feature" with:
+      """
+      Feature:
+        Scenario: one
+          Given a step passes
+
+        Scenario: two
+          Given a step passes
+      """
+    And a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      import {Given} from '@cucumber/cucumber'
+
+      Given(/^a step passes$/, function() {});
+      """
+    And a file named "cucumber.js" with:
+      """
+      export default {
+        'default': '--format message:messages.ndjson',
+      }
+      """
+    And a file named "custom-formatter.js" with:
+      """
+      import {SummaryFormatter} from '@cucumber/cucumber'
+
+      export default class CustomFormatter extends SummaryFormatter {}
+      """
+    And a file named "custom-snippet-syntax.js" with:
+      """
+      export default class CustomSnippetSyntax {
+          build(opts) {
+              return 'hello world'
+          }
+      }
+      """
+    When I run cucumber-js with `<options> --format ./custom-formatter.js --format-options '{"snippetSyntax": "./custom-snippet-syntax.js"}'`
+    Then it passes
+    Examples:
+      | options            |
+      | --esm              |
+      | --esm --parallel 2 |
+
+  @esm
+  Scenario: .mjs support code files are matched by default when using --esm
+    Given a file named "features/a.feature" with:
+      """
+      Feature:
+        Scenario:
+          Given a step passes
+      """
+    And a file named "features/step_definitions/cucumber_steps.mjs" with:
+      """
+      import {Given} from '@cucumber/cucumber'
+
+      Given(/^a step passes$/, function() {});
+      """
+    When I run cucumber-js with `--esm`
+    Then it passes
+
+  Scenario: native module syntax doesn't work without --esm
+    Given a file named "features/a.feature" with:
+      """
+      Feature:
+        Scenario:
+          Given a step passes
+      """
+    And a file named "features/step_definitions/cucumber_steps.js" with:
+      """
+      import {Given} from '@cucumber/cucumber'
+
+      Given(/^a step passes$/, function() {});
+      """
+    When I run cucumber-js
+    Then it fails

features/support/hooks.ts

@@ -13,7 +13,7 @@ Before('@debug', function (this: World) {
   this.debug = true
 })
 
-Before('@spawn', function (this: World) {
+Before('@spawn or @esm', function (this: World) {
   this.spawn = true
 })
 
@@ -43,6 +43,18 @@ Before(function (
   this.localExecutablePath = path.join(projectPath, 'bin', 'cucumber-js')
 })
 
+Before('@esm', function (this: World) {
+  const [majorVersion] = process.versions.node.split('.')
+  if (Number(majorVersion) < 12) {
+    return 'skipped'
+  }
+  fsExtra.writeJSONSync(path.join(this.tmpDir, 'package.json'), {
+    name: 'feature-test-pickle',
+    type: 'module',
+  })
+  return undefined
+})
+
 Before('@global-install', function (this: World) {
   const tmpObject = tmp.dirSync({ unsafeCleanup: true })
 

package.json

@@ -163,6 +163,10 @@
     "lib": "./lib"
   },
   "main": "./lib/index.js",
+  "exports": {
+    "import": "./lib/wrapper.mjs",
+    "require": "./lib/index.js"
+  },
   "types": "./lib/index.d.ts",
   "engines": {
     "node": ">=10"
@@ -182,7 +186,6 @@
     "cli-table3": "^0.6.0",
     "colors": "^1.4.0",
     "commander": "^7.0.0",
-    "create-require": "^1.1.1",
     "duration": "^0.2.2",
     "durations": "^3.4.2",
     "figures": "^3.2.0",
@@ -257,7 +260,7 @@
     "typescript": "4.2.3"
   },
   "scripts": {
-    "build-local": "tsc -p tsconfig.node.json",
+    "build-local": "tsc -p tsconfig.node.json && cp src/importers.js lib/ && cp src/wrapper.mjs lib/",
     "cck-test": "mocha 'compatibility/**/*_spec.ts'",
     "feature-test": "node ./bin/cucumber-js",
     "html-formatter": "node ./bin/cucumber-js --profile htmlFormatter",

src/cli/argv_parser.ts

@@ -22,6 +22,7 @@ export interface IParsedArgvFormatOptions {
 export interface IParsedArgvOptions {
   backtrace: boolean
   dryRun: boolean
+  esm: boolean
   exit: boolean
   failFast: boolean
   format: string[]
@@ -112,6 +113,7 @@ const ArgvParser = {
         'invoke formatters without executing steps',
         false
       )
+      .option('--esm', 'import support code via ES module imports', false)
       .option(
         '--exit',
         'force shutdown of the event loop when the test run has finished: cucumber will call process.exit',

src/cli/configuration_builder.ts

@@ -19,6 +19,7 @@ export interface IConfigurationFormat {
 }
 
 export interface IConfiguration {
+  esm: boolean
   featureDefaultLanguage: string
   featurePaths: string[]
   formats: IConfigurationFormat[]
@@ -80,10 +81,11 @@ export default class ConfigurationBuilder {
       }
       supportCodePaths = await this.expandPaths(
         unexpandedSupportCodePaths,
-        '.js'
+        this.options.esm ? '.@(js|mjs)' : '.js'
       )
     }
     return {
+      esm: this.options.esm,
       featureDefaultLanguage: this.options.language,
       featurePaths,
       formats: this.getFormats(),

src/cli/configuration_builder_spec.ts

@@ -29,6 +29,7 @@ describe('Configuration', () => {
 
       // Assert
       expect(result).to.eql({
+        esm: false,
         featureDefaultLanguage: 'en',
         featurePaths: [],
         formatOptions: {},
@@ -65,27 +66,79 @@ describe('Configuration', () => {
   })
 
   describe('path to a feature', () => {
-    it('returns the appropriate feature and support code paths', async function () {
-      // Arrange
-      const cwd = await buildTestWorkingDirectory()
-      const relativeFeaturePath = path.join('features', 'a.feature')
-      const featurePath = path.join(cwd, relativeFeaturePath)
-      await fsExtra.outputFile(featurePath, '')
-      const supportCodePath = path.join(cwd, 'features', 'a.js')
-      await fsExtra.outputFile(supportCodePath, '')
-      const argv = baseArgv.concat([relativeFeaturePath])
+    describe('without esm', () => {
+      it('returns the appropriate feature and support code paths', async function () {
+        // Arrange
+        const cwd = await buildTestWorkingDirectory()
+        const relativeFeaturePath = path.join('features', 'a.feature')
+        const featurePath = path.join(cwd, relativeFeaturePath)
+        await fsExtra.outputFile(featurePath, '')
+        const supportCodePath = path.join(cwd, 'features', 'a.js')
+        await fsExtra.outputFile(supportCodePath, '')
+        const argv = baseArgv.concat([relativeFeaturePath])
+
+        // Act
+        const {
+          featurePaths,
+          pickleFilterOptions,
+          supportCodePaths,
+        } = await ConfigurationBuilder.build({ argv, cwd })
+
+        // Assert
+        expect(featurePaths).to.eql([featurePath])
+        expect(pickleFilterOptions.featurePaths).to.eql([relativeFeaturePath])
+        expect(supportCodePaths).to.eql([supportCodePath])
+      })
+    })
 
-      // Act
-      const {
-        featurePaths,
-        pickleFilterOptions,
-        supportCodePaths,
-      } = await ConfigurationBuilder.build({ argv, cwd })
+    describe('with esm and js support files', () => {
+      it('returns the appropriate feature and support code paths', async function () {
+        // Arrange
+        const cwd = await buildTestWorkingDirectory()
+        const relativeFeaturePath = path.join('features', 'a.feature')
+        const featurePath = path.join(cwd, relativeFeaturePath)
+        await fsExtra.outputFile(featurePath, '')
+        const supportCodePath = path.join(cwd, 'features', 'a.js')
+        await fsExtra.outputFile(supportCodePath, '')
+        const argv = baseArgv.concat([relativeFeaturePath, '--esm'])
+
+        // Act
+        const {
+          featurePaths,
+          pickleFilterOptions,
+          supportCodePaths,
+        } = await ConfigurationBuilder.build({ argv, cwd })
+
+        // Assert
+        expect(featurePaths).to.eql([featurePath])
+        expect(pickleFilterOptions.featurePaths).to.eql([relativeFeaturePath])
+        expect(supportCodePaths).to.eql([supportCodePath])
+      })
+    })
 
-      // Assert
-      expect(featurePaths).to.eql([featurePath])
-      expect(pickleFilterOptions.featurePaths).to.eql([relativeFeaturePath])
-      expect(supportCodePaths).to.eql([supportCodePath])
+    describe('with esm and mjs support files', () => {
+      it('returns the appropriate feature and support code paths', async function () {
+        // Arrange
+        const cwd = await buildTestWorkingDirectory()
+        const relativeFeaturePath = path.join('features', 'a.feature')
+        const featurePath = path.join(cwd, relativeFeaturePath)
+        await fsExtra.outputFile(featurePath, '')
+        const supportCodePath = path.join(cwd, 'features', 'a.mjs')
+        await fsExtra.outputFile(supportCodePath, '')
+        const argv = baseArgv.concat([relativeFeaturePath, '--esm'])
+
+        // Act
+        const {
+          featurePaths,
+          pickleFilterOptions,
+          supportCodePaths,
+        } = await ConfigurationBuilder.build({ argv, cwd })
+
+        // Assert
+        expect(featurePaths).to.eql([featurePath])
+        expect(pickleFilterOptions.featurePaths).to.eql([relativeFeaturePath])
+        expect(supportCodePaths).to.eql([supportCodePath])
+      })
     })
   })
 

src/cli/helpers.ts

@@ -16,6 +16,9 @@ import TestCaseHookDefinition from '../models/test_case_hook_definition'
 import TestRunHookDefinition from '../models/test_run_hook_definition'
 import { builtinParameterTypes } from '../support_code_library_builder'
 
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const importers = require('../importers')
+
 const StepDefinitionPatternType =
   messages.StepDefinition.StepDefinitionPattern.StepDefinitionPatternType
 
@@ -29,8 +32,11 @@ export async function getExpandedArgv({
   cwd,
 }: IGetExpandedArgvRequest): Promise<string[]> {
   const { options } = ArgvParser.parse(argv)
+  const importer = options.esm ? importers.esm : importers.legacy
   let fullArgv = argv
-  const profileArgv = await new ProfileLoader(cwd).getArgv(options.profile)
+  const profileArgv = await new ProfileLoader(cwd, importer).getArgv(
+    options.profile
+  )
   if (profileArgv.length > 0) {
     fullArgv = _.concat(argv.slice(0, 2), profileArgv, argv.slice(2))
   }