Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add color and wordwrap to help message #3481

Merged
merged 3 commits into from Jan 15, 2019
Merged

Add color and wordwrap to help message #3481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
769c851
Add color and wordwrap to help message
epdenouden Jan 14, 2019
1f00b76
Test colored help message
epdenouden Jan 14, 2019
3c8db63
Fix wrapping long descriptions
epdenouden Jan 14, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
107 changes: 1 addition & 106 deletions src/TextUI/Command.php
View file
Open in desktop
Expand Up @@ -1083,112 +1083,7 @@ protected function handleVersionCheck(): void
protected function showHelp(): void
{
$this->printVersionString();

print <<<EOT
Usage: phpunit [options] UnitTest [UnitTest.php]
phpunit [options] <directory>

Code Coverage Options:

--coverage-clover <file> Generate code coverage report in Clover XML format
--coverage-crap4j <file> Generate code coverage report in Crap4J XML format
--coverage-html <dir> Generate code coverage report in HTML format
--coverage-php <file> Export PHP_CodeCoverage object to file
--coverage-text=<file> Generate code coverage report in text format
Default: Standard output
--coverage-xml <dir> Generate code coverage report in PHPUnit XML format
--whitelist <dir> Whitelist <dir> for code coverage analysis
--disable-coverage-ignore Disable annotations for ignoring code coverage
--no-coverage Ignore code coverage configuration
--dump-xdebug-filter <file> Generate script to set Xdebug code coverage filter

Logging Options:

--log-junit <file> Log test execution in JUnit XML format to file
--log-teamcity <file> Log test execution in TeamCity format to file
--testdox-html <file> Write agile documentation in HTML format to file
--testdox-text <file> Write agile documentation in Text format to file
--testdox-xml <file> Write agile documentation in XML format to file
--reverse-list Print defects in reverse order

Test Selection Options:

--filter <pattern> Filter which tests to run
--testsuite <name,...> Filter which testsuite to run
--group ... Only runs tests from the specified group(s)
--exclude-group ... Exclude tests from the specified group(s)
--list-groups List available test groups
--list-suites List available test suites
--list-tests List available tests
--list-tests-xml <file> List available tests in XML format
--test-suffix ... Only search for test in files with specified
suffix(es). Default: Test.php,.phpt

Test Execution Options:

--dont-report-useless-tests Do not report tests that do not test anything
--strict-coverage Be strict about @covers annotation usage
--strict-global-state Be strict about changes to global state
--disallow-test-output Be strict about output during tests
--disallow-resource-usage Be strict about resource usage during small tests
--enforce-time-limit Enforce time limit based on test size
--default-time-limit=<sec> Timeout in seconds for tests without @small, @medium or @large
--disallow-todo-tests Disallow @todo-annotated tests

--process-isolation Run each test in a separate PHP process
--globals-backup Backup and restore \$GLOBALS for each test
--static-backup Backup and restore static attributes for each test

--colors=<flag> Use colors in output ("never", "auto" or "always")
--columns <n> Number of columns to use for progress output
--columns max Use maximum number of columns for progress output
--stderr Write to STDERR instead of STDOUT
--stop-on-defect Stop execution upon first not-passed test
--stop-on-error Stop execution upon first error
--stop-on-failure Stop execution upon first error or failure
--stop-on-warning Stop execution upon first warning
--stop-on-risky Stop execution upon first risky test
--stop-on-skipped Stop execution upon first skipped test
--stop-on-incomplete Stop execution upon first incomplete test
--fail-on-warning Treat tests with warnings as failures
--fail-on-risky Treat risky tests as failures
-v|--verbose Output more verbose information
--debug Display debugging information

--loader <loader> TestSuiteLoader implementation to use
--repeat <times> Runs the test(s) repeatedly
--teamcity Report test execution progress in TeamCity format
--testdox Report test execution progress in TestDox format
--testdox-group Only include tests from the specified group(s)
--testdox-exclude-group Exclude tests from the specified group(s)
--printer <printer> TestListener implementation to use

--order-by=<order> Run tests in order: default|reverse|random|defects|no-depends
--random-order-seed=<N> Use a specific random seed <N> for random order
--cache-result Write test results to cache file
--do-not-cache-result Do not write test results to cache file

Configuration Options:

--prepend <file> A PHP script that is included as early as possible
--bootstrap <file> A PHP script that is included before the tests run
-c|--configuration <file> Read configuration from XML file
--no-configuration Ignore default configuration file (phpunit.xml)
--no-logging Ignore logging configuration
--no-extensions Do not load PHPUnit extensions
--include-path <path(s)> Prepend PHP's include_path with given path(s)
-d key[=value] Sets a php.ini value
--generate-configuration Generate configuration file with suggested settings
--cache-result-file=<file> Specify result cache path and filename

Miscellaneous Options:

-h|--help Prints this usage information
--version Prints the version and exits
--atleast-version <min> Checks that version is greater than min and exits
--check-version Check whether PHPUnit is the latest version

EOT;
(new \Help())->writeToConsole();
}

