PHPUnit 手册(转)

PHPUnit 手册

Sebastian Bergmann

本作品依据 Creative Commons Attribution 3.0 Unported 许可协议进行授权。

此版本对应于 PHPUnit 5.0。最后更新于 2015-11-29。

1. 安装 PHPUnit

需求

PHP 档案包 (PHAR)

Windows
校验 PHPUnit PHAR 发行包

边缘情况

3. 命令行测试执行器

命令行选项

4. 基境(fixture)

setUp() 多 tearDown() 少
变体
基境共享
全局状态

5. 组织测试

用文件系统来编排测试套件
用 XML 配置来编排测试套件

6. 有风险的测试

无用测试
意外的代码覆盖
测试执行期间产生的输出
测试执行时长的超时限制
全局状态篡改

7. 未完成的测试与跳过的测试

未完成的测试
跳过测试
用 @requires 来跳过测试

1. 清理数据库
2. 建立基境
3–5. 运行测试、验证结果、并拆除基境

PHPUnit 数据库测试用例的配置

实现 getConnection()
实现 getDataSet()
数据库构架(DDL)怎么办？
小建议：使用你自己的抽象数据库 TestCase 类

理解 DataSet（数据集）和 DataTable（数据表）

可用的各种实现
当心外键
实现自有的 DataSet/DataTable

数据库连接 API

数据库断言 API

对表中数据行的数量作出断言
对表的状态作出断言
对查询的结果作出断言
对多个表的状态作出断言

常见问题（FAQ）

PHPUnit 会为每个测试（重新）创建数据库吗？
为了让数据库扩展模块正常工作，需要在应用程序中使用 PDO 吗？
如果看到 “Too much Connections” 错误该怎么办？
Flat XML / CSV 数据集中如何处理 NULL？

9. 测试替身

Stubs （桩件）
仿件对象(Mock Object)
Prophecy
对特质(Trait)与抽象类进行模仿
对 Web 服务(Web Services)进行上桩或模仿
对文件系统进行模仿

10. 测试实践

在开发过程中
在调试过程中

11. 代码覆盖率分析

用于代码覆盖率的软件衡量标准
将文件列入白名单
略过代码块
指明要覆盖的方法
边缘情况

12. 测试的其他用途

敏捷文档
跨团队测试

13. Logging （日志记录）

测试结果 (XML)
测试结果 (TAP)
测试结果 (JSON)
代码覆盖率 (XML)
代码覆盖率 (TEXT)

14. 扩展 PHPUnit

从 PHPUnit_Framework_TestCase 派生子类
编写自定义断言
实现 PHPUnit_Framework_TestListener
从 PHPUnit_Extensions_TestDecorator 派生子类
实现 PHPUnit_Framework_Test

A. 断言

assertArrayHasKey()
assertClassHasAttribute()
assertArraySubset()
assertClassHasStaticAttribute()
assertContains()
assertContainsOnly()
assertContainsOnlyInstancesOf()
assertCount()
assertEmpty()
assertEqualXMLStructure()
assertEquals()
assertFalse()
assertFileEquals()
assertFileExists()
assertGreaterThan()
assertGreaterThanOrEqual()
assertInfinite()
assertInstanceOf()
assertInternalType()
assertJsonFileEqualsJsonFile()
assertJsonStringEqualsJsonFile()
assertJsonStringEqualsJsonString()
assertLessThan()
assertLessThanOrEqual()
assertNan()
assertNull()
assertObjectHasAttribute()
assertRegExp()
assertStringMatchesFormat()
assertStringMatchesFormatFile()
assertSame()
assertStringEndsWith()
assertStringEqualsFile()
assertStringStartsWith()
assertThat()
assertTrue()
assertXmlFileEqualsXmlFile()
assertXmlStringEqualsXmlFile()
assertXmlStringEqualsXmlString()

B. 标注

@author
@after
@afterClass
@backupGlobals
@backupStaticAttributes
@before
@beforeClass
@codeCoverageIgnore*
@covers
@coversDefaultClass
@coversNothing
@dataProvider
@depends
@expectedException
@expectedExceptionCode
@expectedExceptionMessage
@expectedExceptionMessageRegExp
@group
@large
@medium
@preserveGlobalState
@requires
@runTestsInSeparateProcesses
@runInSeparateProcess
@small
@test
@testdox
@ticket
@uses

C. XML 配置文件

PHPUnit
测试套件
分组
Whitelisting Files for Code Coverage
Logging （日志记录）
测试监听器
设定 PHP INI 设置、常量、全局变量
为 Selenium RC 配置浏览器

D. 索引

E. 参考书目

F. 版权

第 1 章安装 PHPUnit

需求

PHPUnit 5.0 需要 PHP 5.6，强烈推荐使用最新版本的 PHP。

PHPUnit 需要使用 dom 和 json 扩展，它们通常是默认启用的。

