/
Help.php
245 lines (211 loc) · 12.1 KB
/
Help.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
<?php declare(strict_types=1);
/*
* 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.
*/
namespace PHPUnit\TextUI;
use PHPUnit\Util\Color;
use SebastianBergmann\Environment\Console;
/**
* @internal This class is not covered by the backward compatibility promise for PHPUnit
*/
final 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;
/**
* @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) {
$width = (new Console)->getNumberOfColumns();
}
if ($withColor === null) {
$this->hasColor = (new 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);
}
}
}
$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;
}
}
}