Include pretty formatter with package (#2592)

Author: davidjgoss

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
+- Include updated pretty formatter ([#2592](https://github.com/cucumber/cucumber-js/pull/2592))
 
 ## [12.0.0] - 2025-07-13
 ### Added

dependency-lint.yml

@@ -23,6 +23,7 @@ ignoreErrors:
   unused:
     - '@cucumber/compatibility-kit' # files dynamically loaded in cck test, not required
     - '@cucumber/junit-xml-formatter' # formatter dynamically imported at runtime
+    - '@cucumber/pretty-formatter' # formatter dynamically imported at runtime
     - '@eslint/compat' # used by eslint
     - '@eslint/eslintrc' # used by eslint
     - '@eslint/js' # used by eslint

docs/formatters.md

@@ -34,11 +34,16 @@ Many formatters, including the built-in ones, support some configuration via opt
 
 This option is repeatable, so you can use it multiple times and the objects will be merged with the later ones taking precedence.
 
-Some options offered by built-in formatters:
+Some common options supported by built-in formatters:
 
 - `colorsEnabled` - [see below](#colored-output)
 - `printAttachments` - if set to `false`, attachments won't be part of progress bars and summary reports
 
+Some formatters have options that are only applicable to them. These options will be under a key that matches the formatter name, like this:
+
+- In a configuration file `{ formatOptions: { pretty: { featuresAndRules : false } }`
+- On the CLI `cucumber-js --format-options '{"pretty":{"featuresAndRules":false}}'`
+
 ## Colored output
 
 Many formatters, including the built-in ones, emit some colored output. By default, Cucumber will automatically detect the colors support of the output stream and decide whether to emit colors accordingly. This check comes via the [supports-colors](https://github.com/chalk/supports-color) library and is pretty comprehensive, including awareness of commonly-used  operating systems and CI platforms that represent edge cases.
@@ -75,7 +80,19 @@ Similar to the Progress Formatter, but provides a real-time updating progress ba
 
 ![](./images/progress_bar_green.gif)
 
-*Note: the Progress Bar Formatter will only work with a TTY terminal (and not, for example, a file stream).*
+### `pretty`
+
+ℹ️ Added in v12.1.0  
+ℹ️ Can be installed and referenced as `@cucumber/pretty-formatter` from v11.1.0
+
+Writes a rich report of the scenario and example execution as it happens.
+
+![](./images/pretty.png)
+
+Options specific to this formatter (under the `pretty` key):
+
+- `featuresAndRules` - whether to include headings for Features and Rules (defaults to `true`)
+- `theme` - control over the styling of various elements (see [documentation](https://github.com/cucumber/pretty-formatter/blob/main/javascript/README.md#themes))
 
 ### `html`
 
@@ -120,7 +137,7 @@ Outputs details of the test run in the legacy JSON format.
 
 The JUnit formatter produces an XML-based report in the standard(ish) [JUnit format](https://github.com/junit-team/junit5/blob/43638eb6a870e0d6c49224053dfeb39dcf0ef33f/platform-tests/src/test/resources/jenkins-junit.xsd). This is most commonly useful for having your CI platform pick up your tests results and factor them into its reporting. Consult your CI platform's docs for where exactly you should output this report to and what the filename should be.
 
-Options specific to this formatter:
+Options specific to this formatter (under the `junit` key):
 
 - `suiteName` - value to go in the `name` attribute of the `testsuite` element in the output (defaults to `cucumber-js`)
 

docs/images/pretty.png

@@ -258,6 +258,7 @@
   },
   "devDependencies": {
     "@cucumber/compatibility-kit": "18.0.3",
+    "@cucumber/pretty-formatter": "^2.0.0",
     "@cucumber/query": "13.5.0",
     "@eslint/compat": "^1.3.0",
     "@eslint/eslintrc": "^3.3.1",
@@ -294,7 +295,7 @@
     "eslint": "^9.29.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-n": "^17.20.0",
-    "eslint-plugin-unicorn": "^59.0.1",
+    "eslint-plugin-unicorn": "^57.0.0",
     "express": "^5.0.0",
     "fs-extra": "10.1.0",
     "genversion": "3.2.0",

package-lock.json

@@ -74,6 +74,7 @@ export async function initializeFormatters({
       await pluginManager.initFormatter(
         implementation,
         configuration.options,
+        stream,
         stream.write.bind(stream),
         directory
       )

package.json

@@ -14,6 +14,7 @@ const builtin = {
   // new plugin-based formatters
   html: htmlFormatter,
   junit: '@cucumber/junit-xml-formatter',
+  pretty: '@cucumber/pretty-formatter',
   message: messageFormatter,
   // legacy class-based formatters
   json: JsonFormatter,
@@ -32,6 +33,8 @@ export const documentation = {
   // new plugin-based formatters
   html: 'Outputs a HTML report',
   junit: 'Produces a JUnit XML report',
+  pretty:
+    'Writes a rich report of the scenario and example execution as it happens',
   message: 'Emits Cucumber messages in newline-delimited JSON',
   // legacy class-based formatters
   json: JsonFormatter.documentation,

src/api/formatters.ts

@@ -35,6 +35,7 @@ export class PluginManager {
   async initFormatter<OptionsType>(
     plugin: FormatterPlugin<OptionsType>,
     options: OptionsType,
+    stream: NodeJS.WritableStream,
     write: (buffer: string | Uint8Array) => void,
     directory?: string
   ) {
@@ -44,6 +45,7 @@ export class PluginManager {
         ? ((options as any)[plugin.optionsKey] ?? ({} as OptionsType))
         : options,
       logger: this.environment.logger,
+      stream,
       write,
       directory,
     })

src/formatter/builtin/index.ts

@@ -71,6 +71,7 @@ export interface FormatterPluginContext<OptionsType> {
   on: (key: 'message', handler: (value: Envelope) => void) => void
   options: OptionsType
   logger: ILogger
+  stream: NodeJS.WritableStream
   write: (buffer: string | Uint8Array) => void
   directory?: string
 }