PHPUnit 还需要 pcre、reflection、spl 扩展。这些标准扩展默认启用，并且除非修改 PHP 的构建系统和 C 源代码，否则无法禁用它们。

代码覆盖率分析报告功能需要 Xdebug （2.1.3以上）与 tokenizer 扩展。生成 XML 格式的报告需要有 xmlwriter 扩展。

PHP 档案包 (PHAR)

要获取 PHPUnit，最简单的方法是下载 PHPUnit 的 PHP 档案包 (PHAR)，它将 PHPUnit 所需要的所有必要组件（以及某些可选组件）捆绑在单个文件中：

要使用 PHP档案包(PHAR)需要有 phar 扩展。

要使用 PHAR 的 --self-update 功能需要有 openssl 扩展。

如果启用了 Suhosin 扩展，需要在 php.ini 中允许执行 PHAR：

suhosin.executor.include.whitelist = phar

注意

要从 https://phar.phpunit.de/ 下载，需要支持 TLS/SNI的客户端，例如 wget 1.14（或更高版本）。

如果要全局安装 PHAR：

$ wget https://phar.phpunit.de/phpunit.phar
$ chmod +x phpunit.phar
$ sudo mv phpunit.phar /usr/local/bin/phpunit
$ phpunit --version
PHPUnit x.y.z by Sebastian Bergmann and contributors.

也可以直接使用下载的 PHAR 文件：

$ wget https://phar.phpunit.de/phpunit.phar
$ php phpunit.phar --version
PHPUnit x.y.z by Sebastian Bergmann and contributors.

Windows

整体上说，在 Windows 下安装 PHAR 和手工在 Windows 下安装 Composer 是一样的过程：

为 PHP 的二进制可执行文件建立一个目录，例如 C:\bin
将 ;C:\bin 附加到 PATH 环境变量中（相关帮助）
下载 https://phar.phpunit.de/phpunit.phar 并将文件保存到 C:\bin\phpunit.phar
打开命令行（例如，按 Windows+R » 输入 cmd » ENTER)

建立外包覆批处理脚本（最后得到 C:\bin\phpunit.cmd）：

C:\Users\username> cd C:\bin
C:\bin> echo @php "%~dp0phpunit.phar" %* > phpunit.cmd
C:\bin> exit

新开一个命令行窗口，确认一下可以在任意路径下执行 PHPUnit：

C:\Users\username> phpunit --version
PHPUnit x.y.z by Sebastian Bergmann and contributors.

对于 Cygwin 或 MingW32 (例如 TortoiseGit) shell 环境，可以跳过第五步。取而代之的是，把文件保存为 phpunit （没有 .phar 扩展名），然后用 chmod 775 phpunit 将其设为可执行。

校验 PHPUnit PHAR 发行包

由 PHPUnit 项目分发的所有官方代码发行包都由发行包管理器进行签名。在 phar.phpunit.de 上有 PGP 签名和 SHA1 散列值可用于校验。

下面的例子详细说明了如何对发行包进行校验。首先下载 phpunit.phar 和与之对应的单独 PGP 签名 phpunit.phar.asc：

wget https://phar.phpunit.de/phpunit.phar
wget https://phar.phpunit.de/phpunit.phar.asc

用单独的签名(phpunit.phar)对 PHPUnit 的 PHP 档案包(phpunit.phar.asc)进行校验：

gpg phpunit.phar.asc
gpg: Signature made Sat 19 Jul 2014 01:28:02 PM CEST using RSA key ID 6372C20A
gpg: Can't check signature: public key not found

在本地系统中没有发行包管理器的公钥(6372C20A)。为了能进行校验，必须从某个密钥服务器上取得发行包管理器的公钥。其中一个服务器是 pgp.uni-mainz.de。所有密钥服务器是链接在一起的，因此连接到任一密钥服务器都可以。

gpg --keyserver pgp.uni-mainz.de --recv-keys 0x4AA394086372C20A
gpg: requesting key 6372C20A from hkp server pgp.uni-mainz.de
gpg: key 6372C20A: public key "Sebastian Bergmann <sb@sebastian-bergmann.de>" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)

现在已经取得了条目名称为"Sebastian Bergmann <sb@sebastian-bergmann.de>"的公钥。不过无法检验这个密钥确实是由名叫 Sebastian Bergmann 的人创建的。但是可以先试着校验发行包的签名：

gpg phpunit.phar.asc
gpg: Signature made Sat 19 Jul 2014 01:28:02 PM CEST using RSA key ID 6372C20A
gpg: Good signature from "Sebastian Bergmann <sb@sebastian-bergmann.de>"
gpg:                 aka "Sebastian Bergmann <sebastian@php.net>"
gpg:                 aka "Sebastian Bergmann <sebastian@thephp.cc>"
gpg:                 aka "Sebastian Bergmann <sebastian@phpunit.de>"
gpg:                 aka "Sebastian Bergmann <sebastian.bergmann@thephp.cc>"
gpg:                 aka "[jpeg image of size 40635]"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: D840 6D0D 8294 7747 2937  7831 4AA3 9408 6372 C20A

