List formatters in help command (#1798)

* feature/list-formatters-in-help-command adding documentation field to Formatter class

* feature/list-formatters-in-help-command refactoring getConstructorByType method to hold a Record<string, typeof Formatter>

* feature/list-formatters-in-help-command improving return statement to deal with cases where the default formatter should be returned

* feature/list-formatters-in-help-command after running lint fix

* feature/list-formatters-in-help-command fixing ternary so logic does not invoke load customFormatter

* feature/list-formatters-in-help-command creating class that will hold the description of the formatters

* feature/list-formatters-in-help-command adding logic to extract the correct documentation for each formatter and altering the IFormatter type to have this field

* feature/list-formatters-in-help-command reverting changes made by adding the documentation field to the formatter object

* feature/list-formatters-in-help-command adding documentation field to html formatter

* feature/list-formatters-in-help-command adding documentation member to json/message/progress/rerun/summary/usage formatters

* feature/list-formatters-in-help-command removing formatterDocumentationHelper class as it is no longer needed

* feature/list-formatters-in-help-command adding documentation field to rerun formatter

* feature/list-formatters-in-help-command fixing return type of getConstructorByType method and running linter

* feature/list-formatters-in-help-command removing unnecessary await

* feature/list-formatters-in-help-command creating Formatters class to hold different formatters and extracting them from the builder class

* feature/list-formatters-in-help-command adding documentation field to progress-bar/snippets/usage-json formatters

* feature/list-formatters-in-help-command added method in formatters class to help build the documentation string

* feature/list-formatters-in-help-command used recently added method to list all available formatters

* feature/list-formatters-in-help-command adding documentation to snippets/progress-bar/usage-json formatters

* feature/list-formatters-in-help-command adding new line to format option so that formatters will appear on new line

* feature/list/formatters-in-help-command converting documentation field inside formatter to be public and static. Refactoring buildFormatterDocumentationString

* feature/list/formatters-in-help-command indenting formatters and removing extra space

* feature/list-formatters-in-help-command refactoring building the documentation string

* feature/list-formatters-in-help-command adding feature to changelog

CHANGELOG.md

@@ -33,6 +33,8 @@ Please see [CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CO
 ### Removed
 
 ### Fixed
+* When running the help command, it now shows all available formatters under the --format option. 
+  [#1798](https://github.com/cucumber/cucumber-js/pull/1798)
 
 ## [7.3.1] (2021-07-20)
 

src/cli/argv_parser.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander'
 import path from 'path'
 import { dialects } from '@cucumber/gherkin'
 import { SnippetInterface } from '../formatter/step_definition_snippet_builder/snippet_syntax'
+import Formatters from '../formatter/helpers/formatters'
 
 // Using require instead of import so compiled typescript will have the desired folder structure
 const { version } = require('../../package.json') // eslint-disable-line @typescript-eslint/no-var-requires
@@ -120,7 +121,8 @@ const ArgvParser = {
       .option('--fail-fast', 'abort the run on first failure', false)
       .option(
         '-f, --format <TYPE[:PATH]>',
-        'specify the output format, optionally supply PATH to redirect formatter output (repeatable)',
+        'specify the output format, optionally supply PATH to redirect formatter output (repeatable).  Available formats:\n' +
+          Formatters.buildFormattersDocumentationString(),
         ArgvParser.collect,
         []
       )

src/formatter/builder.ts

@@ -1,16 +1,7 @@
 import getColorFns from './get_color_fns'
 import JavascriptSnippetSyntax from './step_definition_snippet_builder/javascript_snippet_syntax'
-import JsonFormatter from './json_formatter'
-import MessageFormatter from './message_formatter'
 import path from 'path'
-import ProgressBarFormatter from './progress_bar_formatter'
-import ProgressFormatter from './progress_formatter'
-import RerunFormatter from './rerun_formatter'
-import SnippetsFormatter from './snippets_formatter'
 import StepDefinitionSnippetBuilder from './step_definition_snippet_builder'
-import SummaryFormatter from './summary_formatter'
-import UsageFormatter from './usage_formatter'
-import UsageJsonFormatter from './usage_json_formatter'
 import { ISupportCodeLibrary } from '../support_code_library_builder/types'
 import Formatter, { IFormatterCleanupFn, IFormatterLogFn } from '.'
 import { doesHaveValue, doesNotHaveValue } from '../value_checker'
@@ -19,8 +10,8 @@ import EventDataCollector from './helpers/event_data_collector'
 import { Writable as WritableStream } from 'stream'
 import { IParsedArgvFormatOptions } from '../cli/argv_parser'
 import { SnippetInterface } from './step_definition_snippet_builder/snippet_syntax'
-import HtmlFormatter from './html_formatter'
 import { pathToFileURL } from 'url'
+import Formatters from './helpers/formatters'
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const { importer } = require('../importer')
 
@@ -67,30 +58,12 @@ const FormatterBuilder = {
     type: string,
     cwd: string
   ): Promise<typeof Formatter> {
-    switch (type) {
-      case 'json':
-        return JsonFormatter
-      case 'message':
-        return MessageFormatter
-      case 'html':
-        return HtmlFormatter
-      case 'progress':
-        return ProgressFormatter
-      case 'progress-bar':
-        return ProgressBarFormatter
-      case 'rerun':
-        return RerunFormatter
-      case 'snippets':
-        return SnippetsFormatter
-      case 'summary':
-        return SummaryFormatter
-      case 'usage':
-        return UsageFormatter
-      case 'usage-json':
-        return UsageJsonFormatter
-      default:
-        return await FormatterBuilder.loadCustomFormatter(type, cwd)
-    }
+    const formatters: Record<string, typeof Formatter> =
+      Formatters.getFormatters()
+
+    return formatters[type]
+      ? formatters[type]
+      : await FormatterBuilder.loadCustomFormatter(type, cwd)
   },
 
   async getStepDefinitionSnippetBuilder({

src/formatter/helpers/formatters.ts

@@ -0,0 +1,39 @@
+import Formatter from '../.'
+import JsonFormatter from '../json_formatter'
+import MessageFormatter from '../message_formatter'
+import ProgressBarFormatter from '../progress_bar_formatter'
+import ProgressFormatter from '../progress_formatter'
+import RerunFormatter from '../rerun_formatter'
+import SnippetsFormatter from '../snippets_formatter'
+import SummaryFormatter from '../summary_formatter'
+import UsageFormatter from '../usage_formatter'
+import UsageJsonFormatter from '../usage_json_formatter'
+import HtmlFormatter from '../html_formatter'
+
+const Formatters = {
+  getFormatters(): Record<string, typeof Formatter> {
+    return {
+      json: JsonFormatter,
+      message: MessageFormatter,
+      html: HtmlFormatter,
+      progress: ProgressFormatter,
+      'progress-bar': ProgressBarFormatter,
+      rerun: RerunFormatter,
+      snippets: SnippetsFormatter,
+      summary: SummaryFormatter,
+      usage: UsageFormatter,
+      'usage-json': UsageJsonFormatter,
+    }
+  },
+  buildFormattersDocumentationString(): string {
+    let concatanatedFormattersDocumentation: string = ''
+    const formatters = this.getFormatters()
+    for (const formatterName in formatters) {
+      concatanatedFormattersDocumentation += `    ${formatterName}: ${formatters[formatterName].documentation}\n`
+    }
+
+    return concatanatedFormattersDocumentation
+  },
+}
+
+export default Formatters

src/formatter/html_formatter.ts

@@ -8,6 +8,7 @@ import { promisify } from 'util'
 
 export default class HtmlFormatter extends Formatter {
   private readonly _finished: Promise<void>
+  public static readonly documentation: string = 'Outputs HTML report'
 
   constructor(options: IFormatterOptions) {
     super(options)

src/formatter/index.ts

@@ -39,6 +39,7 @@ export default class Formatter {
   protected stream: WritableStream
   protected supportCodeLibrary: ISupportCodeLibrary
   private readonly cleanup: IFormatterCleanupFn
+  static readonly documentation: string
 
   constructor(options: IFormatterOptions) {
     this.colorFns = options.colorFns

src/formatter/json_formatter.ts

@@ -81,6 +81,9 @@ interface UriToTestCaseAttemptsMap {
 }
 
 export default class JsonFormatter extends Formatter {
+  public static readonly documentation: string =
+    'Prints the feature as JSON. The JSON format is in maintenance mode. Please consider using the message formatter with the standalone json-formatter (https://github.com/cucumber/cucumber/tree/master/json-formatter).'
+
   constructor(options: IFormatterOptions) {
     super(options)
     options.eventBroadcaster.on('envelope', (envelope: messages.Envelope) => {

src/formatter/message_formatter.ts

@@ -2,6 +2,7 @@ import Formatter, { IFormatterOptions } from '.'
 import * as messages from '@cucumber/messages'
 
 export default class MessageFormatter extends Formatter {
+  public static readonly documentation: string = 'Outputs protobuf messages'
   constructor(options: IFormatterOptions) {
     super(options)
     options.eventBroadcaster.on('envelope', (envelope: messages.Envelope) =>

src/formatter/progress_bar_formatter.ts

@@ -13,6 +13,8 @@ export default class ProgressBarFormatter extends Formatter {
   private testRunStarted: messages.TestRunStarted
   private issueCount: number
   public progressBar: ProgressBar
+  public static readonly documentation: string =
+    'Similar to the Progress Formatter, but provides a real-time updating progress bar based on the total number of steps to be executed in the test run'
 
   constructor(options: IFormatterOptions) {
     super(options)

src/formatter/progress_formatter.ts

@@ -16,6 +16,9 @@ const STATUS_CHARACTER_MAPPING: Map<messages.TestStepResultStatus, string> =
   ])
 
 export default class ProgressFormatter extends SummaryFormatter {
+  public static readonly documentation: string =
+    'Prints one character per scenario.'
+
   constructor(options: IFormatterOptions) {
     options.eventBroadcaster.on('envelope', (envelope: IEnvelope) => {
       if (doesHaveValue(envelope.testRunFinished)) {

src/formatter/rerun_formatter.ts

@@ -15,6 +15,8 @@ interface UriToLinesMap {
 
 export default class RerunFormatter extends Formatter {
   private readonly separator: string
+  public static readonly documentation: string =
+    'Prints failing files with line numbers.'
 
   constructor(options: IFormatterOptions) {
     super(options)

src/formatter/snippets_formatter.ts

@@ -5,6 +5,9 @@ import * as messages from '@cucumber/messages'
 import IEnvelope = messages.Envelope
 
 export default class SnippetsFormatter extends Formatter {
+  public static readonly documentation: string =
+    "The Snippets Formatter doesn't output anything regarding the test run; it just prints snippets to implement any undefined steps"
+
   constructor(options: IFormatterOptions) {
     super(options)
     options.eventBroadcaster.on('envelope', (envelope: IEnvelope) => {

src/formatter/summary_formatter.ts

@@ -12,6 +12,9 @@ interface ILogIssuesRequest {
 }
 
 export default class SummaryFormatter extends Formatter {
+  public static readonly documentation: string =
+    'Summary output of feature and scenarios'
+
   constructor(options: IFormatterOptions) {
     super(options)
     let testRunStartedTimestamp: messages.Timestamp

src/formatter/usage_formatter.ts

@@ -6,6 +6,9 @@ import * as messages from '@cucumber/messages'
 import IEnvelope = messages.Envelope
 
 export default class UsageFormatter extends Formatter {
+  public static readonly documentation: string =
+    'Prints where step definitions are used. The slowest step definitions (with duration) are listed first. If --dry-run is used the duration is not shown, and step definitions are sorted by filename instead.'
+
   constructor(options: IFormatterOptions) {
     super(options)
     options.eventBroadcaster.on('envelope', (envelope: IEnvelope) => {

src/formatter/usage_json_formatter.ts

@@ -5,6 +5,9 @@ import * as messages from '@cucumber/messages'
 import IEnvelope = messages.Envelope
 
 export default class UsageJsonFormatter extends Formatter {
+  public static readonly documentation: string =
+    'Does what the Usage Formatter does, but outputs JSON, which can be output to a file and then consumed by other tools.'
+
   constructor(options: IFormatterOptions) {
     super(options)
     options.eventBroadcaster.on('envelope', (envelope: IEnvelope) => {