better formats config

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 Please see [CONTRIBUTING.md](./CONTRIBUTING.md) on how to contribute to Cucumber.
 
 ## [Unreleased]
+### Added
+- Support array notation of formats with path in configuration files ([#2318](https://github.com/cucumber/cucumber-js/pull/2318))
 
 ## [9.4.0] - 2023-08-12
 ### Fixed

cucumber.json

@@ -4,11 +4,11 @@
     "require": ["features/**/*.ts"],
     "format": [
       "progress-bar",
-      "rerun:@rerun.txt",
-      "usage:reports/usage.txt",
-      "message:reports/messages.ndjson",
-      "junit:reports/junit.xml",
-      "html:reports/html-formatter.html"
+      ["rerun", "@rerun.txt"],
+      ["usage", "reports/usage.txt"],
+      ["message", "reports/messages.ndjson"],
+      ["junit", "reports/junit.xml"],
+      ["html", "reports/html-formatter.html"]
     ],
     "retry": 2,
     "retryTagFilter": "@flaky"

docs/formatters.md

@@ -6,22 +6,19 @@ cucumber-js provides many built-in Formatters, plus building blocks with which y
 
 You can specify one or more formats via the `format` configuration option:
 
-- In a configuration file `{ format: ['<TYPE[:PATH]>'] }`
-- On the CLI `$ cucumber-js --format <TYPE[:PATH]>`
+- In a configuration file `{ format: ['progress-bar', ['html', 'cucumber-report.html']] }`
+- On the CLI `$ cucumber-js --format progress-bar --format html:cucumber-report.html`
 
-For each value you provide, `TYPE` should be one of:
+For each format you specify, you have to provide one or two values. The first (required) is to identify the formatter. It can take a few forms:
 
-* The name of one of the built-in formatters (below) e.g. `progress`
+* The name of one of the built-in formatters (below) e.g. `progress-bar`
 * A module/package name e.g. `@cucumber/pretty-formatter`
 * A relative path to a local formatter implementation e.g. `./my-customer-formatter.js`
 * An absolute path to a local formatter implementation in the form of a `file://` URL
 
-If `PATH` is supplied, the formatter prints to the given file, otherwise it prints to `stdout`. If the path includes directories that do not yet exist they will be created.
+Without a second value, the formatter will print to `stdout`. The second value, if present, is a path to where the formatter output should be written. If the path includes directories that do not yet exist, they will be created.
 
-For example, this configuration would give you a progress bar as you run, plus JSON and HTML report files:
-
-- In a configuration file `{ format: ['progress-bar', 'json:cucumber-report.json', 'html:cucumber-report.html'] }`
-- On the CLI `$ cucumber-js --format progress-bar --format json:cucumber-report.json --format html:cucumber-report.html`
+On the CLI, when specifying both a name and path, you'll need to use `:` as a delimiter. In a configuration file you can do this too, but you can also provide an array with the two values as separate strings, which is recommended. 
 
 Some notes on specifying Formatters:
 

package.json

@@ -246,7 +246,7 @@
     "verror": "^1.10.0",
     "xmlbuilder": "^15.1.1",
     "yaml": "^2.2.2",
-    "yup": "^0.32.11"
+    "yup": "1.2.0"
   },
   "devDependencies": {
     "@cucumber/compatibility-kit": "^12.0.0",

src/api/convert_configuration.ts

@@ -42,7 +42,7 @@ function convertFormats(
   env: NodeJS.ProcessEnv
 ) {
   const splitFormats: string[][] = flatConfiguration.format.map((item) =>
-    OptionSplitter.split(item)
+    Array.isArray(item) ? item : OptionSplitter.split(item)
   )
   return {
     stdout:

src/api/convert_configuration_spec.ts

@@ -39,15 +39,15 @@ describe('convertConfiguration', () => {
     })
   })
 
-  it('should map multiple formatters', async () => {
+  it('should map multiple formatters with string and array notations', async () => {
     const result = await convertConfiguration(
       {
         ...DEFAULT_CONFIGURATION,
         format: [
           'summary',
           'message',
           'json:./report.json',
-          'html:./report.html',
+          ['html', './report.html'],
         ],
       },
       {}

src/configuration/check_schema.ts

@@ -7,7 +7,15 @@ const schema = yup.object().shape({
   dryRun: yup.boolean(),
   exit: yup.boolean(),
   failFast: yup.boolean(),
-  format: yup.array().of(yup.string()),
+  format: yup
+    .array()
+    .of(
+      yup.lazy((val) =>
+        Array.isArray(val)
+          ? yup.array().of(yup.string()).min(2).max(2)
+          : yup.string()
+      )
+    ),
   formatOptions: yup.object(),
   import: yup.array().of(yup.string()),
   language: yup.string().oneOf(Object.keys(dialects)),

src/configuration/types.ts

@@ -1,12 +1,14 @@
 import { FormatOptions } from '../formatter'
 import { PickleOrder } from '../models/pickle_order'
 
+type FormatsConfiguration = Array<string | [string, string]>
+
 export interface IConfiguration {
   backtrace: boolean
   dryRun: boolean
   forceExit: boolean
   failFast: boolean
-  format: string[]
+  format: FormatsConfiguration
   formatOptions: FormatOptions
   import: string[]
   language: string