此时，签名已经没问题了，但是这个公钥还不能信任。签名没问题意味着文件未被篡改。可是由于公钥加密系统的性质，还需要再校验密钥 6372C20A 确实是由真正的 Sebastian Bergmann 创建的。

任何攻击者都能创建公钥并将其上传到公钥服务器。他们可以建立一个带恶意的发行包，并用这个假密钥进行签名。这样，如果尝试对这个损坏了的发行包进行签名校验，由于密钥是“真”密钥，校验将成功完成。因此，需要对这个密钥的真实性进行校验。如何对公钥的真实性进行校验已经超出了本文档的范畴。

有个比较谨慎的做法是创建一个脚本来管理 PHPUnit 的安装，在运行测试套件之前校验 GnuPG 签名。例如：

#!/usr/bin/env bash
clean=1 # 是否在测试完成之后删除 phpunit.phar ？
aftercmd="php phpunit.phar --bootstrap bootstrap.php src/tests"
gpg --fingerprint D8406D0D82947747293778314AA394086372C20A
if [ $? -ne 0 ]; then
    echo -e "\033[33mDownloading PGP Public Key...\033[0m"
    gpg --recv-keys D8406D0D82947747293778314AA394086372C20A
    # Sebastian Bergmann <sb@sebastian-bergmann.de>
    gpg --fingerprint D8406D0D82947747293778314AA394086372C20A
    if [ $? -ne 0 ]; then
        echo -e "\033[31mCould not download PGP public key for verification\033[0m"
        exit
    fi
fi

if [ "$clean" -eq 1 ]; then
    # 如果存在就清理掉
    if [ -f phpunit.phar ]; then
        rm -f phpunit.phar
    fi
    if [ -f phpunit.phar.asc ]; then
        rm -f phpunit.phar.asc
    fi
fi

# 抓取最新的发行版和对应的签名
if [ ! -f phpunit.phar ]; then
    wget https://phar.phpunit.de/phpunit.phar
fi
if [ ! -f phpunit.phar.asc ]; then
    wget https://phar.phpunit.de/phpunit.phar.asc
fi

# 在运行前先校验
gpg --verify phpunit.phar.asc phpunit.phar
if [ $? -eq 0 ]; then
    echo
    echo -e "\033[33mBegin Unit Testing\033[0m"
    # 运行测试套件
    `$after_cmd`
    # 清理
    if [ "$clean" -eq 1 ]; then
        echo -e "\033[32mCleaning Up!\033[0m"
        rm -f phpunit.phar
        rm -f phpunit.phar.asc
    fi
else
    echo
    chmod -x phpunit.phar
    mv phpunit.phar /tmp/bad-phpunit.phar
    mv phpunit.phar.asc /tmp/bad-phpunit.phar.asc
    echo -e "\033[31mSignature did not match! PHPUnit has been moved to /tmp/bad-phpunit.phar\033[0m"
    exit 1
fi

Composer

如果用 Composer 来管理项目的依赖关系，只要在项目的 composer.json 文件中简单地加上对 phpunit/phpunit 的依赖关系即可。下面是一个最小化的 composer.json 文件的例子，只定义了一个对 PHPUnit 5.0 的开发时(development-time)依赖：

{
    "require-dev": {
        "phpunit/phpunit": "5.0.*"
    }
}

要通过 Composer 完成系统级的安装，可以运行：

composer global require "phpunit/phpunit=5.0.*"

请确保 path 变量中包含有 ~/.composer/vendor/bin/。

可选的组件包

有以下可选组件包可用：

PHP_Invoker

一个工具类，可以用带有超时限制的方式调用可调用内容。当需要在严格模式下保证测试的超时限制时，这个组件包是必须的。

PHPUnit 的 PHAR 分发中已经包含了此组件包。若要通过 Composer 安装此组件包，添加如下 "require-dev" 依赖项：

"phpunit/php-invoker": "*"

DbUnit

移植到 PHP/PHPUnit 上的 DbUnit 用于提供对数据库交互测试的支持。

PHPUnit 的 PHAR 分发中已经包含了此组件包。若要通过 Composer 安装此组件包，添加如下 "require-dev" 依赖项：

"phpunit/dbunit": ">=1.2"

第 2 章编写 PHPUnit 测试

例 2.1展示了如何用 PHPUnit 编写测试来对 PHP 数组操作进行测试。本例介绍了用 PHPUnit 编写测试的基本惯例与步骤：

针对类 Class 的测试写在类 ClassTest中。
ClassTest（通常）继承自 PHPUnit_Framework_TestCase。
测试都是命名为 test* 的公用方法。

