config: support configuration as objects

CHANGELOG.md

@@ -17,6 +17,7 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
   See [./docs/cli.md#printing-attachments-details](https://github.com/cucumber/cucumber-js/blob/main/docs/cli.md#printing-attachments-details) for more info.
   ([#1136](https://github.com/cucumber/cucumber-js/issues/1136)
   [#1721](https://github.com/cucumber/cucumber-js/pull/1721))
+- Support for configuration to be objects instead of argv strings, and for configuration files in ESM and JSON formats ([#1952](https://github.com/cucumber/cucumber-js/pull/1952))
 
 ### Fixed
 - Warn users who are on an unsupported node version ([#1922](https://github.com/cucumber/cucumber-js/pull/1922))

README.md

@@ -47,6 +47,7 @@ If you learn best by example, we have [a repo with several example projects](htt
 The following documentation is for `main`, which might contain some unreleased features. See below the documentation for older versions.
 
 * [CLI](/docs/cli.md)
+* [Configuration](/docs/configuration.md)
 * Support Files
   * [World](/docs/support_files/world.md)
   * [Step Definitions](/docs/support_files/step_definitions.md)
@@ -56,14 +57,17 @@ The following documentation is for `main`, which might contain some unreleased f
   * [Attachments](/docs/support_files/attachments.md)
   * [API Reference](/docs/support_files/api_reference.md)
 * Guides
-  * [Dry Run](./docs/dry_run.md)
+  * [Dry run](./docs/dry_run.md)
   * [ES Modules](./docs/esm.md)
+  * [Failing fast](./docs/fail_fast.md)
+  * [Filtering](./docs/filtering.md)
   * [Formatters](./docs/formatters.md)
   * [Running in parallel](./docs/parallel.md)
   * [Profiles](./docs/profiles.md)
   * [Rerunning just failures](./docs/rerun.md)
   * [Retrying flaky scenarios](./docs/retry.md)
   * [Snippets for undefined steps](./docs/snippets.md)
+  * [Transpiling (from TypeScript etc)](./docs/transpiling.md)
 * [FAQ](/docs/faq.md)
 
 ### Documentation for older versions

compatibility/cck_spec.ts

@@ -9,8 +9,7 @@ import { ignorableKeys } from '../features/support/formatter_output_helpers'
 import * as messages from '@cucumber/messages'
 import * as messageStreams from '@cucumber/message-streams'
 import util from 'util'
-import { runCucumber } from '../src/api'
-import { IRunConfiguration } from '../src/configuration'
+import { runCucumber, IRunnableConfiguration } from '../src/api'
 import { Envelope } from '@cucumber/messages'
 
 const asyncPipeline = util.promisify(pipeline)
@@ -30,9 +29,13 @@ describe('Cucumber Compatibility Kit', () => {
       const actualMessages: Envelope[] = []
       const stdout = new PassThrough()
       const stderr = new PassThrough()
-      const runConfiguration: IRunConfiguration = {
+      const runConfiguration: IRunnableConfiguration = {
         sources: {
+          defaultDialect: 'en',
           paths: [`${CCK_FEATURES_PATH}/${suiteName}/${suiteName}${extension}`],
+          names: [],
+          tagExpression: '',
+          order: 'defined',
         },
         support: {
           requireModules: ['ts-node/register'],
@@ -42,7 +45,20 @@ describe('Cucumber Compatibility Kit', () => {
           importPaths: [],
         },
         runtime: {
+          dryRun: false,
+          failFast: false,
+          filterStacktraces: true,
+          parallel: 0,
           retry: suiteName === 'retry' ? 2 : 0,
+          retryTagFilter: '',
+          strict: true,
+          worldParameters: {},
+        },
+        formats: {
+          stdout: 'summary',
+          files: {},
+          options: {},
+          publish: false,
         },
       }
       await runCucumber(

cucumber.json

@@ -0,0 +1,20 @@
+{
+  "default": {
+    "requireModule": [
+      "ts-node/register"
+    ],
+    "require": [
+      "features/**/*.ts"
+    ],
+    "format": [
+      "progress-bar",
+      "rerun:@rerun.txt",
+      "usage:reports/usage.txt",
+      "message:reports/messages.ndjson",
+      "html:reports/html-formatter.html"
+    ],
+    "retry": 2,
+    "retryTagFilter": "@flaky",
+    "publishQuiet": true
+  }
+}

docs/cli.md

@@ -1,178 +1,59 @@
 # CLI
 
-Cucumber.js includes an executable file to run the features. After installing Cucumber in your project, you can run it with:
+Cucumber includes an executable file to run your scenarios. After installing the `@cucumber/cucumber` package, you can run it directly:
 
 ``` shell
 $ ./node_modules/.bin/cucumber-js
 ```
 
-**Note on global installs:** Cucumber does not work when installed globally because cucumber
-needs to be required in your support files and globally installed modules cannot be required.
-
-## Running specific features
-
-* Specify a [glob](https://github.com/isaacs/node-glob) pattern
-  * `$ cucumber-js features/**/*.feature`
-* Specify a feature directory
-  * `$ cucumber-js features/dir`
-* Specify a feature file
-  * `$ cucumber-js features/my_feature.feature`
-* Specify a scenario by its line number
-  * `$ cucumber-js features/my_feature.feature:3`
-* Specify a scenario by its name matching a regular expression
-  * `$ cucumber-js --name "topic 1"`
-  * `$ cucumber-js --name "^start.+end$"`
-  * If used multiple times, the scenario name needs to match only one of the names supplied
-  * To escape special regex characters in scenario name, use backslash e.g., `\(Scenario Name\)`
-* Use [Tags](#tags)
-
-## Loading support files
-
-By default, the following files are loaded:
-* If the features live in a `features` directory (at any level)
-  * `features/**/*.(js|mjs)`
-* Otherwise
-  * `<DIR>/**/*.(js|mjs)` for each directory containing the selected features
+Or via a [`package.json` script](https://docs.npmjs.com/cli/v8/using-npm/scripts):
 
-With the defaults described above, `.js` files are loaded via `require()`, whereas `.mjs` files are loaded via `import()`.
-
-Alternatively, you can use either or both of these options to explicitly load support files before executing the features:
+```json
+{
+  "scripts": {
+    "cucumber": "cucumber-js"
+  }
+}
+```
 
-- `--require <GLOB|DIR|FILE>` - loads via `require()` (legacy)
-- `--import <GLOB|DIR|FILE>` - loads via `import()`
+Or via [npx](https://docs.npmjs.com/cli/v8/commands/npx):
 
-Both options use [glob](https://github.com/isaacs/node-glob) patterns and may be used multiple times in order to e.g. load files from several different locations.
+``` shell
+$ npx cucumber-js
+```
 
-_Note that once you specify any `--require` or `--import` options, the defaults described above are no longer applied._
+**Note on global installs:** Cucumber does not work when installed globally because `@cucumber/cucumber`
+needs to be required in your support files and globally installed modules cannot be required.
 
-## Formats
+## Options
 
-Use `--format <TYPE[:PATH]>` to specify the format of the output.
+All the [standard configuration options](./configuration.md#options) can be provided via the CLI.
 
-See [Formatters](./formatters.md).
+Additionally, there are a few options that are specific to the CLI:
 
-### Officially-supported standalone formatters
+| Option             | Type       | Repeatable | Description                                                                             |
+|--------------------|------------|------------|-----------------------------------------------------------------------------------------|
+| `--config`, `-c`   | `string`   | No         | Path to your configuration file - see [Files](./configuration.md#files)                 |
+| `--profile`, `-p`  | `string[]` | Yes        | Profiles from which to include configuration - see [Profiles](./profiles.md)            |
+| `--version`, `-v`  | `boolean`  | No         | Print the currently installed version of Cucumber, then exit immediately                |
+| `--i18n-keywords`  | `string`   | No         | Print the Gherkin keywords for the given ISO-639-1 language code, then exit immediately |
+| `--i18n-languages` | `boolean`  | No         | Print the supported languages for Gherkin, then exit immediately                        |
 
-* [@cucumber/pretty-formatter](https://www.npmjs.com/package/@cucumber/pretty-formatter) - prints the feature with inline results,  colours and custom themes.
+To see the available options for your installed version, run:
 
-### Format Options
+```shell
+$ cucumber-js --help
+```
 
-You can pass in format options with `--format-options <JSON>`.
+## Exiting
 
-See [Formatters](./formatters.md).
+By default, cucumber exits when the event loop drains. Use the `exit` configuration option in order to force shutdown of the event loop when the test run has finished:
 
-## Exiting
+- In a configuration file `{ exit: true }`
+- On the CLI `$ cucumber-js --exit`
 
-By default, cucumber exits when the event loop drains. Use the `--exit` flag in order to force shutdown of the event loop when the test run has finished. This is discouraged, as fixing the issues that causes the hang is a better long term solution. Some potential resources for that are:
+This is discouraged, as fixing the issues that causes the hang is a better long term solution. Some potential resources for that are:
 * [Node.js guide to debugging](https://nodejs.org/en/docs/inspector/)
 * NPM package [why-is-node-running](https://www.npmjs.com/package/why-is-node-running)
 * [Node.js Async Hooks](https://nodejs.org/dist/latest-v8.x/docs/api/async_hooks.html)
 * Isolating what scenario or scenarios causes the hang
-
-## --no-strict
-
-disable _strict_ mode.
-
-By default, cucumber works in _strict_ mode, meaning it will fail if there are pending steps.
-
-## Parallel
-
-See [Parallel](./parallel.md).
-
-## Printing Attachments Details
-
-Printing attachments details can be disabled with
-`--fomat-options '{"printAttachments": false}'`.
-
-This option applies to the progress formatter and the summary formatter.
-
-## Profiles
-
-See [Profiles](./profiles.md).
-
-## Tags
-
-Use `--tags <EXPRESSION>` to run specific features or scenarios. This option is repeatable and the expressions will be merged with an `and` operator.
-`<EXPRESSION>` is a [cucumber tag expression](https://docs.cucumber.io/cucumber/api/#tag-expressions).
-
-## --fail-fast
-
-abort the run on first failure (default: false)
-
-By default, cucumber-js runs the entire suite and reports all the failures. This flag allows a developer workflow where you work on one failure at a time. Combining this feature with rerun files allows you to work through all failures in an efficient manner.
-
-A note on using in conjunction with `--retry`: we consider a test case to have failed if it exhausts retries and still fails, but passed if it passes on a retry having failed previous attempts, so `--fail-fast` does still allow retries to happen.
-
-## Retry failing tests
-
-See [Retry](./retry.md)
-
-## Transpilation
-
-Step definitions and support files can be written in other languages that transpile to JavaScript.
-
-### Simple ES6 support
-
-For instance, for ES6 support with [Babel](https://babeljs.io/) 7 add:
-
-```
---require-module @babel/register
-```
-
-This will effectively call `require('@babel/register')` prior to requiring any support files.
-
-If your files end with an extension other than `js`, make sure to also include the `--require` option to state the required support files. For example, if using [CoffeeScript](https://www.npmjs.com/package/coffeescript):
-
-```
---require-module coffeescript/register --require 'features/**/*.coffee'
-```
-
-### TypeScript
-
-Your `tsconfig.json` should have the `resolveJsonModule` compiler option switched on. Other than that, a pretty standard TypeScript setup should work as expected.
-
-#### With ts-node
-
-If you are using [ts-node](https://github.com/TypeStrong/ts-node):
-
-```
---require-module ts-node/register --require 'step-definitions/**/*.ts'
-```
-
-> ⚠️ Some TypeScript setups use `esnext` modules by default,
->   which doesn't marry well with Node. You may consider using commonjs instead.
->   See how to add [extra configuration](#extra-configuration) below.
-
-#### With babel
-
-If you are using babel with [@babel/preset-typescript](https://babeljs.io/docs/en/babel-preset-typescript):
-
-```
---require-module @babel/register --require 'step-definitions/**/*.ts'
-```
-
-### Extra Configuration
-
-Sometimes the required module (say `@ts-node/register`) needs extra configuration. For example, you might want to configure it such that it prevents the compiled JS being written out to files, and pass some compiler options. In such cases, create a script (say, `tests.setup.js`):
-
-```js
-require('ts-node').register({
-  transpileOnly: true,
-  compilerOptions: {
-    "module": "commonjs",
-    "resolveJsonModule": true,
-  },
-});
-```
-
-And then require it using the `--require` option:
-
-```
---require tests.setup.js --require 'features/**/*.ts'
-```
-
-Note that the first `--require tests.setup.js` overrides the default require glob, so we'll need to `--require` our support code explicitly too.
-
-## World Parameters
-
-See [World](./support_files/world.md).