PHPUnit9.0 命令行测试执行器-命令行选项

PHPUnit 命令行测试执行器可通过 ​phpunit​命令调用。下面的代码展示了如何用 PHPUnit 命令行测试执行器来运行测试：

$ phpunit ArrayTest
PHPUnit latest.0 by Sebastian Bergmann and contributors.

..

Time: 0 seconds

OK (2 tests, 2 assertions)

上面这个调用例子中，PHPUnit 命令行测试执行器将在当前工作目录中寻找 ​ArrayTest.php​ 源文件并加载之。而在此源文件中应当能找到 ​ArrayTest​测试用例类，此类中的测试将被执行。对于每个测试的运行，PHPUnit 命令行工具输出一个字符来指示进展：

• ​.​当测试成功时输出。
• ​F​当测试方法运行过程中一个断言失败时输出。
• ​E​当测试方法运行过程中产生一个错误时输出。
• ​R​当测试被标记为有风险时输出。
• ​S​当测试被跳过时输出。
• ​I​当测试被标记为不完整或未实现时输出。

PHPUnit 区分失败（failure）与错误（error）。失败指的是被违背了的 PHPUnit 断言，例如一个失败的 ​assertSame()​ 调用。错误指的是意料之外的异常（exception）或 PHP 错误。这种差异已被证明在某些时候是非常有用的，因为错误往往比失败更容易修复。如果得到了一个非常长的问题列表，那么最好先对付错误，当错误全部修复了之后再试一次瞧瞧还有没有失败。

命令行选项

让我们来瞧瞧以下代码中命令行测试执行器的各种选项：

$ phpunit --help
PHPUnit latest.0 by Sebastian Bergmann and contributors.

Usage:
  phpunit [options] 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
  --coverage-cache <dir>      Cache static analysis results
  --warm-coverage-cache       Warm static analysis cache
  --coverage-filter <dir>     Include <dir> in code coverage analysis
  --path-coverage             Perform path coverage analysis
  --disable-coverage-ignore   Disable annotations for ignoring code coverage
  --no-coverage               Ignore code coverage configuration

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
  --no-logging                Ignore logging configuration

Test Selection Options:
  --filter <pattern>          Filter which tests to run
  --testsuite <name>          Filter which testsuite to run
  --group <name>              Only runs tests from the specified group(s)
  --exclude-group <name>      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 <suffixes>    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-incomplete        Treat incomplete tests as failures
  --fail-on-risky             Treat risky tests as failures
  --fail-on-skipped           Treat skipped tests as failures
  --fail-on-warning           Treat tests with warnings as failures
  -v|--verbose                Output more verbose information
  --debug                     Display debugging information

  --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)
  --no-interaction            Disable TestDox progress animation
  --printer <printer>         TestListener implementation to use

  --order-by <order>          Run tests in order: default|defects|duration|no-depends|random|reverse|size
  --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)
  --extensions <extensions>   A comma separated list of PHPUnit extensions to load
  --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
  --cache-result-file <file>  Specify result cache path and filename
  --generate-configuration    Generate configuration file with suggested settings
  --migrate-configuration     Migrate configuration file to current format

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

​phpunit UnitTest​

• 运行由 UnitTest 类提供的测试。这个类应当在 ​UnitTest.php​ 源文件中声明。
• ​UnitTest ​这个类必须满足以下二个条件之一：要么它继承自 ​PHPUnit\Framework\TestCase​；要么它提供 ​public static suite()​ 方法，这个方法返回一个​PHPUnit\Framework\Test​ 对象，比如，一个 ​PHPUnit\Framework\TestSuite​ 类的实例。

​phpunit UnitTest UnitTest.php​

• 运行由 ​UnitTest类提供的测试。这个类应当在指定的源文件中声明。

​--coverage-clover​

• 为运行的测试生成带有代码覆盖率信息的 XML 格式的日志文件。

​--coverage-crap4j​

• 生成 Crap4j 格式的代码覆盖率报告。

​--coverage-html​

• 生成 HTML 格式的代码覆盖率报告。

​--coverage-php​

• 生成一个序列化后的 ​PHP_CodeCoverage ​对象，此对象含有代码覆盖率信息。

​--coverage-text​

• 为运行的测试以人们可读的格式生成带有代码覆盖率信息的日志文件或命令行输出。

​--log-junit​

• 为运行的测试生成 JUnit XML 格式的日志文件。

​--testdox-html​ 和 ​--testdox-text​

• 为运行的测试以 HTML 或纯文本格式生成敏捷文档

​--filter​

• 只运行名称与给定模式匹配的测试。如果模式未用定界符包住，PHPUnit 将用 / 定界符来将其包住。

测试名称将以以下格式之一进行匹配：

​TestNamespace\TestCaseClass::testMethod​

默认的测试名称格式等价于在测试方法内使用 ​__METHOD__​ 魔术常量。

​TestNamespace\TestCaseClass::testMethod with data set #0​

当测试拥有数据供给器时，数据的每轮迭代都会将其当前索引附加在默认测试名称结尾处。

​TestNamespace\TestCaseClass::testMethod with data set "my named data"​

当测试拥有使用命名数据集的数据供给器时，数据的每轮迭代都会将当前名称附加在默认测试名称结尾处。命名数据集的例子参见示例 3.1。

示例 3.1 命名数据集

<?php
use PHPUnit\Framework\TestCase;

namespace TestNamespace;