也可以在方法的文档注释块(docblock)中使用 @test 标注将其标记为测试方法。
在测试方法内，类似于 assertEquals()（参见附录 A）这样的断言方法用来对实际值与预期值的匹配做出断言。

例 2.1: 用 PHPUnit 测试数组操作

<?php
class StackTest extends PHPUnit_Framework_TestCase
{
    public function testPushAndPop()
    {
        $stack = array();
        $this->assertEquals(0, count($stack));

        array_push($stack, 'foo');
        $this->assertEquals('foo', $stack[count($stack)-1]);
        $this->assertEquals(1, count($stack));

        $this->assertEquals('foo', array_pop($stack));
        $this->assertEquals(0, count($stack));
    }
}
?>

	当你想把一些东西写到 `print` 语句或者调试表达式中时，别这么做，将其写成一个测试来代替。
	--Martin Fowler

测试的依赖关系

	单元测试主要是作为一种良好实践来编写的，它能帮助开发人员识别并修复 bug、重构代码，还可以看作被测软件单元的文档。要实现这些好处，理想的单元测试应当覆盖程序中所有可能的路径。一个单元测试通常覆盖一个函数或方法中的一个特定路径。但是，测试方法并不一定非要是一个封装良好的独立实体。测试方法之间经常有隐含的依赖关系暗藏在测试的实现方案中。
	--Adrian Kuhn et. al.

PHPUnit支持对测试方法之间的显式依赖关系进行声明。这种依赖关系并不是定义在测试方法的执行顺序中，而是允许生产者(producer)返回一个测试基境(fixture)的实例，并将此实例传递给依赖于它的消费者(consumer)们。

生产者(producer)，是能生成被测单元并将其作为返回值的测试方法。
消费者(consumer)，是依赖于一个或多个生产者及其返回值的测试方法。

例 2.2展示了如何用 @depends 标注来表达测试方法之间的依赖关系。

例 2.2: 用 @depends 标注来表达依赖关系

<?php
class StackTest extends PHPUnit_Framework_TestCase
{
    public function testEmpty()
    {
        $stack = array();
        $this->assertEmpty($stack);

        return $stack;
    }

    /**
     * @depends testEmpty
     */
    public function testPush(array $stack)
    {
        array_push($stack, 'foo');
        $this->assertEquals('foo', $stack[count($stack)-1]);
        $this->assertNotEmpty($stack);

        return $stack;
    }

    /**
     * @depends testPush
     */
    public function testPop(array $stack)
    {
        $this->assertEquals('foo', array_pop($stack));
        $this->assertEmpty($stack);
    }
}
?>

在上例中，第一个测试， testEmpty()，创建了一个新数组，并断言其为空。随后，此测试将此基境作为结果返回。第二个测试，testPush()，依赖于 testEmpty() ，并将所依赖的测试之结果作为参数传入。最后，testPop() 依赖于 testPush()。

注意

默认情况下，生产者所产生的返回值将“原样”传递给相应的消费者。这意味着，如果生产者返回的是一个对象，那么传递给消费者的将是一个指向此对象的引用。如果需要传递对象的副本而非引用，则应当用 @depends clone 替代 @depends。

为了快速定位缺陷，我们希望把注意力集中于相关的失败测试上。这就是为什么当某个测试所依赖的测试失败时，PHPUnit 会跳过这个测试。通过利用测试之间的依赖关系，缺陷定位得到了改进，如例 2.3中所示。

例 2.3: 利用测试之间的依赖关系

<?php
class DependencyFailureTest extends PHPUnit_Framework_TestCase
{
    public function testOne()
    {
        $this->assertTrue(FALSE);
    }

    /**
     * @depends testOne
     */
    public function testTwo()
    {
    }
}
?>

phpunit --verbose DependencyFailureTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

FS

Time: 0 seconds, Memory: 5.00Mb

There was 1 failure:

1) DependencyFailureTest::testOne
Failed asserting that false is true.

/home/sb/DependencyFailureTest.php:6

There was 1 skipped test:

1) DependencyFailureTest::testTwo
This test depends on "DependencyFailureTest::testOne" to pass.


FAILURES!
Tests: 1, Assertions: 1, Failures: 1, Skipped: 1.

测试可以使用多个 @depends 标注。PHPUnit 不会更改测试的运行顺序，因此你需要自行保证某个测试所依赖的所有测试均出现于这个测试之前。

拥有多个 @depends 标注的测试，其第一个参数是第一个生产者提供的基境，第二个参数是第二个生产者提供的基境，以此类推。参见例 2.4

例 2.4: 有多重依赖的测试

<?php
class MultipleDependenciesTest extends PHPUnit_Framework_TestCase
{
    public function testProducerFirst()
    {
        $this->assertTrue(true);
        return 'first';
    }

    public function testProducerSecond()
    {
        $this->assertTrue(true);
        return 'second';
    }

