PHPUnit Manual

ほとんどの場合、PHPUnit を使用する際には以下の 5 つのクラスやインターフェイスに出会うことになるでしょう。

PHPUnit の、5 つの基本クラス/インターフェイスである PHPUnit_Framework_Assert、 PHPUnit_Framework_Test、 PHPUnit_Framework_TestCase、 PHPUnit_Framework_TestSuite およびand PHPUnit_Framework_TestResult の関係を 図 21.1 に示します。

図21.1 PHPUnit の 5 つの基本クラス/インターフェイス

PHPUnit 用に書かれたテストケースのほとんどは、間接的に PHPUnit_Framework_Assert を継承しています。ここには、 値を自動的にチェックして矛盾を報告するためのメソッドが含まれています。 これらのメソッドは静的に宣言されているので、 あなたが作成したメソッドの中で「規約による設計」方式のアサーションを使用し、 PHPUnit に結果を報告させることができます (例 21.1 を参照ください)。

<?php
require_once 'PHPUnit/Framework.php';
 
class Sample
{
    public function aSampleMethod($object)
    {
        PHPUnit_Framework_Assert::assertNotNull($object);
    }
}
 
$sample = new Sample;
$sample->aSampleMethod(NULL);
?>

Fatal error: Uncaught exception 'PHPUnit_Framework_ExpectationFailedException'
with message 'Failed asserting that <null> is not identical to <null>'.

しかし、ほとんどの場合はこれらのアサーションはテストの中で行います。

各アサーションメソッドには 2 種類の方式があります。 エラー時に表示されるメッセージをパラメータとして指定する方法としない方法です。 オプションで指定したメッセージは、通常はテストが失敗したことが報告される場面で 表示されます。これにより、デバッグが楽になります。

<?php
require_once 'PHPUnit/Framework.php';
 
class MessageTest extends PHPUnit_Framework_TestCase
{
    public function testMessage()
    {
        $this->assertTrue(FALSE, 'これは独自のメッセージです。');
    }
}
?>

以下の例は、 例 21.2 のテスト testMessage() でメッセージつきのアサーションを使用した場合の出力結果です。

phpunit MessageTest
PHPUnit 3.2.10 by Sebastian Bergmann.

F

Time: 0 seconds

There was 1 failure:

1) testMessage(MessageTest)
これは独自のメッセージです。
Failed asserting that <boolean:false> is true.
/home/sb/MessageTest.php:8

FAILURES!
Tests: 1, Failures: 1.

表 21.1 に、すべてのアサーションをまとめます。

もっと複雑なアサーションを行う場合には、 PHPUnit_Framework_Constraint クラスを使用します。 これらは、assertThat() メソッドを使用して 例 21.3 のように評価されます。

<?php
require_once 'PHPUnit/Framework.php';
 
class ConstraintTest extends PHPUnit_Framework_TestCase
{
    public function testNotEquals()
    {
        $constraint = $this->logicalNot(
          $this->equalTo('foo')
        );
 
        $this->assertThat('foo', $constraint);
    }
}
?>

phpunit ConstraintTest
PHPUnit 3.2.10 by Sebastian Bergmann.

F

Time: 0 seconds

There was 1 failure:

1) testNotEquals(ConstraintTest)
Failed asserting that <string:foo> is not equal to <string:foo>.
/home/sb/ConstraintTest.php:12

FAILURES!
Tests: 1, Failures: 1.

表 21.2 に、 使用できる PHPUnit_Framework_Constraint の実装をまとめます。

これら以外に、プロジェクトで使用している オブジェクト固有のアサーションが必要になることもあるでしょう。独自の Assert クラスを作成し、 そこに独自のアサーションを含めてテストに使用することができます。

アサーションに失敗すると、ボトルネックメソッド fail(string $message) がコールされ、これは PHPUnit_Framework_AssertionFailedError をスローします。 このメソッドにもパラメータなしのものがあります。テストでエラーが発生した際に、 fail() を明示的にコールします。 例外が発生することが期待されるテストなどがその例になります。 表 21.3 に、PHPUnit のボトルネックメソッドをまとめます。

markTestIncomplete() および markTestSkipped() は、テストに対して「未完了」あるいは「省略」の印をつけるために便利なメソッドです。

単体テストとは、もともとクラスの公開インターフェイスをテストするものです。 しかし、時には非公開の属性の内容をテストしたいこともあるでしょう。 readAttribute() メソッドを使用すると、 指定したオブジェクトの属性の値を取得することができます。

PHPUnit_Framework_Test は、 テストとして働くすべてのオブジェクトが使用する、 一般的なインターフェイスです。これを実装したオブジェクトは、 ひとつあるいは複数のテストを表すことになります。 表 21.6 に示す 2 つのメソッドが定義されています。

