Clean up --help (#1331)

Clean up `--help` to better align with other commands captured in Dart CLI. Closes #1330

Author: grouma

pkgs/test/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.16.0-nullsafety.3
+
+* Clean up `--help` output.
+
 ## 1.16.0-nullsafety.2
 
 * Allow version `0.40.x` of `analyzer`.

pkgs/test/pubspec.yaml

@@ -1,5 +1,5 @@
 name: test
-version: 1.16.0-nullsafety.2
+version: 1.16.0-nullsafety.3
 description: A full featured library for writing and running Dart tests.
 homepage: https://github.com/dart-lang/test/blob/master/pkgs/test
 
@@ -34,7 +34,7 @@ dependencies:
  yaml: ^2.0.0
  # Use an exact version until the test_api and test_core package are stable.
  test_api: 0.2.19-nullsafety
- test_core: 0.3.12-nullsafety.2
+ test_core: 0.3.12-nullsafety.3
 
 dev_dependencies:
  fake_async: ^1.0.0

pkgs/test/test/runner/runner_test.dart

@@ -13,7 +13,6 @@ import 'dart:math' as math;
 
 import 'package:package_config/package_config.dart';
 import 'package:path/path.dart' as p;
-
 import 'package:test/test.dart';
 import 'package:test_core/src/util/exit_codes.dart' as exit_codes;
 import 'package:test_descriptor/test_descriptor.dart' as d;
@@ -59,10 +58,10 @@ final _defaultConcurrency = math.max(1, Platform.numberOfProcessors ~/ 2);
 final _usage = '''
 Usage: pub run test [files or directories...]
 
--h, --help Shows this usage information.
- --version Shows the package's version.
+-h, --help Show this usage information.
+ --version Show the package:test version.
 
-======== Selecting Tests
+Selecting Tests:
 -n, --name A substring of the name of the test to run.
  Regular expression syntax is supported.
  If passed multiple times, tests must match all substrings.
@@ -74,7 +73,7 @@ Usage: pub run test [files or directories...]
  Supports boolean selector syntax.
  --[no-]run-skipped Run skipped tests instead of skipping them.
 
-======== Running Tests
+Running Tests:
 -p, --platform The platform(s) on which to run the tests.
  $_browsers
 -P, --preset The configuration preset(s) to use.
@@ -85,36 +84,37 @@ Usage: pub run test [files or directories...]
  --pub-serve=<port> The port of a pub serve instance serving "test/".
  --timeout The default test timeout. For example: 15s, 2x, none
  (defaults to "30s")
- --pause-after-load Pauses for debugging before any tests execute.
+ --pause-after-load Pause for debugging before any tests execute.
  Implies --concurrency=1, --debug, and --timeout=none.
  Currently only supported for browser tests.
- --debug Runs the VM and Chrome tests in debug mode.
- --coverage=<directory> Gathers coverage and outputs it to the specified directory.
+ --debug Run the VM and Chrome tests in debug mode.
+ --coverage=<directory> Gather coverage and output it to the specified directory.
  Implies --debug.
- --[no-]chain-stack-traces Chained stack traces to provide greater exception details
+ --[no-]chain-stack-traces Use chained stack traces to provide greater exception details
  especially for asynchronous code. It may be useful to disable
  to provide improved test performance but at the cost of
  debuggability.
  (defaults to on)
- --no-retry Don't re-run tests that have retry set.
- --test-randomize-ordering-seed The seed to randomize the execution order of test cases.
+ --no-retry Don't rerun tests that have retry set.
+ --test-randomize-ordering-seed Use the specified seed to randomize the execution order of test cases.
  Must be a 32bit unsigned integer or "random".
  If "random", pick a random seed to use.
  If not passed, do not randomize test case execution order.
 
-======== Output
--r, --reporter The runner used to print test results.
+Output:
+-r, --reporter Set how to print test results.
 
  [compact] A single line, updated continuously.
  [expanded] (default) A separate line for each update.
- [json] A machine-readable format (see https://bit.ly/2Z7J0OH).
+ [json] A machine-readable format (see https://dart.dev/go/test-docs/json_reporter.md).
 
- --file-reporter The reporter used to write test results to a file.
- Should be in the form <reporter>:<filepath>, e.g. "json:reports/tests.json"
- --verbose-trace Whether to emit stack traces with core library frames.
- --js-trace Whether to emit raw JavaScript stack traces for browser tests.
- --[no-]color Whether to use terminal colors.
+ --file-reporter Set the reporter used to write test results to a file.
+ Should be in the form <reporter>:<filepath>, Example: "json:reports/tests.json"
+ --verbose-trace Emit stack traces with core library frames.
+ --js-trace Emit raw JavaScript stack traces for browser tests.
+ --[no-]color Use terminal colors.
  (auto-detected by default)
+
 ''';
 
 final _browsers = '[vm (default), chrome, phantomjs, firefox' +

pkgs/test_core/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.12-nullsafety.3
+
+* Clean up `--help` output.
+
 ## 0.3.12-nullsafety.2
 
 * Allow version `0.40.x` of `analyzer`.

pkgs/test_core/lib/src/runner/configuration/args.dart

@@ -25,15 +25,15 @@ final ArgParser _parser = (() {
  if (!Platform.isWindows) allRuntimes.remove(Runtime.internetExplorer);
 
  parser.addFlag('help',
- abbr: 'h', negatable: false, help: 'Shows this usage information.');
+ abbr: 'h', negatable: false, help: 'Show this usage information.');
  parser.addFlag('version',
- negatable: false, help: "Shows the package's version.");
+ negatable: false, help: 'Show the package:test version.');
 
  // Note that defaultsTo declarations here are only for documentation purposes.
  // We pass null instead of the default so that it merges properly with the
  // config file.
 
- parser.addSeparator('======== Selecting Tests');
+ parser.addSeparator('Selecting Tests:');
  parser.addMultiOption('name',
  abbr: 'n',
  help: 'A substring of the name of the test to run.\n'
@@ -58,7 +58,7 @@ final ArgParser _parser = (() {
  parser.addFlag('run-skipped',
  help: 'Run skipped tests instead of skipping them.');
 
- parser.addSeparator('======== Running Tests');
+ parser.addSeparator('Running Tests:');
 
  // The UI term "platform" corresponds with the implementation term "runtime".
  // The [Runtime] class used to be called [TestPlatform], but it was changed to
@@ -87,28 +87,29 @@ final ArgParser _parser = (() {
  help: 'The default test timeout. For example: 15s, 2x, none',
  defaultsTo: '30s');
  parser.addFlag('pause-after-load',
- help: 'Pauses for debugging before any tests execute.\n'
+ help: 'Pause for debugging before any tests execute.\n'
  'Implies --concurrency=1, --debug, and --timeout=none.\n'
  'Currently only supported for browser tests.',
  negatable: false);
  parser.addFlag('debug',
- help: 'Runs the VM and Chrome tests in debug mode.', negatable: false);
+ help: 'Run the VM and Chrome tests in debug mode.', negatable: false);
  parser.addOption('coverage',
- help: 'Gathers coverage and outputs it to the specified directory.\n'
+ help: 'Gather coverage and output it to the specified directory.\n'
  'Implies --debug.',
  valueHelp: 'directory');
  parser.addFlag('chain-stack-traces',
- help: 'Chained stack traces to provide greater exception details\n'
+ help: 'Use chained stack traces to provide greater exception details\n'
  'especially for asynchronous code. It may be useful to disable\n'
  'to provide improved test performance but at the cost of\n'
  'debuggability.',
  defaultsTo: true);
  parser.addFlag('no-retry',
- help: "Don't re-run tests that have retry set.",
+ help: "Don't rerun tests that have retry set.",
  defaultsTo: false,
  negatable: false);
  parser.addOption('test-randomize-ordering-seed',
- help: 'The seed to randomize the execution order of test cases.\n'
+ help: 'Use the specified seed to randomize the execution order of test'
+ ' cases.\n'
  'Must be a 32bit unsigned integer or "random".\n'
  'If "random", pick a random seed to use.\n'
  'If not passed, do not randomize test case execution order.');
@@ -118,25 +119,24 @@ final ArgParser _parser = (() {
  reporterDescriptions[reporter] = allReporters[reporter]!.description;
  }
 
- parser.addSeparator('======== Output');
+ parser.addSeparator('Output:');
  parser.addOption('reporter',
  abbr: 'r',
- help: 'The runner used to print test results.',
+ help: 'Set how to print test results.',
  defaultsTo: defaultReporter,
  allowed: reporterDescriptions.keys.toList(),
  allowedHelp: reporterDescriptions);
  parser.addOption('file-reporter',
- help: 'The reporter used to write test results to a file.\n'
+ help: 'Set the reporter used to write test results to a file.\n'
  'Should be in the form <reporter>:<filepath>, '
- 'e.g. "json:reports/tests.json"');
+ 'Example: "json:reports/tests.json"');
  parser.addFlag('verbose-trace',
- negatable: false,
- help: 'Whether to emit stack traces with core library frames.');
+ negatable: false, help: 'Emit stack traces with core library frames.');
  parser.addFlag('js-trace',
  negatable: false,
- help: 'Whether to emit raw JavaScript stack traces for browser tests.');
+ help: 'Emit raw JavaScript stack traces for browser tests.');
  parser.addFlag('color',
- help: 'Whether to use terminal colors.\n(auto-detected by default)');
+ help: 'Use terminal colors.\n(auto-detected by default)');
 
  /// The following options are used only by the internal Google test runner.
  /// They're hidden and not supported as stable API surface outside Google.

pkgs/test_core/lib/src/runner/configuration/reporters.dart

@@ -44,12 +44,16 @@ final _allReporters = <String, ReporterDetails>{
  Directory(config.paths.single).existsSync(),
  printPlatform: config.suiteDefaults.runtimes.length > 1)),
  'json': ReporterDetails(
- 'A machine-readable format (see https://bit.ly/2Z7J0OH).',
+ 'A machine-readable format (see '
+ 'https://dart.dev/go/test-docs/json_reporter.md).',
  (_, engine, sink) => JsonReporter.watch(engine, sink)),
 };
 
-final defaultReporter =
- inTestTests ? 'expanded' : canUseSpecialChars ? 'compact' : 'expanded';
+final defaultReporter = inTestTests
+ ? 'expanded'
+ : canUseSpecialChars
+ ? 'compact'
+ : 'expanded';
 
 /// **Do not call this function without express permission from the test package
 /// authors**.

pkgs/test_core/pubspec.yaml

@@ -1,5 +1,5 @@
 name: test_core
-version: 0.3.12-nullsafety.2
+version: 0.3.12-nullsafety.3
 description: A basic library for writing tests and running them on the VM.
 homepage: https://github.com/dart-lang/test/blob/master/pkgs/test_core