    /**
     * @depends testProducerFirst
     * @depends testProducerSecond
     */
    public function testConsumer()
    {
        $this->assertEquals(
            array('first', 'second'),
            func_get_args()
        );
    }
}
?>

phpunit --verbose MultipleDependenciesTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

...

Time: 0 seconds, Memory: 3.25Mb

OK (3 tests, 3 assertions)

数据供给器

测试方法可以接受任意参数。这些参数由数据供给器方法（在例 2.5中，是 additionProvider() 方法）提供。用 @dataProvider 标注来指定使用哪个数据供给器方法。

数据供给器方法必须声明为 public，其返回值要么是一个数组，其每个元素也是数组；要么是一个实现了 Iterator 接口的对象，在对它进行迭代时每步产生一个数组。每个数组都是测试数据集的一部分，将以它的内容作为参数来调用测试方法。

例 2.5: 使用返回数组的数组的数据供给器

<?php
class DataTest extends PHPUnit_Framework_TestCase
{
    /**
     * @dataProvider additionProvider
     */
    public function testAdd($a, $b, $expected)
    {
        $this->assertEquals($expected, $a + $b);
    }

    public function additionProvider()
    {
        return array(
          array(0, 0, 0),
          array(0, 1, 1),
          array(1, 0, 1),
          array(1, 1, 3)
        );
    }
}
?>

phpunit DataTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

...F

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

1) DataTest::testAdd with data set #3 (1, 1, 3)
Failed asserting that 2 matches expected 3.

/home/sb/DataTest.php:9

FAILURES!
Tests: 4, Assertions: 4, Failures: 1.

当使用到大量数据集时，最好逐个用字符串键名对其命名，避免用默认的数字键名。这样输出信息会更加详细些，其中将包含打断测试的数据集所对应的名称。

例 2.6: 使用带有命名数据集的数据供给器

<?php
class DataTest extends PHPUnit_Framework_TestCase
{
    /**
     * @dataProvider additionProvider
     */
    public function testAdd($a, $b, $expected)
    {
        $this->assertEquals($expected, $a + $b);
    }

    public function additionProvider()
    {
        return array(
          'adding zeros' => array(0, 0, 0),
          'zero plus one' => array(0, 1, 1),
          'one plus zero' => array(1, 0, 1),
          'one plus one' => array(1, 1, 3)
        );
    }
}
?>

phpunit DataTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

...F

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

1) DataTest::testAdd with data set "one plus one" (1, 1, 3)
Failed asserting that 2 matches expected 3.

/home/sb/DataTest.php:9

FAILURES!
Tests: 4, Assertions: 4, Failures: 1.

例 2.7: 使用返回迭代器对象的数据供给器

<?php
require 'CsvFileIterator.php';

class DataTest extends PHPUnit_Framework_TestCase
{
    /**
     * @dataProvider additionProvider
     */
    public function testAdd($a, $b, $expected)
    {
        $this->assertEquals($expected, $a + $b);
    }

    public function additionProvider()
    {
        return new CsvFileIterator('data.csv');
    }
}
?>

phpunit DataTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

...F

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

1) DataTest::testAdd with data set #3 ('1', '1', '3')
Failed asserting that 2 matches expected '3'.

/home/sb/DataTest.php:11

FAILURES!
Tests: 4, Assertions: 4, Failures: 1.

例 2.8: CsvFileIterator 类

<?php
class CsvFileIterator implements Iterator {
    protected $file;
    protected $key = 0;
    protected $current;

    public function __construct($file) {
        $this->file = fopen($file, 'r');
    }

    public function __destruct() {
        fclose($this->file);
    }

    public function rewind() {
        rewind($this->file);
        $this->current = fgetcsv($this->file);
        $this->key = 0;
    }

    public function valid() {
        return !feof($this->file);
    }

    public function key() {
        return $this->key;
    }

    public function current() {
        return $this->current;
    }

    public function next() {
        $this->current = fgetcsv($this->file);
        $this->key++;
    }
}
?>

如果测试同时从 @dataProvider 方法和一个或多个 @depends 测试接收数据，那么来自于数据供给器的参数将先于来自所依赖的测试的。来自于所依赖的测试的参数对于每个数据集都是一样的。参见例 2.9

例 2.9: 在同一个测试中组合使用 @depends 和 @dataProvider

<?php
class DependencyAndDataProviderComboTest extends PHPUnit_Framework_TestCase
{
    public function provider()
    {
        return array(array('provider1'), array('provider2'));
    }

    public function testProducerFirst()
    {
        $this->assertTrue(true);
        return 'first';
    }

    public function testProducerSecond()
    {
        $this->assertTrue(true);
        return 'second';
    }

    /**
     * @depends testProducerFirst
     * @depends testProducerSecond
     * @dataProvider provider
     */
    public function testConsumer()
    {
        $this->assertEquals(
            array('provider1', 'first', 'second'),
            func_get_args()
        );
    }
}
?>

phpunit --verbose DependencyAndDataProviderComboTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

...F

Time: 0 seconds, Memory: 3.50Mb

There was 1 failure:

1) DependencyAndDataProviderComboTest::testConsumer with data set #1 ('provider2')
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
Array (
-    0 => 'provider1'
+    0 => 'provider2'
1 => 'first'
2 => 'second'
)

/home/sb/DependencyAndDataProviderComboTest.php:31

FAILURES!
Tests: 4, Assertions: 4, Failures: 1.

注意

如果一个测试依赖于另外一个使用了数据供给器的测试，仅当被依赖的测试至少能在一组数据上成功时，依赖于它的测试才会运行。使用了数据供给器的测试，其运行结果是无法注入到依赖于此测试的其他测试中的。

注意

所有的数据供给器方法的执行都是在对 setUpBeforeClass 静态方法的调用和第一次对 setUp 方法的调用之前完成的。因此，无法在数据供给器中使用创建于这两个方法内的变量。这是必须的，这样 PHPUnit 才能计算测试的总数量。

对异常进行测试

例 2.10展示了如何用 @expectedException 标注来测试被测代码中是否抛出了异常。

例 2.10: 使用 @expectedException 标注

<?php
class ExceptionTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException InvalidArgumentException
     */
    public function testException()
    {
    }
}
?>

phpunit ExceptionTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 4.75Mb

There was 1 failure:

1) ExceptionTest::testException
Expected exception InvalidArgumentException


FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

另外，你可以将 @expectedExceptionMessage、@expectedExceptionMessageRegExp 和 @expectedExceptionCode 与 @expectedException 联合使用，来对异常的讯息与代号进行测试，如例 2.11所示。

例 2.11: 使用 @expectedExceptionMessage、@expectedExceptionMessageRegExp 和 @expectedExceptionCode 标注

<?php
class ExceptionTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException        InvalidArgumentException
     * @expectedExceptionMessage Right Message
     */
    public function testExceptionHasRightMessage()
    {
        throw new InvalidArgumentException('Some Message', 10);
    }

    /**
     * @expectedException              InvalidArgumentException
     * @expectedExceptionMessageRegExp #Right.*#
     */
    public function testExceptionMessageMatchesRegExp()
    {
        throw new InvalidArgumentException('Some Message', 10);
    }

    /**
     * @expectedException     InvalidArgumentException
     * @expectedExceptionCode 20
     */
    public function testExceptionHasRightCode()
    {
        throw new InvalidArgumentException('Some Message', 10);
    }
}
?>

phpunit ExceptionTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

FFF

Time: 0 seconds, Memory: 3.00Mb

There were 3 failures:

1) ExceptionTest::testExceptionHasRightMessage
Failed asserting that exception message 'Some Message' contains 'Right Message'.

2) ExceptionTest::testExceptionMessageMatchesRegExp
Failed asserting that exception message 'Some Message' matches '#Right.*#'.

3) ExceptionTest::testExceptionHasRightCode
Failed asserting that expected exception code 20 is equal to 10.


FAILURES!
Tests: 3, Assertions: 6, Failures: 3.

关于 @expectedExceptionMessage、@expectedExceptionMessageRegExp 和 @expectedExceptionCode，分别在“@expectedExceptionMessage”一节、“@expectedExceptionMessageRegExp”一节和 “@expectedExceptionCode”一节有更多相关范例。

此外，还可以用 setExpectedException() 或 setExpectedExceptionRegExp() 方法来设定所预期的异常，如例 2.12所示。

例 2.12: 预期被测代码将引发异常

<?php
class ExceptionTest extends PHPUnit_Framework_TestCase
{
    public function testException()
    {
        $this->setExpectedException('InvalidArgumentException');
    }

    public function testExceptionHasRightMessage()
    {
        $this->setExpectedException(
          'InvalidArgumentException', 'Right Message'
        );
        throw new InvalidArgumentException('Some Message', 10);
    }

    public function testExceptionMessageMatchesRegExp()
    {
        $this->setExpectedExceptionRegExp(
          'InvalidArgumentException', '/Right.*/', 10
        );
        throw new InvalidArgumentException('The Wrong Message', 10);
    }

    public function testExceptionHasRightCode()
    {
        $this->setExpectedException(
          'InvalidArgumentException', 'Right Message', 20
        );
        throw new InvalidArgumentException('The Right Message', 10);
    }
}
?>

phpunit ExceptionTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

FFFF

Time: 0 seconds, Memory: 3.00Mb

There were 4 failures:

1) ExceptionTest::testException
Expected exception InvalidArgumentException

2) ExceptionTest::testExceptionHasRightMessage
Failed asserting that exception message 'Some Message' contains 'Right Message'.