class TestCaseClass extends TestCase
{
    /**
     * @dataProvider provider
     */
    public function testMethod($data)
    {
        $this->assertTrue($data);
    }

    public function provider()
    {
        return [
            'my named data' => [true],
            'my data'       => [true]
        ];
    }
}

​/path/to/my/test.phpt​

• 对于 PHPT 测试，其测试名称是文件系统路径。

有效的过滤器模式例子参见示例 3.2。
示例 3.2 过滤器模式示例

--filter 'TestNamespace\\TestCaseClass::testMethod'
--filter 'TestNamespace\\TestCaseClass'
--filter TestNamespace
--filter TestCaseClase
--filter testMethod
--filter '/::testMethod .*"my named data"/'
--filter '/::testMethod .*#5$/'
--filter '/::testMethod .*#(5|6|7)$/'

在匹配数据供给器时有一些额外的快捷方式，参见示例 3.3。
示例 3.3 过滤器快捷方式

--filter 'testMethod#2'
--filter 'testMethod#2-4'
--filter '#2'
--filter '#2-4'
--filter 'testMethod@my named data'
--filter 'testMethod@my.*data'
--filter '@my named data'
--filter '@my.*data'

​--testsuite​

• 只运行名称与给定模式匹配的测试套件。

​--group​

• 只运行来自指定分组（可以多个）的测试。可以用 ​@group​ 标注为测试标记其所属的分组。
• ​@author​ 和 ​@ticket​ 标注都是 ​@group​ 的别名，分别允许基于作者和事务 ID 筛选测试。

​--exclude-group​

• 排除来自指定分组（可以多个）的测试。可以用 ​@group​ 标注为测试标记其所属的分组。

​--list-groups​

• 列出所有有效的测试分组。

​--test-suffix​

• 只查找文件名以指定后缀（可以多个）结尾的测试文件。

​--dont-report-useless-tests​

• 不报告事实上不测试任何内容的测试。

​--strict-coverage​

• 更严格对待意外的代码覆盖。

​--strict-global-state​

• 更严格对待全局状态篡改。

​--disallow-test-output​

• 更严格对待测试执行期间产生的输出。

​--disallow-todo-tests​

• 不执行文档注释块中含有 ​@todo​ 标注的测试。

​--enforce-time-limit​

• 根据测试规模对其加上执行时长限制。

​--process-isolation​

• 每个测试都在独立的 PHP 进程中运行。

​--no-globals-backup​

• 不要备份与还原 ​$GLOBALS​。

​--static-backup​

• 备份与还原用户定义的类中的静态属性。

​--colors​
使用彩色输出。在 Windows 上，用 ANSICON 或 ConEmu。
本选项有三个可能的值：

• ​never​：完全不使用彩色输出。当未使用 ​--colors​ 选项时，这是默认值。
• ​auto​：如果当前终端不支持彩色、或者输出被管道输出至其他命令、或输出被重定向至文件时，不使用彩色输出，其余情况使用彩色。
• ​always​：总是使用彩色输出，即使当前终端不支持彩色、输出被管道输出至其他命令、或输出被重定向至文件。

当使用了 ​--colors​ 选项但未指定任何值时，将选择 ​auto​ 做为其值。

​--columns​

• 定义输出所使用的列数。如果将其值定义为 ​max​，则使用当前终端所支持的最大列数。

​--stderr​

• 选择输出到 ​STDERR ​而非 ​STDOUT​。

​--stop-on-error​

• 首次错误出现后停止执行。

​--stop-on-failure​

• 首次错误或失败出现后停止执行。

​--stop-on-risky​

• 首次碰到有风险的测试时停止执行。

​--stop-on-skipped​

• 首次碰到跳过的测试时停止执行。

​--stop-on-incomplete​

• 首次碰到不完整的测试时停止执行。

​--verbose​

• 输出更详尽的信息，例如不完整或者跳过的测试的名称。​

• 输出调试信息，例如当一个测试开始执行时输出其名称。

​--loader​

• 指定要使用的 ​PHPUnit\Runner\TestSuiteLoader​ 实现。
• 标准的测试套件加载器将在当前工作目录和 PHP 的 ​include_path ​配置指令中指定的每个目录内查找源文件。诸如 ​Project_Package_Class ​这样的类名对应的源文件名为 ​Project/Package/Class.php​

​--repeat​

• 将测试重复运行指定次数。​

• 以 TestDox 格式报告测试进度。

​--printer​

• 指定要使用的结果输出器（printer）。输出器类必须扩展 ​PHPUnit\Util\Printer​ 并且实现 ​PHPUnit\Framework\TestListener​ 接口。

• 在测试前先运行一个 “bootstrap” PHP 文件。

​--configuration​、​-c​

• 从 XML 文件中读取配置信息。
• 如果 ​phpunit.xml​ 或 ​phpunit.xml.dist​（按此顺序）存在于当前工作目录并且未使用 ​--configuration​，将自动从此文件中读取配置。
• 如果指定了目录且在此目录中存在 ​phpunit.xml​ 或 ​phpunit.xml.dist​（按此顺序）将自动从此文件中读取配置。

​--no-configuration​

• 忽略当前工作目录下的 ​phpunit.xml​ 与 ​phpunit.xml.dist​

• 向 PHP 的 ​include_path ​开头添加指定路径（可以多个）。

• 设置指定的 PHP 配置选项的值。

请注意，选项不能放在参数之后。