/**
Expand Down
244 changes: 244 additions & 0 deletions src/Util/Help.php
View file
Open in desktop
@@ -0,0 +1,244 @@
<?php
/*
* This file is part of PHPUnit.
*
* (c) Sebastian Bergmann <sebastian@phpunit.de>
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/

use PHPUnit\Util\Color;
use SebastianBergmann\Environment\Console;

class Help
{
private const LEFT_MARGIN = ' ';

private const HELP_TEXT = [
'Usage' => [
['text' => 'phpunit [options] UnitTest [UnitTest.php]'],
['text' => 'phpunit [options] <directory>'],
],
'Code Coverage Options' => [
['arg' => '--coverage-clover <file>', 'desc' => 'Generate code coverage report in Clover XML format'],
['arg' => '--coverage-crap4j <file>', 'desc' => 'Generate code coverage report in Crap4J XML format'],
['arg' => '--coverage-html <dir>', 'desc' => 'Generate code coverage report in HTML format'],
['arg' => '--coverage-php <file>', 'desc' => 'Export PHP_CodeCoverage object to file'],
['arg' => '--coverage-text=<file>', 'desc' => 'Generate code coverage report in text format [default: standard output]'],
['arg' => '--coverage-xml <dir>', 'desc' => 'Generate code coverage report in PHPUnit XML format'],
['arg' => '--whitelist <dir>', 'desc' => 'Whitelist <dir> for code coverage analysis'],
['arg' => '--disable-coverage-ignore', 'desc' => 'Disable annotations for ignoring code coverage'],
['arg' => '--no-coverage', 'desc' => 'Ignore code coverage configuration'],
['arg' => '--dump-xdebug-filter <file>', 'desc' => 'Generate script to set Xdebug code coverage filter'],
],

'Logging Options' => [
['arg' => '--log-junit <file>', 'desc' => 'Log test execution in JUnit XML format to file'],
['arg' => '--log-teamcity <file>', 'desc' => 'Log test execution in TeamCity format to file'],
['arg' => '--testdox-html <file>', 'desc' => 'Write agile documentation in HTML format to file'],
['arg' => '--testdox-text <file>', 'desc' => 'Write agile documentation in Text format to file'],
['arg' => '--testdox-xml <file>', 'desc' => 'Write agile documentation in XML format to file'],
['arg' => '--reverse-list', 'desc' => 'Print defects in reverse order'],
],

'Test Selection Options' => [
['arg' => '--filter <pattern>', 'desc' => 'Filter which tests to run'],
['arg' => '--testsuite <name>', 'desc' => 'Filter which testsuite to run'],
['arg' => '--group <name>', 'desc' => 'Only runs tests from the specified group(s)'],
['arg' => '--exclude-group <name>', 'desc' => 'Exclude tests from the specified group(s)'],
['arg' => '--list-groups', 'desc' => 'List available test groups'],
['arg' => '--list-suites', 'desc' => 'List available test suites'],
['arg' => '--list-tests', 'desc' => 'List available tests'],
['arg' => '--list-tests-xml <file>', 'desc' => 'List available tests in XML format'],
['arg' => '--test-suffix <suffixes>', 'desc' => 'Only search for test in files with specified suffix(es). Default: Test.php,.phpt'],
],

'Test Execution Options' => [
['arg' => '--dont-report-useless-tests', 'desc' => 'Do not report tests that do not test anything'],
['arg' => '--strict-coverage', 'desc' => 'Be strict about @covers annotation usage'],
['arg' => '--strict-global-state', 'desc' => 'Be strict about changes to global state'],
['arg' => '--disallow-test-output', 'desc' => 'Be strict about output during tests'],
['arg' => '--disallow-resource-usage', 'desc' => 'Be strict about resource usage during small tests'],
['arg' => '--enforce-time-limit', 'desc' => 'Enforce time limit based on test size'],
['arg' => '--default-time-limit=<sec>', 'desc' => 'Timeout in seconds for tests without @small, @medium or @large'],
['arg' => '--disallow-todo-tests', 'desc' => 'Disallow @todo-annotated tests'],
['spacer' => ''],

['arg' => '--process-isolation', 'desc' => 'Run each test in a separate PHP process'],
['arg' => '--globals-backup', 'desc' => 'Backup and restore $GLOBALS for each test'],
['arg' => '--static-backup', 'desc' => 'Backup and restore static attributes for each test'],
['spacer' => ''],

['arg' => '--colors=<flag>', 'desc' => 'Use colors in output ("never", "auto" or "always")'],
['arg' => '--columns <n>', 'desc' => 'Number of columns to use for progress output'],
['arg' => '--columns max', 'desc' => 'Use maximum number of columns for progress output'],
['arg' => '--stderr', 'desc' => 'Write to STDERR instead of STDOUT'],
['arg' => '--stop-on-defect', 'desc' => 'Stop execution upon first not-passed test'],
['arg' => '--stop-on-error', 'desc' => 'Stop execution upon first error'],
['arg' => '--stop-on-failure', 'desc' => 'Stop execution upon first error or failure'],
['arg' => '--stop-on-warning', 'desc' => 'Stop execution upon first warning'],
['arg' => '--stop-on-risky', 'desc' => 'Stop execution upon first risky test'],
['arg' => '--stop-on-skipped', 'desc' => 'Stop execution upon first skipped test'],
['arg' => '--stop-on-incomplete', 'desc' => 'Stop execution upon first incomplete test'],
['arg' => '--fail-on-warning', 'desc' => 'Treat tests with warnings as failures'],
['arg' => '--fail-on-risky', 'desc' => 'Treat risky tests as failures'],
['arg' => '-v|--verbose', 'desc' => 'Output more verbose information'],
['arg' => '--debug', 'desc' => 'Display debugging information'],
['spacer' => ''],

['arg' => '--loader <loader>', 'desc' => 'TestSuiteLoader implementation to use'],
['arg' => '--repeat <times>', 'desc' => 'Runs the test(s) repeatedly'],
['arg' => '--teamcity', 'desc' => 'Report test execution progress in TeamCity format'],
['arg' => '--testdox', 'desc' => 'Report test execution progress in TestDox format'],
['arg' => '--testdox-group', 'desc' => 'Only include tests from the specified group(s)'],
['arg' => '--testdox-exclude-group', 'desc' => 'Exclude tests from the specified group(s)'],
['arg' => '--printer <printer>', 'desc' => 'TestListener implementation to use'],
['spacer' => ''],

['arg' => '--order-by=<order>', 'desc' => 'Run tests in order: default|reverse|random|defects|no-depends'],
['arg' => '--random-order-seed=<N>', 'desc' => 'Use a specific random seed <N> for random order'],
['arg' => '--cache-result', 'desc' => 'Write test results to cache file'],
['arg' => '--do-not-cache-result', 'desc' => 'Do not write test results to cache file'],
],

'Configuration Options' => [
['arg' => '--prepend <file>', 'desc' => 'A PHP script that is included as early as possible'],
['arg' => '--bootstrap <file>', 'desc' => 'A PHP script that is included before the tests run'],
['arg' => '-c|--configuration <file>', 'desc' => 'Read configuration from XML file'],
['arg' => '--no-configuration', 'desc' => 'Ignore default configuration file (phpunit.xml)'],
['arg' => '--no-logging', 'desc' => 'Ignore logging configuration'],
['arg' => '--no-extensions', 'desc' => 'Do not load PHPUnit extensions'],
['arg' => '--include-path <path(s)>', 'desc' => 'Prepend PHP\'s include_path with given path(s)'],
['arg' => '-d <key[=value]>', 'desc' => 'Sets a php.ini value'],
['arg' => '--generate-configuration', 'desc' => 'Generate configuration file with suggested settings'],
['arg' => '--cache-result-file=<file>', 'desc' => 'Specify result cache path and filename'],
],

'Miscellaneous Options' => [
['arg' => '-h|--help', 'desc' => 'Prints this usage information'],
['arg' => '--version', 'desc' => 'Prints the version and exits'],
['arg' => '--atleast-version <min>', 'desc' => 'Checks that version is greater than min and exits'],
['arg' => '--check-version', 'desc' => 'Check whether PHPUnit is the latest version'],
],

];

/**
* @var int Number of columns required to write the longest option name to the console
*/
private $maxArgLength = 0;