3) ExceptionTest::testExceptionMessageMatchesRegExp
Failed asserting that exception message 'The Wrong Message' contains '/Right.*/'.

4) ExceptionTest::testExceptionHasRightCode
Failed asserting that expected exception code 20 is equal to 10.


FAILURES!
Tests: 4, Assertions: 8, Failures: 4.

表 2.1中列举了用于对异常进行测试的各种方法。

表 2.1. 用于对异常进行测试的方法

方法	含义
`void setExpectedException(string $exceptionName[, string $exceptionMessage = '', integer $exceptionCode = NULL])`	设定预期的 `$exceptionName`、`$exceptionMessage` 和 `$exceptionCode`。
`void setExpectedExceptionRegExp(string $exceptionName[, string $exceptionMessageRegExp = '', integer $exceptionCode = NULL])`	设定预期的 `$exceptionName`、`$exceptionMessageRegExp` 和 `$exceptionCode`。
`String getExpectedException()`	返回预期异常的名称。

可以用例 2.13 中所示方法来对异常进行测试。

例 2.13: 另一种对异常进行测试的方法

<?php
class ExceptionTest extends PHPUnit_Framework_TestCase {
    public function testException() {
        try {
            // ... 预期会引发异常的代码 ...
        }

        catch (InvalidArgumentException $expected) {
            return;
        }

        $this->fail('预期的异常未出现。');
    }
}
?>

当例 2.13 中预期会引发异常的代码并没有引发异常时，后面对 fail() 的调用将会中止测试，并通告测试有问题。如果预期的异常出现了，将执行 catch 代码块，测试将会成功结束。

对 PHP 错误进行测试

默认情况下，PHPUnit 将测试在执行中触发的 PHP 错误、警告、通知都转换为异常。利用这些异常，就可以，比如说，预期测试将触发 PHP 错误，如例 2.14所示。

注意

PHP 的 error_reporting 运行时配置会对 PHPUnit 将哪些错误转换为异常有所限制。如果在这个特性上碰到问题，请确认 PHP 的配置中没有抑制想要测试的错误类型。

例 2.14: 用 @expectedException 来预期 PHP 错误

<?php
class ExpectedErrorTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException PHPUnit_Framework_Error
     */
    public function testFailingInclude()
    {
        include 'not_existing_file.php';
    }
}
?>

phpunit -d error_reporting=2 ExpectedErrorTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

.

Time: 0 seconds, Memory: 5.25Mb

OK (1 test, 1 assertion)

PHPUnit_Framework_Error_Notice 和 PHPUnit_Framework_Error_Warning 分别代表 PHP 通知与 PHP 警告。

注意

对异常进行测试是越明确越好的。对太笼统的类进行测试有可能导致不良副作用。因此，不再允许用 @expectedException 或 setExpectedException() 对 Exception 类进行测试。

如果测试依靠会触发错误的 PHP 函数，例如 fopen ，有时候在测试中使用错误抑制符会很有用。通过抑制住错误通知，就能对返回值进行检查，否则错误通知将会导致抛出 PHPUnit_Framework_Error_Notice。

例 2.15: 对会引发PHP 错误的代码的返回值进行测试

<?php
class ErrorSuppressionTest extends PHPUnit_Framework_TestCase
{
    public function testFileWriting() {
        $writer = new FileWriter;
        $this->assertFalse(@$writer->write('/is-not-writeable/file', 'stuff'));
    }
}
class FileWriter
{
    public function write($file, $content) {
        $file = fopen($file, 'w');
        if($file == false) {
            return false;
        }
        // ...
    }
}

?>

phpunit ErrorSuppressionTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

.

Time: 1 seconds, Memory: 5.25Mb

OK (1 test, 1 assertion)

如果不使用错误抑制符，此测试将会失败，并报告 fopen(/is-not-writeable/file): failed to open stream: No such file or directory。

对输出进行测试

有时候，想要断言（比如说）某方法的运行过程中生成了预期的输出（例如，通过 echo 或 print）。PHPUnit_Framework_TestCase 类使用 PHP 的输出缓冲特性来为此提供必要的功能支持。

例 2.16展示了如何用 expectOutputString() 方法来设定所预期的输出。如果没有产生预期的输出，测试将计为失败。

例 2.16: 对函数或方法的输出进行测试

<?php
class OutputTest extends PHPUnit_Framework_TestCase
{
    public function testExpectFooActualFoo()
    {
        $this->expectOutputString('foo');
        print 'foo';
    }

    public function testExpectBarActualBaz()
    {
        $this->expectOutputString('bar');
        print 'baz';
    }
}
?>

phpunit OutputTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

.F

Time: 0 seconds, Memory: 5.75Mb

There was 1 failure:

1) OutputTest::testExpectBarActualBaz
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'bar'
+'baz'


FAILURES!
Tests: 2, Assertions: 2, Failures: 1.

表 2.2中列举了用于对输出进行测试的各种方法。

