fix(cli): restore command line help contents (#3502)

devoto13 · web-flow · commit e99da316a2d3 · 2020-05-07T10:58:41.000-07:00
These were lost after migration to yargs as CLI parser. Fixes #3474
diff --git a/lib/cli.js b/lib/cli.js
@@ -10,16 +10,6 @@ const helper = require('./helper')
 const constant = require('./constants')
 
 function processArgs (argv, options, fs, path) {
-  if (argv.help) {
-    console.log(yargs.help())
-    process.exit(0)
-  }
-
-  if (argv.version) {
-    console.log(`Karma version: ${constant.VERSION}`)
-    process.exit(0)
-  }
-
   // TODO(vojta): warn/throw when unknown argument (probably mispelled)
   Object.getOwnPropertyNames(argv).forEach(function (name) {
     let argumentValue = argv[name]
@@ -130,6 +120,10 @@ function processArgs (argv, options, fs, path) {
 
   options.configFile = configFile ? path.resolve(configFile) : null
 
+  if (options.cmd === 'run') {
+    options.clientArgs = parseClientArgs(process.argv)
+  }
+
   return options
 }
 
@@ -151,39 +145,44 @@ function argsBeforeDoubleDash (argv) {
   return idx === -1 ? argv : argv.slice(0, idx)
 }
 
-function describeShared () {
-  yargs
+function describeRoot () {
+  return yargs
     .usage('Karma - Spectacular Test Runner for JavaScript.\n\n' +
+      'Run --help with particular command to see its description and available options.\n\n' +
       'Usage:\n' +
-      '  $0 <command>\n\n' +
-      'Commands:\n' +
-      '  start [<configFile>] [<options>] Start the server / do single run.\n' +
-      '  init [<configFile>] Initialize a config file.\n' +
-      '  run [<options>] [ -- <clientArgs>] Trigger a test run.\n' +
-      '  completion Shell completion for karma.\n\n' +
-      'Run --help with particular command to see its description and available options.')
+      '  $0 <command>')
+    .command('init', 'Initialize a config file.', describeInit)
+    .command('start', 'Start the server / do a single run.', describeStart)
+    .command('run', 'Trigger a test run.', describeRun)
+    .command('stop', 'Stop the server.', describeStop)
+    .command('completion', 'Shell completion for karma.', describeCompletion)
+    .demandCommand(1, 'Command not specified.')
+    .strictCommands()
     .describe('help', 'Print usage and options.')
     .describe('version', 'Print current version.')
 }
 
-function describeInit () {
+function describeInit (yargs) {
   yargs
     .usage('Karma - Spectacular Test Runner for JavaScript.\n\n' +
       'INIT - Initialize a config file.\n\n' +
       'Usage:\n' +
-      '  $0 init [<configFile>]')
+      '  $0 init [configFile]')
+    .strictCommands(false)
+    .version(false)
     .describe('log-level', '<disable | error | warn | info | debug> Level of logging.')
     .describe('colors', 'Use colors when reporting and printing logs.')
     .describe('no-colors', 'Do not use colors when reporting or printing logs.')
-    .describe('help', 'Print usage and options.')
 }
 
-function describeStart () {
+function describeStart (yargs) {
   yargs
     .usage('Karma - Spectacular Test Runner for JavaScript.\n\n' +
       'START - Start the server / do a single run.\n\n' +
       'Usage:\n' +
-      '  $0 start [<configFile>] [<options>]')
+      '  $0 start [configFile]')
+    .strictCommands(false)
+    .version(false)
     .describe('port', '<integer> Port where the server is running.')
     .describe('auto-watch', 'Auto watch source files and run on change.')
     .describe('detached', 'Detach the server.')
@@ -201,93 +200,57 @@ function describeStart () {
     .describe('no-fail-on-empty-test-suite', 'Do not fail on empty test suite.')
     .describe('fail-on-failing-test-suite', 'Fail on failing test suite.')
     .describe('no-fail-on-failing-test-suite', 'Do not fail on failing test suite.')
-    .describe('help', 'Print usage and options.')
 }
 
-function describeRun () {
+function describeRun (yargs) {
   yargs
     .usage('Karma - Spectacular Test Runner for JavaScript.\n\n' +
       'RUN - Run the tests (requires running server).\n\n' +
       'Usage:\n' +
-      '  $0 run [<configFile>] [<options>] [ -- <clientArgs>]')
+      '  $0 run [configFile] [-- <clientArgs>]')
+    .strictCommands(false)
+    .version(false)
     .describe('port', '<integer> Port where the server is listening.')
     .describe('no-refresh', 'Do not re-glob all the patterns.')
     .describe('fail-on-empty-test-suite', 'Fail on empty test suite.')
     .describe('no-fail-on-empty-test-suite', 'Do not fail on empty test suite.')
-    .describe('help', 'Print usage.')
     .describe('log-level', '<disable | error | warn | info | debug> Level of logging.')
     .describe('colors', 'Use colors when reporting and printing logs.')
     .describe('no-colors', 'Do not use colors when reporting or printing logs.')
 }
 
-function describeStop () {
+function describeStop (yargs) {
   yargs
     .usage('Karma - Spectacular Test Runner for JavaScript.\n\n' +
       'STOP - Stop the server (requires running server).\n\n' +
       'Usage:\n' +
-      '  $0 run [<configFile>] [<options>]')
+      '  $0 stop [configFile]')
+    .strictCommands(false)
+    .version(false)
     .describe('port', '<integer> Port where the server is listening.')
     .describe('log-level', '<disable | error | warn | info | debug> Level of logging.')
-    .describe('help', 'Print usage.')
 }
 
-function describeCompletion () {
+function describeCompletion (yargs) {
   yargs
     .usage('Karma - Spectacular Test Runner for JavaScript.\n\n' +
       'COMPLETION - Bash/ZSH completion for karma.\n\n' +
       'Installation:\n' +
-      '  $0 completion >> ~/.bashrc\n')
-    .describe('help', 'Print usage.')
+      '  $0 completion >> ~/.bashrc')
+    .strictCommands(false)
+    .version(false)
 }
 
 function printRunnerProgress (data) {
   process.stdout.write(data)
 }
 
-exports.process = function () {
-  const argv = yargs.parse(argsBeforeDoubleDash(process.argv.slice(2)))
-  const options = {
-    cmd: argv._.shift()
-  }
-
-  switch (options.cmd) {
-    case 'start':
-      describeStart()
-      break
-
-    case 'run':
-      describeRun()
-      options.clientArgs = parseClientArgs(process.argv)
-      break
-
-    case 'stop':
-      describeStop()
-      break
-
-    case 'init':
-      describeInit()
-      break
-
-    case 'completion':
-      describeCompletion()
-      break
-
-    default:
-      describeShared()
-      if (!options.cmd) {
-        processArgs(argv, options, fs, path)
-        console.error('Command not specified.')
-      } else {
-        console.error('Unknown command "' + options.cmd + '".')
-      }
-      yargs.showHelp()
-      process.exit(1)
-  }
-
-  return processArgs(argv, options, fs, path)
+exports.process = () => {
+  const argv = describeRoot().parse(argsBeforeDoubleDash(process.argv.slice(2)))
+  return processArgs(argv, { cmd: argv._.shift() }, fs, path)
 }
 
-exports.run = function () {
+exports.run = () => {
   const config = exports.process()
 
   switch (config.cmd) {
diff --git a/test/e2e/cli.feature b/test/e2e/cli.feature
@@ -0,0 +1,171 @@
+Feature: CLI
+  In order to use Karma
+  As a person who wants to write great tests
+  I want command line interface to provide help and useful errors.
+
+  Scenario: Top-level CLI help
+    When I execute Karma with arguments: "--help"
+    Then the stdout is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      Run --help with particular command to see its description and available options.
+
+      Usage:
+        karma <command>
+
+      Commands:
+        karma init        Initialize a config file.
+        karma start       Start the server / do a single run.
+        karma run         Trigger a test run.
+        karma stop        Stop the server.
+        karma completion  Shell completion for karma.
+
+      Options:
+        --help     Print usage and options.                                  [boolean]
+        --version  Print current version.                                    [boolean]
+      """
+
+  Scenario: Current version
+    When I execute Karma with arguments: "--version"
+    Then the stdout matches RegExp:
+      """
+      ^\d\.\d\.\d$
+      """
+
+  Scenario: Error when command is unknown
+    When I execute Karma with arguments: "strat"
+    Then the stderr is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      Run --help with particular command to see its description and available options.
+
+      Usage:
+        karma <command>
+
+      Commands:
+        karma init        Initialize a config file.
+        karma start       Start the server / do a single run.
+        karma run         Trigger a test run.
+        karma stop        Stop the server.
+        karma completion  Shell completion for karma.
+
+      Options:
+        --help     Print usage and options.                                  [boolean]
+        --version  Print current version.                                    [boolean]
+
+      Unknown command: strat
+      """
+
+  Scenario: Init command help
+    When I execute Karma with arguments: "init --help"
+    Then the stdout is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      INIT - Initialize a config file.
+
+      Usage:
+        karma init [configFile]
+
+      Options:
+        --help       Print usage and options.                                [boolean]
+        --log-level  <disable | error | warn | info | debug> Level of logging.
+        --colors     Use colors when reporting and printing logs.
+        --no-colors  Do not use colors when reporting or printing logs.
+      """
+
+  Scenario: Start command help
+    When I execute Karma with arguments: "start --help"
+    Then the stdout is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      START - Start the server / do a single run.
+
+      Usage:
+        karma start [configFile]
+
+      Options:
+        --help                           Print usage and options.            [boolean]
+        --port                           <integer> Port where the server is running.
+        --auto-watch                     Auto watch source files and run on change.
+        --detached                       Detach the server.
+        --no-auto-watch                  Do not watch source files.
+        --log-level                      <disable | error | warn | info | debug> Level
+                                         of logging.
+        --colors                         Use colors when reporting and printing logs.
+        --no-colors                      Do not use colors when reporting or printing
+                                         logs.
+        --reporters                      List of reporters (available: dots, progress,
+                                         junit, growl, coverage).
+        --browsers                       List of browsers to start (eg. --browsers
+                                         Chrome,ChromeCanary,Firefox).
+        --capture-timeout                <integer> Kill browser if does not capture in
+                                         given time [ms].
+        --single-run                     Run the test when browsers captured and exit.
+        --no-single-run                  Disable single-run.
+        --report-slower-than             <integer> Report tests that are slower than
+                                         given time [ms].
+        --fail-on-empty-test-suite       Fail on empty test suite.
+        --no-fail-on-empty-test-suite    Do not fail on empty test suite.
+        --fail-on-failing-test-suite     Fail on failing test suite.
+        --no-fail-on-failing-test-suite  Do not fail on failing test suite.
+      """
+
+  Scenario: Run command help
+    When I execute Karma with arguments: "run --help"
+    Then the stdout is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      RUN - Run the tests (requires running server).
+
+      Usage:
+        karma run [configFile] [-- <clientArgs>]
+
+      Options:
+        --help                         Print usage and options.              [boolean]
+        --port                         <integer> Port where the server is listening.
+        --no-refresh                   Do not re-glob all the patterns.
+        --fail-on-empty-test-suite     Fail on empty test suite.
+        --no-fail-on-empty-test-suite  Do not fail on empty test suite.
+        --log-level                    <disable | error | warn | info | debug> Level
+                                       of logging.
+        --colors                       Use colors when reporting and printing logs.
+        --no-colors                    Do not use colors when reporting or printing
+                                       logs.
+      """
+
+  Scenario: Stop command help
+    When I execute Karma with arguments: "stop --help"
+    Then the stdout is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      STOP - Stop the server (requires running server).
+
+      Usage:
+        karma stop [configFile]
+
+      Options:
+        --help       Print usage and options.                                [boolean]
+        --port       <integer> Port where the server is listening.
+        --log-level  <disable | error | warn | info | debug> Level of logging.
+      """
+
+  Scenario: Completion command help
+    When I execute Karma with arguments: "completion --help"
+    Then the stdout is exactly:
+      """
+      Karma - Spectacular Test Runner for JavaScript.
+
+      COMPLETION - Bash/ZSH completion for karma.
+
+      Installation:
+        karma completion >> ~/.bashrc
+
+      Options:
+        --help  Print usage and options.                                     [boolean]
+      """
diff --git a/test/e2e/step_definitions/core_steps.js b/test/e2e/step_definitions/core_steps.js
