第 3 章 命令行测试执行器

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

phpunit ArrayTest
PHPUnit 3.8.0 by Sebastian Bergmann.

..

Time: 0 seconds


OK (2 tests, 2 assertions)

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

.

当测试成功时输出。

F

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

E

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

S

当测试被跳过时输出(参见第 7 章)。

I

当测试被标记为不完整或未实现时输出(参见第 7 章)。

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

命令行选项

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

phpunit --help
PHPUnit 3.8.0 by Sebastian Bergmann.

Usage: phpunit [switches] UnitTest [UnitTest.php]
       phpunit [switches] <directory>

  --log-junit <file>        Log test execution in JUnit XML format to file.
  --log-tap <file>          Log test execution in TAP format to file.
  --log-json <file>         Log test execution in JSON format.

  --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>     Serialize PHP_CodeCoverage object to file.
  --coverage-text=<file>    Generate code coverage report in text format.
                            Default to writing to the standard output.

  --testdox-html <file>     Write agile documentation in HTML format to file.
  --testdox-text <file>     Write agile documentation in Text format to file.

  --filter <pattern>        Filter which tests to run.
  --testsuite <pattern>     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.
  --test-suffix ...         Only search for test in files with specified
                            suffix(es). Default: Test.php,.phpt

  --loader <loader>         TestSuiteLoader implementation to use.
  --printer <printer>       TestSuiteListener implementation to use.
  --repeat <times>          Runs the test(s) repeatedly.

  --tap                     Report test execution progress in TAP format.
  --testdox                 Report test execution progress in TestDox format.

  --colors                  Use colors in output.
  --stderr                  Write to STDERR instead of STDOUT.
  --stop-on-error           Stop execution upon first error.
  --stop-on-failure         Stop execution upon first error or failure.
  --stop-on-skipped         Stop execution upon first skipped test.
  --stop-on-incomplete      Stop execution upon first incomplete test.
  --strict                  Run tests in strict mode.
  -v|--verbose              Output more verbose information.
  --debug                   Display debugging information during test execution.

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

  --bootstrap <file>        A "bootstrap" PHP file that is run before the tests.
  -c|--configuration <file> Read configuration from XML file.
  --no-configuration        Ignore default configuration file (phpunit.xml).
  --include-path <path(s)>  Prepend PHP's include_path with given path(s).
  -d key[=value]            Sets a php.ini value.

  -h|--help                 Prints this usage information.
  --version                 Prints the version and exits.
phpunit UnitTest

运行由 UnitTest 类提供的测试。这个类应当在 UnitTest.php 源文件中声明。

UnitTest 这个类必须满足以下二个条件之一:要么它继承自 PHPUnit_Framework_TestCase;要么它提供 public static suite() 方法,这个方法返回一个 PHPUnit_Framework_Test 对象,比如,一个 PHPUnit_Framework_TestSuite 类的实例。

phpunit UnitTest UnitTest.php

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

--log-junit

为运行的测试生成 JUnit XML 格式的日志文件。更多细节请参见第 14 章

--log-tap

为运行的测试生成 Test Anything Protocol (TAP) 格式的日志文件。更多细节请参见第 14 章

--log-json

生成 JSON 格式的日志文件。更多细节请参见第 14 章

--coverage-html

生成 HTML 格式的代码覆盖率报告。更多细节请参见第 10 章

请注意,此功能仅当安装了 tokenizer 和 Xdebug 这两个 PHP 扩展后才可用。

--coverage-clover

为运行的测试生成带有代码覆盖率信息的 XML 格式的日志文件。更多细节请参见第 14 章

请注意,此功能仅当安装了 tokenizer 和 Xdebug 这两个 PHP 扩展后才可用。

--coverage-crap4j

生成 Crap4j 格式的代码覆盖率报告。更多细节请参见第 10 章

请注意,此功能仅当安装了 tokenizer 和 Xdebug 这两个 PHP 扩展后才可用。

--coverage-php

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

请注意,此功能仅当安装了 tokenizer 和 Xdebug 这两个 PHP 扩展后才可用。

--coverage-text

为运行的测试以人们可读的格式生成带有代码覆盖率信息的日志文件或命令行输出。更多细节请参见第 14 章

请注意,此功能仅当安装了 tokenizer 和 Xdebug 这两个 PHP 扩展后才可用。

--testdox-html and --testdox-text

为运行的测试以 HTML 或纯文本格式生成敏捷文档。更多细节请参见第 11 章

--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
namespace TestNamespace;

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

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


/path/to/my/test.phpt

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

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

例 3.2: 过滤器模式例子

  • --filter 'TestNamespace\\TestCaseClass::testMethod'

  • --filter 'TestNamespace\\TestCaseClass'

  • --filter TestNamespace

  • --filter TestCaseClass

  • --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 标注是 @group 的一个别名,允许按作者来筛选测试。

--exclude-group

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

--list-groups

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

--test-suffix

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

--loader

指定要使用的 PHPUnit_Runner_TestSuiteLoader 实现。

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

--printer

指定要使用的结果输出器(printer)。输出器类必须扩展 PHPUnit_Util_Printer 并且实现 PHPUnit_Framework_TestListener 接口。

--repeat

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

--tap

使用 Test Anything Protocol (TAP) 报告测试进度。 更多细节请参见第 14 章

--testdox

将测试进度作为敏捷文档来报告。更多细节请参见第 11 章

--colors

使用彩色输出。

--stderr

选择输出到 STDERR 而非 STDOUT

--stop-on-error

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

--stop-on-failure

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

--stop-on-skipped

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

--stop-on-incomplete

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

--strict

以严格模式运行测试。当启用严格模式时:

  • 本身产生输出的测试将会失败。

  • 不含断言的错误将会失败,并且不会生成代码覆盖率信息。

  • 如果安装了 PHP_Invoker 组件包:

    • 标记为 @large 的测试如果其执行时间超过60秒将视为失败。这个超时限制可以通过 XML 配置文件的 timeoutForLargeTests 属性进行配置。

    • 标记为 @medium 的测试如果其执行时间超过10秒将视为失败。这个超时限制可以通过 XML 配置文件的 timeoutForMediumTests 属性进行配置。

    • 未标记为 @medium@large 的测试如果其执行时间超过1秒将视为失败。这个超时限制可以通过 XML 配置文件的 timeoutForSmallTests 属性进行配置。

--verbose

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

--process-isolation

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

--no-globals-backup

不要备份并还原 $GLOBALS。更多细节请参见“全局状态”一节

--static-backup

备份并还原用户定义的类中的静态属性。更多细节请参见“全局状态”一节

--bootstrap

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

--configuration, -c

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

如果当前工作目录下存在 phpunit.xml 或者 phpunit.xml.dist (按此顺序查找),同时又使用 --configuration 选项,那么将自动从此文件中读取配置信息。

--no-configuration

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

--include-path

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

-d

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

--debug

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

请在 GitHub 上 开启任务单 来对本页提出改进建议。万分感谢!