表 2.2. 用于对输出进行测试的方法

方法	含义
`void expectOutputRegex(string $regularExpression)`	设置输出预期为输出应当匹配正则表达式 `$regularExpression`。
`void expectOutputString(string $expectedString)`	设置输出预期为输出应当与 `$expectedString` 字符串相等。
`bool setOutputCallback(callable $callback)`	设置回调函数，用来做诸如将实际输出规范化之类的动作。

注意

在严格模式下，本身产生输出的测试将会失败。

错误相关信息的输出

当有测试失败时，PHPUnit 全力提供尽可能多的有助于找出问题所在的上下文信息。

例 2.17: 数组比较失败时生成的错误相关信息输出

<?php
class ArrayDiffTest extends PHPUnit_Framework_TestCase
{
    public function testEquality() {
        $this->assertEquals(
            array(1,2,3 ,4,5,6),
            array(1,2,33,4,5,6)
        );
    }
}
?>

phpunit ArrayDiffTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

1) ArrayDiffTest::testEquality
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
     0 => 1
     1 => 2
-    2 => 3
+    2 => 33
     3 => 4
     4 => 5
     5 => 6
 )

/home/sb/ArrayDiffTest.php:7

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

在这个例子中，数组中只有一个值不同，但其他值也都同时显示出来，以提供关于错误发生的位置的上下文信息。

当生成的输出很长而难以阅读时，PHPUnit 将对其进行分割，并在每个差异附近提供少数几行上下文信息。

例 2.18: 长数组比较失败时生成的错误相关信息输出

<?php
class LongArrayDiffTest extends PHPUnit_Framework_TestCase
{
    public function testEquality() {
        $this->assertEquals(
            array(0,0,0,0,0,0,0,0,0,0,0,0,1,2,3 ,4,5,6),
            array(0,0,0,0,0,0,0,0,0,0,0,0,1,2,33,4,5,6)
        );
    }
}
?>

phpunit LongArrayDiffTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

1) LongArrayDiffTest::testEquality
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
     13 => 2
-    14 => 3
+    14 => 33
     15 => 4
     16 => 5
     17 => 6
 )


/home/sb/LongArrayDiffTest.php:7

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

边缘情况

当比较失败时，PHPUnit 为输入值建立文本表示，然后以此进行对比。这种实现导致在差异指示中显示出来的问题可能比实际上存在的多。

这种情况只出现在对数组或者对象使用 assertEquals 或其他“弱”比较函数时。

例 2.19: 当使用弱比较时在生成的差异结果中出现的边缘情况

<?php
class ArrayWeakComparisonTest extends PHPUnit_Framework_TestCase
{
    public function testEquality() {
        $this->assertEquals(
            array(1  ,2,3 ,4,5,6),
            array('1',2,33,4,5,6)
        );
    }
}
?>

phpunit ArrayWeakComparisonTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

F

Time: 0 seconds, Memory: 5.25Mb

There was 1 failure:

1) ArrayWeakComparisonTest::testEquality
Failed asserting that two arrays are equal.
--- Expected
+++ Actual
@@ @@
 Array (
-    0 => 1
+    0 => '1'
     1 => 2
-    2 => 3
+    2 => 33
     3 => 4
     4 => 5
     5 => 6
 )


/home/sb/ArrayWeakComparisonTest.php:7

FAILURES!
Tests: 1, Assertions: 1, Failures: 1.

在这个例子中，第一个索引项中的 1 and '1' 在报告中被视为不同，虽然 assertEquals 认为这两个值是匹配的。

第 3 章命令行测试执行器

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

phpunit ArrayTest
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

..

Time: 0 seconds


OK (2 tests, 2 assertions)

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

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

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

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

命令行选项

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

phpunit --help
PHPUnit 5.0.0 by Sebastian Bergmann and contributors.

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.

Logging Options:

  --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.
  --testdox-html <file>     Write agile documentation in HTML format to file.
  --testdox-text <file>     Write agile documentation in Text format to file.

Test Selection Options:

  --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

Test Execution Options:

  --report-useless-tests    Be strict about tests that do not test anything.
  --strict-coverage         Be strict about unintentionally covered code.
  --strict-global-state     Be strict about changes to global state
  --disallow-test-output    Be strict about output during tests.
  --enforce-time-limit      Enforce time limit based on test size.
  --disallow-todo-tests     Disallow @todo-annotated tests.

  --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.

  --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-error           Stop execution upon first error.
  --stop-on-failure         Stop execution upon first error or failure.
  --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.
  -v|--verbose              Output more verbose information.
  --debug                   Display debugging information during test execution.

  --loader <loader>         TestSuiteLoader 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.
  --printer <printer>       TestListener implementation to use.

Configuration Options:

  --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.

Miscellaneous Options:

  -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 类提供的测试。这个类应当在指定的源文件中声明。

--coverage-clover

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