Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
fix(cli): restore command line help contents (#3502)
These were lost after migration to yargs as CLI parser.

Fixes #3474
  • Loading branch information
devoto13 committed May 7, 2020
1 parent 4f2fe56 commit e99da31
Show file tree
Hide file tree
Showing 3 changed files with 239 additions and 76 deletions.
115 changes: 39 additions & 76 deletions lib/cli.js
Expand Up @@ -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]
Expand Down Expand Up @@ -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
}

Expand All @@ -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.')
Expand All @@ -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) {
Expand Down
171 changes: 171 additions & 0 deletions 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]
"""

0 comments on commit e99da31

Please sign in to comment.