/**
* @var int Number of columns left for the description field after padding and option
*/
private $maxDescLength = 0;

/**
* @var bool Use color highlights for sections, options and parameters
*/
private $hasColor = false;

public function __construct(?int $width = null, ?bool $withColor = null)
{
if ($width === null || $withColor === null) {
$console = new Console();
}

if ($withColor === null) {
$this->hasColor = $console->hasColorSupport();
} else {
$this->hasColor = $withColor;
}

foreach (self::HELP_TEXT as $section => $options) {
foreach ($options as $option) {
if (isset($option['arg'])) {
$this->maxArgLength = \max($this->maxArgLength, \strlen($option['arg']) ?? 0);
}
}
}

if ($width === null) {
$width = $console->getNumberOfColumns();
}
$this->maxDescLength = $width - $this->maxArgLength - 4;
}

/**
* Write the help file to the CLI, adapting width and colors to the console
*/
public function writeToConsole(): void
{
if ($this->hasColor) {
$this->writeWithColor();
} else {
$this->writePlaintext();
}
}

private function writePlaintext(): void
{
foreach (self::HELP_TEXT as $section => $options) {
print "$section:" . \PHP_EOL;

if ($section !== 'Usage') {
print \PHP_EOL;
}

foreach ($options as $option) {
if (isset($option['spacer'])) {
print \PHP_EOL;
}

if (isset($option['text'])) {
print self::LEFT_MARGIN . $option['text'] . \PHP_EOL;
}

if (isset($option['arg'])) {
$arg = \str_pad($option['arg'], $this->maxArgLength);
print self::LEFT_MARGIN . $arg . ' ' . $option['desc'] . \PHP_EOL;
}
}

print \PHP_EOL;
}
}

private function writeWithColor(): void
{
foreach (self::HELP_TEXT as $section => $options) {
print Color::colorize('fg-yellow', "$section:") . \PHP_EOL;

foreach ($options as $option) {
if (isset($option['spacer'])) {
print \PHP_EOL;
}

if (isset($option['text'])) {
print self::LEFT_MARGIN . $option['text'] . \PHP_EOL;
}

if (isset($option['arg'])) {
$arg = Color::colorize('fg-green', \str_pad($option['arg'], $this->maxArgLength));
$arg = \preg_replace_callback(
'/(<[^>]+>)/',
function ($matches) {
return Color::colorize('fg-cyan', $matches[0]);
},
$arg
);
$desc = \explode(\PHP_EOL, \wordwrap($option['desc'], $this->maxDescLength, \PHP_EOL));

print self::LEFT_MARGIN . $arg . ' ' . $desc[0] . \PHP_EOL;

for ($i = 1; $i < \count($desc); $i++) {
print \str_repeat(' ', $this->maxArgLength + 3) . $desc[$i] . \PHP_EOL;
}
}
}

print \PHP_EOL;
}
}
}