3. 命令行测试执行器

    上面这个调用例子中，PHPUnit 命令行测试执行器将在当前工作目录中寻找 ArrayTest.php 源文件并加载之。而在此源文件中应当能找到 ArrayTest 测试用例类，此类中的测试将被执行。

    对于每个测试的运行，PHPUnit 命令行工具输出一个字符来指示进展：

    .

    F

    当测试方法运行过程中一个断言失败时输出。

    E

    当测试方法运行过程中产生一个错误时输出。

    R

    当测试被标记为有风险时输出（参见）。

    S

    当测试被跳过时输出（参见未完成的测试与跳过的测试）。

    I

    当测试被标记为不完整或未实现时输出（参见）。

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

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

    1. $ phpunit --help
    2. PHPUnit latest.0 by Sebastian Bergmann and contributors.
    4. Usage:
    5.   phpunit [options] UnitTest.php
    6.   phpunit [options] <directory>
    8. Code Coverage Options:
    9.   --coverage-clover <file>    Generate code coverage report in Clover XML format
    10.   --coverage-crap4j <file>    Generate code coverage report in Crap4J XML format
    11.   --coverage-html <dir>       Generate code coverage report in HTML format
    12.   --coverage-php <file>       Export PHP_CodeCoverage object to file
    13.   --coverage-text <file>      Generate code coverage report in text format [default: standard output]
    14.   --coverage-xml <dir>        Generate code coverage report in PHPUnit XML format
    15.   --coverage-cache <dir>      Cache static analysis results
    16.   --warm-coverage-cache       Warm static analysis cache
    17.   --coverage-filter <dir>     Include <dir> in code coverage analysis
    18.   --path-coverage             Perform path coverage analysis
    19.   --disable-coverage-ignore   Disable annotations for ignoring code coverage
    20.   --no-coverage               Ignore code coverage configuration
    22. Logging Options:
    23.   --log-junit <file>          Log test execution in JUnit XML format to file
    24.   --log-teamcity <file>       Log test execution in TeamCity format to file
    25.   --testdox-html <file>       Write agile documentation in HTML format to file
    26.   --testdox-text <file>       Write agile documentation in Text format to file
    27.   --testdox-xml <file>        Write agile documentation in XML format to file
    28.   --reverse-list              Print defects in reverse order
    29.   --no-logging                Ignore logging configuration
    31. Test Selection Options:
    32.   --filter <pattern>          Filter which tests to run
    33.   --testsuite <name>          Filter which testsuite to run
    34.   --group <name>              Only runs tests from the specified group(s)
    35.   --exclude-group <name>      Exclude tests from the specified group(s)
    36.   --list-groups               List available test groups
    37.   --list-suites               List available test suites
    38.   --list-tests                List available tests
    39.   --test-suffix <suffixes>    Only search for test in files with specified suffix(es). Default: Test.php,.phpt
    41. Test Execution Options:
    42.   --dont-report-useless-tests Do not report tests that do not test anything
    43.   --strict-coverage           Be strict about @covers annotation usage
    44.   --strict-global-state       Be strict about changes to global state
    45.   --disallow-test-output      Be strict about output during tests
    46.   --disallow-resource-usage   Be strict about resource usage during small tests
    47.   --enforce-time-limit        Enforce time limit based on test size
    48.   --default-time-limit <sec>  Timeout in seconds for tests without @small, @medium or @large
    49.   --disallow-todo-tests       Disallow @todo-annotated tests
    51.   --process-isolation         Run each test in a separate PHP process
    52.   --globals-backup            Backup and restore $GLOBALS for each test
    53.   --static-backup             Backup and restore static attributes for each test
    55.   --colors <flag>             Use colors in output ("never", "auto" or "always")
    56.   --columns <n>               Number of columns to use for progress output
    57.   --columns max               Use maximum number of columns for progress output
    58.   --stderr                    Write to STDERR instead of STDOUT
    59.   --stop-on-defect            Stop execution upon first not-passed test
    60.   --stop-on-error             Stop execution upon first error
    61.   --stop-on-failure           Stop execution upon first error or failure
    62.   --stop-on-warning           Stop execution upon first warning
    63.   --stop-on-risky             Stop execution upon first risky test
    65.   --stop-on-incomplete        Stop execution upon first incomplete test
    66.   --fail-on-incomplete        Treat incomplete tests as failures
    67.   --fail-on-risky             Treat risky tests as failures
    68.   --fail-on-skipped           Treat skipped tests as failures
    69.   --fail-on-warning           Treat tests with warnings as failures
    70.   -v|--verbose                Output more verbose information
    71.   --debug                     Display debugging information
    73.   --repeat <times>            Runs the test(s) repeatedly
    74.   --teamcity                  Report test execution progress in TeamCity format
    75.   --testdox                   Report test execution progress in TestDox format
    76.   --testdox-group             Only include tests from the specified group(s)
    77.   --testdox-exclude-group     Exclude tests from the specified group(s)
    78.   --no-interaction            Disable TestDox progress animation
    80.   --order-by <order>          Run tests in order: default|defects|duration|no-depends|random|reverse|size
    81.   --random-order-seed <N>     Use a specific random seed <N> for random order
    82.   --cache-result              Write test results to cache file
    83.   --do-not-cache-result       Do not write test results to cache file
    85. Configuration Options:
    86.   --prepend <file>            A PHP script that is included as early as possible
    87.   --bootstrap <file>          A PHP script that is included before the tests run
    88.   -c|--configuration <file>   Read configuration from XML file
    89.   --no-configuration          Ignore default configuration file (phpunit.xml)
    90.   --extensions <extensions>   A comma separated list of PHPUnit extensions to load
    91.   --no-extensions             Do not load PHPUnit extensions
    92.   --include-path <path(s)>    Prepend PHP's include_path with given path(s)
    93.   -d <key[=value]>            Sets a php.ini value
    94.   --cache-result-file <file>  Specify result cache path and filename
    95.   --generate-configuration    Generate configuration file with suggested settings
    96.   --migrate-configuration     Migrate configuration file to current format
    98. Miscellaneous Options:
    99.   -h|--help                   Prints this usage information
    100.   --version                   Prints the version and exits
    101.   --atleast-version <min>     Checks that version is greater than min and exits
    102.   --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

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

    /path/to/my/test.phpt

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

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

    示例 3.2 过滤器模式示例

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

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

    示例 3.3 过滤器快捷方式

    --testsuite

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

    只运行来自指定分组（可以多个）的测试。可以用 @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 上，用 或 ConEmu。

    本选项有三个可能的值：

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

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

    --columns

    --stderr

    选择输出到 STDERR 而非 STDOUT。

    --stop-on-error

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

    --stop-on-failure

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

    --stop-on-risky

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

    --stop-on-skipped

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

    --stop-on-incomplete

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

    --verbose

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

    --debug

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

    --loader

    指定要使用的 PHPUnit\Runner\TestSuiteLoader 实现。

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

    --repeat

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

    --testdox

    以 TestDox 格式报告测试进度。（参见 ）。

    --printer

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

    --bootstrap

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

    --configuration、-c

    从 XML 文件中读取配置信息。更多细节请参见 XML 配置文件。

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

    如果指定了目录且在此目录中存在 phpunit.xml 或 phpunit.xml.dist（按此顺序）将自动从此文件中读取配置。

    --no-configuration

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

    --include-path

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

    -d

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

    注

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

    TestDox

    PHPUnit 的 TestDox 功能着眼于测试类及其所有测试方法的名称，将它们驼峰式大小写（camel case）（或蛇式大小写（snake_case））拼写的 PHP 名称转换为句子：testBalanceIsInitiallyZero()（或 test_balance_is_initially_zero()）转化为“Balance is initially zero”。如果有多个测试方法的名字互相之间的差异只是一个或多个数字的后缀，例如 testBalanceCannotBecomeNegative() 和 testBalanceCannotBecomeNegative2()，假如所有这些测试都成功，句子“Balance cannot become negative”只会出现一次。

    来看一下从 BankAccount 类生成的敏捷文档：

    1. $ phpunit --testdox BankAccountTest.php
    2. PHPUnit latest.0 by Sebastian Bergmann and contributors.
    4. BankAccount
    5.  ✔ Balance is initially zero

    另外，敏捷文档也能以 HTML 或纯文本格式生成并写入文件中，用 --testdox-html 和 --testdox-text 参数即可。