PHPUnit_Framework_Test の実装クラスとして有名なのは、 PHPUnit_Framework_TestCase および PHPUnit_Framework_TestSuite の 2 つです。 PHPUnit_Framework_Test を実装したクラスを独自に作成することも可能です。 このインターフェイスはあえて小規模に設計されているので、実装するのは簡単でしょう。

テストケースクラスは PHPUnit_Framework_TestCase クラスを継承して作成します。たいていの場合は、 テストスイートから自動的にテストを実行させることになるでしょう。 この場合、(規約により) 各テストは test* という名前のメソッドにしておかなければなりません。

PHPUnit_Framework_TestCase は PHPUnit_Framework_Test::countTestCases() を実装しており、 これは常に 1 を返します。このクラスで実装されている PHPUnit_Framework_Test::run(PHPUnit_Framework_TestResult $result) は、まず setUp() を実行し、テストメソッドを実行し、 それから tearDown() を実行し、その結果を PHPUnit_Framework_TestResult に報告します。

PHPUnit_Framework_TestCase によって実装されているメソッドを 表 21.7 にまとめます。

このクラスには、ふたつのテンプレートメソッド setUp() および tearDown() が存在します。これをオーバーライドすると、 実行しようとしているテストに関する前処理や後始末を行うことができます。 表 21.8 にこれらのメソッドをまとめます。 テンプレートメソッド assertPreConditions() および assertPostConditions() を使用すると、 テストケースクラス内のすべてのテストで実行するアサーションを定義することができます。

PHPUnit_Framework_TestSuite は複数の PHPUnit_Framework_Test を組み合わせたものです。 簡単に言うと、このクラスには複数のテストケースが含まれており、 テストスイートを実行するとそれらの全てのテストが実行されます。 テストスイートは composite なので、テストスイートの中に別のテストスイートを含め、 さらにそのテストスイートの中には別のテストスイートが含まれており…… といったことも可能です。これにより、 いろいろなところから集めたテストをひとまとめにすることが簡単になります。

run(PHPUnit_Framework_TestResult $result) および countTestCases() の 2 つに加え、 PHPUnit_Framework_TestSuite は名前つきインスタンス、 名前なしインスタンスを作成するためのメソッドも用意しています。 PHPUnit_Framework_TestSuite のインスタンスを作成するためのメソッドを 表 21.9 に示します。

PHPUnit_Framework_TestSuite には、 PHPUnit_Framework_Test を追加したり取得したりするためのメソッドも用意されています。これを 表 21.10 にまとめます。

例 21.4 に、テストスイートを作成して実行する方法を示します。

<?php
require_once 'PHPUnit/Framework.php';
 
require_once 'ArrayTest.php';
 
// ArrayTest クラスのテストを含む
// テストスイートを作成します。
$suite = new PHPUnit_Framework_TestSuite('ArrayTest');
 
// テストを実行します。
$suite->run();
?>

第 7 章 では、 PHPUnit_Framework_TestSuite クラスを使用して 階層化されたテストケースを組み合わせる例を示します。

PHPUnit_Framework_TestSuite クラスには、 ふたつのテンプレートメソッド setUp() および tearDown() が存在します。 これらはそれぞれ、テストスイートのテストが実行される前と後にコールされます。

これらのテストを実行している間は、実行したテストの数・失敗したテスト・ テストの所要時間などをどこかに保存しておかなければなりません。 これらの結果を収集するのが PHPUnit_Framework_TestResult です。ひとつの PHPUnit_Framework_TestResult が、 テスト全体で使いまわされます。テストの実行結果や失敗の内容は PHPUnit_Framework_TestResult に記録されていき、 実行が終了すると、PHPUnit_Framework_TestResult には全てのテストの概要が含まれるようになります。

PHPUnit_Framework_TestResult は、 テストの進行状況を知りたい他のオブジェクトから参照されることもあります。 例えば、グラフィカルなテストランナーは PHPUnit_Framework_TestResult を監視し、各テストの開始時にプログレスバーを更新するでしょう。

表 21.12 は、 PHPUnit_Framework_TestResult の API をまとめたものです。

PHPUnit_Framework_TestResult のオブザーバを登録したい場合は、PHPUnit_Framework_TestListener を実装する必要があります。これを登録するには、 表 21.13 に示した addListener() を使用します。

表 21.14 に、テストリスナーが実装するメソッドを示します。 例 22.3 も参照ください。

この本で取り上げたクラスの多くは PHPUnit/Framework にあるものです。ここには PHPUnit のすべてのパッケージが含まれています。