PHPUnit マニュアル

setUp() と tearDown() は理屈上では対称的になるはずですが、実際にはそうではありません。実際には、 tearDown() を実装する必要があるのは setUp() で外部リソース (ファイルやソケットなど) を割り当てた場合のみです。もし setUp() で単に PHP オブジェクトを作成しただけの場合は、 一般には tearDown() は必要ありません。しかし、もし setUp() で大量のオブジェクトを作成した場合には、 それらの後始末をするために tearDown() で変数を unset() したくなることもあるでしょう。 テストケースオブジェクト自体のガベージコレクションにはあまり意味がありません。

ふたつのテストがあって、それぞれの setup がほんの少しだけ違う場合にはどうなるでしょう? このような場合は、二種類の可能性が考えられます。

PHPUnit には、スイートレベルでの設定をするための便利な方法はありません。 複数のテストの間で fixture を共有したいなんてことは、通常はめったにないはずです。 しかし、設計上の問題などでどうしても fixture を共有しなければならないこともあるでしょう。

複数のテスト間で共有する意味のある fixture の例として意味のあるものといえば、 データベースとの接続でしょう。テストのたびに新しいデータベース接続を毎回作成するのではなく、 最初にログインした状態を再利用するということです。こうすることで、 テストの実行時間を短縮できます。これを行うには、データベースに関するテストを DatabaseTests という名前のクラスに書き、デコレータ (decorator) オブジェクト TestSetup でテストスイートをラップします。オーバーライドした setUp() でデータベース接続をオープンし、 tearDown() で接続を閉じるようにします。この例を 例 7.2 に示します。DatabaseTestSetup デコレータを起動することで、 DatabaseTests のテストを行うことができます。例えば、 PHPUnit のコマンドライン版テストランナーでは phpunit DatabaseTestSetup とします。

<?php
require_once 'PHPUnit/Framework.php';
require_once 'PHPUnit/Extensions/TestSetup.php';
 
class DatabaseTestSetup extends PHPUnit_Extensions_TestSetup
{
    protected $connection = NULL;
 
    protected function setUp()
    {
        $this->connection = new PDO(
          'mysql:host=wopr;dbname=test',
          'root',
          ''
        );
    }
 
    protected function tearDown()
    {
        $this->connection = NULL;
    }
 
    public static function suite()
    {
        return new DatabaseTestSetup(
          new PHPUnit_Framework_TestSuite('DatabaseTests')
        );
    }
}
?>

このように fixture を共有することがテストの価値を下げてしまうということを、 まだうまく伝え切れていないかもしれません。問題なのは、 各オブジェクトが疎結合になっていないという設計なのです。 複数が連携しているようなテストを作って設計上の問題から目をそらしてしまうのではなく、 きちんと設計しなおした上で、スタブ (第 10 章 を参照ください) を使用するテストを書くことをお勧めします。

PHPUnit_Extensions_ExceptionTestCase を継承したテストクラスを作成し、 テストコードの内部で例外がスローされたかどうかを調べることもできます。 例 8.1 では、PHPUnit_Extensions_ExceptionTestCase のサブクラスを作成し、テストしたい例外をその setExpectedException() メソッドに設定する方法を示します。期待した例外がスローされなかった場合は、 そのテストは失敗という扱いになります。

<?php
require_once 'PHPUnit/Extensions/ExceptionTestCase.php';
 
class ExceptionTest extends PHPUnit_Extensions_ExceptionTestCase
{
    public function testException()
    {
        $this->setExpectedException('Exception');
    }
}
?>

phpunit ExceptionTest
PHPUnit 3.0.0 by Sebastian Bergmann.

F

Time: 00:00
There was 1 failure:
1) testException(ExceptionTest)
Expected exception Exception

FAILURES!
Tests: 1, Failures: 1.

表 8.1 は、PHPUnit_Extensions_ExceptionTestCase が実装しているメソッドをまとめたものです。

一方、 例 8.2 のような方法で例外をテストすることもできます。

<?php
require_once 'PHPUnit/Framework.php';
 
class ExceptionTest extends PHPUnit_Framework_TestCase {
    public function testException() {
        try {
            // ... 例外が発生するであろうコード ...
        }
 
        catch (Exception $expected) {
            return;
        }
 
        $this->fail('期待通りの例外が発生しませんでした。');
    }
}
?>

例外が発生するはずの 例 8.2 のコードで例外が発生しなかった場合、それに続く fail() (表 20.3 を参照ください) によってテストが終了し、問題を報告します。期待通りに例外が発生すると、 catch ブロックが実行されてテストは正常終了します。

メソッドの実行結果を確かめる方法として、(echo や print などによる) 出力が期待通りのものかを調べたいこともあるでしょう。 PHPUnit_Extensions_OutputTestCase クラスは、PHP の 出力バッファリング 機能を使用してこの仕組みを提供します。

例 8.3 では、PHPUnit_Extensions_OutputTestCase のサブクラスを作成し、期待する出力内容を expectOutputString() メソッドで設定する方法を示します。 期待通りの出力が得られなかった場合は、そのテストは失敗という扱いになります。

<?php
require_once 'PHPUnit/Extensions/OutputTestCase.php';
 
class OutputTest extends PHPUnit_Extensions_OutputTestCase
{
    public function testExpectFooActualFoo()
    {
        $this->expectOutputString('foo');
        print 'foo';
    }
 
    public function testExpectFooActualBar()
    {
        $this->expectOutputString('foo');
        print 'bar';
    }
}
?>

phpunit OutputTest
PHPUnit 3.0.0 by Sebastian Bergmann.

.F

Time: 00:00

There was 1 failure:

1) testExpectFooActualBar(OutputTest)
Failed asserting that <string:bar> is equal to <string:foo>.

FAILURES!
Tests: 2, Failures: 1.

表 8.2 PHPUnit_Extensions_OutputTestCase が提供するメソッドをまとめたものです。

PHPUnit_Extensions_PerformanceTestCase を継承したテストクラスを使用すると、 関数やメソッドの実行が制限時間内に終わったかどうかなどをテストすることができます。

PHPUnit_Extensions_PerformanceTestCase のサブクラスを作成してその setMaxRunningTime() メソッドを使用し、実行時間の最大値を制限する方法を 例 8.4 で示します。 もしテストが制限時間内に終了しなければ、そのテストは失敗という扱いになります。

<?php
require_once 'PHPUnit/Extensions/PerformanceTestCase.php';
 
class PerformanceTest extends PHPUnit_Extensions_PerformanceTestCase
{
    public function testPerformance()
    {
        $this->setMaxRunningTime(2);
        sleep(1);
    }
}
?>

表 8.3 は、PHPUnit_Extensions_PerformanceTestCase が実装しているメソッドをまとめたものです。

新しいテストケースクラスを作成する際には、 これから書くべきテストの内容をはっきりさせるために、 まず最初は以下のような空のテストメソッドを書きたくなることでしょう。

public function testSomething()
{
}

しかし、PHPUnit フレームワークでは空のメソッドを「成功した」 と判断してしまうという問題があります。このような解釈ミスがあると、 テスト結果のレポートが無意味になってしまいます。 そのテストがほんとうに成功したのか、 それともまだテストが実装されていないのかが判断できないからです。 実装していないテストメソッドの中で $this->fail() をコールするようにしたところで事態は何も変わりません。 こうすると、テストが「失敗した」と判断されてしまいます。 これは未実装のテストが「成功」と判断されてしまうのと同じくらいまずいことです (訳注: レポートを見ても、そのテストがほんとうに失敗したのか、 まだ実装されていないだけなのかがわかりません)。

テストの成功を青信号、失敗を赤信号と考えるなら、 テストが未完成あるいは未実装であることを表すための黄信号が必要です。 そのような場合に使用するインターフェイスが PHPUnit_Framework_IncompleteTest で、 これは未完成あるいは未実装のテストメソッドで発生する例外を表すものです。 このインターフェイスの標準的な実装が PHPUnit_Framework_IncompleteTestError です。

例 9.1 では SampleTest というテストケースクラスを定義しています。 便利なメソッド markTestIncomplete() (これは、自動的に PHPUnit_Framework_IncompleteTestError を発生させます) をテストメソッド内でコールすることで、 このメソッドがまだ完成していないことをはっきりさせます。

<?php
require_once 'PHPUnit/Framework.php';
 
class SampleTest extends PHPUnit_Framework_TestCase
{
    public function testSomething()
    {
        // オプション: お望みなら、ここで何かのテストをしてください。
        $this->assertTrue(TRUE, 'This should already work.');
 
        // ここで処理を止め、テストが未完成であるという印をつけます。
        $this->markTestIncomplete(
          'このテストは、まだ実装されていません。'
        );
    }
}
?>

未完成のテストは、PHPUnit のコマンドライン版テストランナーでは以下のように I で表されます。

phpunit --verbose SampleTest
PHPUnit 3.0.0 by Sebastian Bergmann.

I

Time: 00:00
There was 1 incomplete test:
1) testSomething(SampleTest)
This test has not been implemented yet.
/home/sb/SampleTest.php:12

OK, but incomplete or skipped tests!
Tests: 1, Incomplete: 1.

表 9.1 に、テストを未完成扱いにするための API を示します。

すべてのテストがあらゆる環境で実行できるわけではありません。 考えてみましょう。たとえば、データベースの抽象化レイヤーを使用しており、 それがさまざまなドライバを使用してさまざまなデータベースシステムを サポートしているとします。MySQL ドライバのテストができるのは、 当然 MySQL サーバが使用できる環境だけです。

例 9.2 に示すテストケースクラス DatabaseTest には、 テストメソッド testConnection() が含まれています。 このクラスのテンプレートメソッド setUp() では、 MySQLi 拡張モジュールが使用可能かを調べたうえで、もし使用できない場合は markTestSkipped() メソッドでテストを省略するようにしています。

<?php
require_once 'PHPUnit/Framework.php';
 
class DatabaseTest extends PHPUnit_Framework_TestCase
{
    protected function setUp()
    {
        if (!extension_loaded('mysqli')) {
            $this->markTestSkipped(
              'MySQLi 拡張モジュールが使用できません。'
            );
        }
    }
 
    public function testConnection()
    {
        // ...
    }
}
?>

飛ばされたテストは、PHPUnit のコマンドライン版テストランナーでは以下のように S で表されます。

phpunit --verbose DatabaseTest
PHPUnit 3.0.0 by Sebastian Bergmann.

S

Time: 00:00
There was 1 skipped test:
1) testConnection(DatabaseTest)
The MySQLi extension is not available.
/home/sb/DatabaseTest.php:9

OK, but incomplete or skipped tests!
Tests: 1, Skipped: 1.

表 9.2 に、テストを省略するための API を示します。

あるいは、Subject の実装をテストする際に モックオブジェクトを使用せずに 自己シャント (Self Shunt) パターン を適用する方法もあります。 これは、テストケース自身をスタブとして使用します。 自己シャントというのは医学用語で、薬を注入する場所を確保するため、 チューブを挿入して動脈からとった血液を静脈にもどすことを意味します。

まず、Observer を実装したテストケースクラスを作成します。 Observer は、Subject を観察したいオブジェクトが実装しなければならないインターフェイスです。

class ObserverTest extends PHPUnit_Framework_TestCase implements Observer
{
}

次に、Observer のメソッドである update() を実装します。そして、観察対象のオブジェクトである Subject の状態が変化した場合にそのメソッドが正しくコールされるかどうかを調べます。

public $wasCalled = FALSE;

public function update(Subject $subject)
{
  $this->wasCalled = TRUE;
}

さあ、それではテストを書いてみましょう。まず新しい Subject オブジェクトを作成し、テストオブジェクトをオブザーバとしてアタッチします。 Subject の状態が変化すると (例えば doSomething() メソッドがコールされるなど)、Subject オブジェクトは全オブザーバの update() メソッドをコールしなければなりません。ここではインスタンス変数 $wasCalled を使用し、update() の中でその値を設定します。これにより、Subject オブジェクトが期待通りの動作をしているかどうかを確かめます。

public function testUpdate()
{
  $subject = new Subject;
  $subject->attach($this);
  $subject->doSomething();

  $this->assertTrue($this->wasCalled);
}

グローバルなインスタンスではなく、新しい Subject オブジェクトを作成したことに注意してください。スタブを利用する際には、 このような設計をお勧めします。こうすると、 オブジェクト間の結合度が緩やかになり、再利用性が高まります。

自己シャントパターンになじみのない方には、このテストはわかりにくいかもしれません。 いったいここで何が起こっているんだ? テストケース自身がオブザーバになるだって? でも、お決まりのパターンをいったん身につけてしまえば、 これらのテストは簡単に理解できるようになります。 テストの内容をつかむために必要なことは、 すべてひとつのクラスの中に含まれているのですから。

いろいろな要因で失敗する可能性があるテストよりも、 単一の事項のみをテストするテストのほうが情報を得やすくなります。では、 できるだけ外部からの影響を受けないようなテストを作成するには どうすればいいのでしょうか? 単純なことです。 高価で面倒で頼りなくて遅くて複雑なリソースを、 テスト用に自動で生成されたスタブに置き換えればいいのです。たとえば、 複雑な計算結果を単に定数に置き換えたものを、テスト用に作成すればいいのです。

スタブを使用すると、高価な外部リソースを使用することによる問題を解決できます。 たとえばデータベース接続のようなリソースをテスト間で共有するには PHPUnit_Extensions_TestSetup デコレータを使用すればいいのですが、 テストの目的を考えると、データベースを使用せずにすむのならばそのほうがずっとよいでしょう。

例 10.2 に、スタブメソッドの作成と返り値の設定の方法を示します。

<?php
require_once 'PHPUnit/Framework.php';
 
class StubTest extends PHPUnit_Framework_TestCase
{
    public function testStub()
    {
        $stub = $this->getMock('SomeClass');
        $stub->expects($this->any())
             ->method('doSomething')
             ->will($this->returnValue('foo'));
 
        // $stub->doSomething() をコールすると、'foo' を返します。
    }
}
?>

表 10.2 は、スタブメソッドの返り値を設定する際に使用できるメソッドの一覧です。

また、スタブを使用することで、よりよい設計を行うことができるようにもなります。 あちこちで使用されているリソースを単一の窓口 (façade : ファサード) 経由でアクセスするようにすることで、 それを簡単にスタブに置き換えられるようになります。例えば、 データベースへのアクセスのコードをそこらじゅうにちりばめるのではなく、 その代わりに IDatabase インターフェイスを実装した単一の Database オブジェクトを使用するようにします。すると、 IDatabase を実装したスタブを作成することで、 それをテストに使用できるようになるのです。同時に、 テストを行う際にスタブデータベースを使用するか 本物のデータベースを使用するかを選択できるようになります。 つまり開発時にはローカル環境でテストし、 統合テスト時には実際のデータベースでテストするといったことができるようになるのです。

スタブ化しなければならない機能は、たいてい同一オブジェクト内で密結合しています。 この機能ををひとつの結合したインターフェイスにまとめることで、 システムのそれ以外の部分との結合を緩やかにすることができます。

開発中のソフトウェアの内部構造を変更し、 わかりやすく変更が簡単なものにする必要が出てきたときのことを考えましょう。 それによってソフトウェアの外部的な振る舞いが変わってしまってはいけません。 この、いわゆる リファクタリング (日本語) を安全に行うにあたり、テストスイートが非常に重要となります。 もしテストスイートがなければ、リファクタリングによってシステムを壊してしまっても あなたはそれに気づかないでしょう。

以下の条件が、あなたのプロジェクトのコードや設計を改善するための助けとなるでしょう。 また、単体テストを使用することで、リファクタリングによって振る舞いが変化していないこと・ エラーが発生していないことが確認できます。

システムに新しい機能を追加する際には、まず最初にテストを書きます。 そのテストがきちんと実行できるようになった時点で、開発は終了です。 この手法については、次の章で詳しく説明します。

不具合の報告を受けたら、すぐにでもそれを修正したいと思われることでしょう。 しかし、あせって修正しようとしても、経験上なかなかうまくいきません。 不具合を修正したつもりが新たな不具合を引き起こしていたなんてこともありがちですね。

はやる気持ちを抑えて、以下のようにしてみましょう。

不具合が再現する最小限のコードを見つける過程で、 不具合の原因がわかるかもしれません。テストを書くことによって、 不具合を真の意味で修正できる可能性が高まるでしょう。なぜなら、 テストを書くことで、将来同じ間違いをする可能性を減らせるからです。 これまでに書いたすべてのテストが、 不注意によって別の問題を発生させる可能性を減らすために役立っているのです。

この章では、銀行口座を表すクラスを例にして考えます。預金残高の取得や設定、 預け入れや引き落としなどのメソッドだけでなく、BankAccount クラスは以下のふたつの規約を満たす必要があります。

テストファーストプログラミングの手法に従い、まずは BankAccount クラスのテストを作成し、その後で実際のコードを書いていくようにしましょう。 上の規約をテスト作成の基準とし、それにしたがって 例 12.1 のようにテストメソッドの名前をつけます。

<?php
require_once 'PHPUnit/Framework.php';
require_once 'BankAccount.php';
 
class BankAccountTest extends PHPUnit_Framework_TestCase
{
    private $ba;
 
    protected function setUp()
    {
        $this->ba = new BankAccount;
    }
 
    public function testBalanceIsInitiallyZero()
    {
        $this->assertEquals(0, $this->ba->getBalance());
    }
 
    public function testBalanceCannotBecomeNegative()
    {
        try {
            $this->ba->withdrawMoney(1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
 
    public function testBalanceCannotBecomeNegative2()
    {
        try {
            $this->ba->depositMoney(-1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
 
    public function testBalanceCannotBecomeNegative3()
    {
        try {
            $this->ba->setBalance(-1);
        }
 
        catch (Exception $e) {
            return;
        }
 
        $this->fail();
    }
}
?>

それでは、最初のテスト testBalanceIsInitiallyZero() をクリアするために必要な最小限のコードを書いていきましょう。必要なのは、 BankAccount クラスの getBalance() メソッドを 例 12.2 のように実装することです。

<?php
class BankAccount
{
    private $balance = 0;
 
    public function getBalance()
    {
        return $this->balance;
    }
}
?>

これで最初のテストはクリアすることになりましたが、 2 番目のテストには失敗します。なぜなら、 テストメソッド内でコールしているメソッドがまだ実装されていないからです。

phpunit BankAccountTest
PHPUnit 3.0.0 by Sebastian Bergmann.

.
Fatal error: Call to undefined method BankAccount::withdrawMoney()

ふたつめの規約のテストをクリアするには、withdrawMoney()、 depositMoney() および setBalance() の各メソッドを 例 12.3 のように実装しなければなりません。これらのメソッドは、 規約に反するような引数でコールされた場合には InvalidArgumentException を発生させるように実装しています。

<?php
class BankAccount
{
    private $balance = 0;
 
    public function getBalance()
    {
        return $this->balance;
    }
 
    public function setBalance($balance)
    {
        if ($balance >= 0) {
            $this->balance = $balance;
        } else {
            throw new InvalidArgumentException;
        }
    }
 
    public function depositMoney($amount)
    {
        if ($amount >= 0) {
            $this->balance += $amount;
        } else {
            throw new InvalidArgumentException;
        }
    }
 
    public function withdrawMoney($amount)
    {
        if ($amount >= 0 && $this->balance >= $amount) {
            $this->balance -= $amount;
        } else {
            throw new InvalidArgumentException;
        }
    }
}
?>

これで、2 つめの規約に関するテストにもクリアするようになります。

phpunit BankAccountTest
PHPUnit 3.0.0 by Sebastian Bergmann.

....

Time: 00:00

OK (4 tests)

別の方法としては、PHPUnit_Framework_Assert クラスが提供する静的なアサーションメソッドを用いて、コード内に 「規約による設計」方式のアサーションを記述するというものもあります。 例 12.4 がその例です。これらのアサーションのいずれかに失敗すると、例外 PHPUnit_Framework_AssertionFailedError が発生します。 この方式を用いると、条件チェックのコードを減らすことができてテストが読みやすくなります。 ただ、プログラムの実行時にも PHPUnit が必要になってしまいます。

<?php
require_once 'PHPUnit/Framework.php';
 
class BankAccount
{
    private $balance = 0;
 
    public function getBalance()
    {
        return $this->balance;
    }
 
    public function setBalance($balance)
    {
        PHPUnit_Framework_Assert::assertTrue($balance >= 0);
 
        $this->balance = $balance;
    }
 
    public function depositMoney($amount)
    {
        PHPUnit_Framework_Assert::assertTrue($amount >= 0);
 
        $this->balance += $amount;
    }
 
    public function withdrawMoney($amount)
    {
        PHPUnit_Framework_Assert::assertTrue($amount >= 0);
        PHPUnit_Framework_Assert::assertTrue($this->balance >= $amount);
 
        $this->balance -= $amount;
    }
}
?>

規約を満たすための条件をテスト内に記述することで、「規約による設計」 方式で BankAccount クラスをプログラミングしてきました。 次に、テストファーストプログラミングの考え方にしたがって、 テストをクリアするために必要なコードを記述してきました。 でも、ひとつ忘れてしまったことがあります。それは、 setBalance()、depositMoney() および withdrawMoney() に正当な値を指定した場合に、 正常に動作することを確かめるテストを書くことです。 自分が書いたテストが妥当なものなのか、 それで十分なのかを調べるためのテストが必要ですね。次の章では、そのための 「コードカバレッジ解析」について説明します。

一般的に、エクストリームプログラミングのようなアジャイルプロセスを採用しているプロジェクトでは、 ドキュメントの内容が実際の設計やコードに追いついていないことが多いものです。 エクストリームプログラミングでは コードの共同所有 (collective code ownership) を要求しており、 すべての開発者がシステム全体の動作を知っておく必要があります。 作成するテストに対して、そのクラスが何を行うべきなのかを示すような 「わかりやすい」名前をつけられるようにさえしておけば、PHPUnit の TestDox 機能を使用して自動的にドキュメントを生成することができます。 このドキュメントにより、開発者たちはプロジェクト内の各クラスが どのようにふるまうべきなのかを知ることができます。

PHPUnit の TestDox 機能は、テストクラス内のすべてのテストメソッドの名前を抽出し、 それを PHP 風のキャメルケースから通常の文に変換します。つまり testBalanceIsInitiallyZero() が "Balance is initially zero" のようになるわけです。最後のほうの数字のみが違うメソッド、例えば testBalanceCannotBecomeNegative() と testBalanceCannotBecomeNegative2() のようなものが存在した場合は、 文 "Balance cannot become negative" は一度のみ表示され、 全てのテストが成功したことを表します。

以下のコードは、phpunit --testdox-text BankAccountTest.txt BankAccountTest を実行させて出力した、BankAccount クラス (例 12.1 を参照ください) のアジャイルな文書の例です。

BankAccount
 - Balance is initially zero
 - Balance cannot become negative

また、--testdox-html BankAccountTest.htm を使用することで、アジャイルな文書を HTML 形式で作成することもできます。

アジャイルな文書は、プロジェクト内であなたが作成しようとしている外部パッケージについて、 このように動作するであるという期待をまとめた文書にもなります。 外部のパッケージを使用するときには、 そのパッケージが期待通りに動作しなくなるというリスクに常にさらされています。 パッケージのバージョンアップにより知らないうちに挙動が変わってしまい、 あなたのコードが動作しなくなる可能性もあります。そのようなことを避けるため、 「このパッケージはこのように動作するはず」 ということを常にテストケースで記述しておくようにします。テストが成功すれば、 期待通りに動作していることがわかります。もし動作仕様をすべてテストで記述できているのなら、 外部パッケージが将来バージョンアップされたとしても何の心配もいりません。 テストをクリアしたということは、システムは期待通りに動作するということだからです。

あるパッケージについての機能を文書化するためにテストを書いているとき、 そのテストの所有者はあなたです。今あなたがテストを作成しているパッケージの作者は、 そのテストのことについては何も知りません。パッケージの作者とよりつながりを深めるため、 作成したテストを使用してコミュニケートしたり、 そのテストを使用して共同作業をしたりすることができるでしょう。

あなたが作成したテストを使用してパッケージの作者と共同作業をすることになれば、 テストも共同で書くことになります。そうすることで、 より多くのテストケースを挙げられるようになるでしょう。 「暗黙の了解」などに頼っていては、共同作業はできません。 テストと同時に、あなたはそのパッケージに対して期待していることを正確に文書化することになります。 また、すべてのテストにクリアした時点で、 作者はパッケージが完成したことを知ることになります。

スタブ (本書の前のほうで説明した "モックオブジェクト" の章を参照ください) を使用することで、パッケージの作者と別れても作業できるようになります。 パッケージ作者の仕事は、パッケージの実際の実装でテストをクリアするようにすること。 そしてあなたの仕事はあなたが書いたコードでテストをクリアするようにすることです。 この段階になれば、あなたはスタブオブジェクトを使用すればよいのです。 このやり方により、2 つのチームが独立して開発できるようになります。

PHPUnit がサポートする XML のフォーマットは、 Apache Ant の JUnit タスク が使用しているものを参考にしています。 以下の例は、ArrayTest のテストが生成した XML ログファイルです。

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite name="ArrayTest"
             file="/home/sb/ArrayTest.php"
             tests="2"
             failures="0"
             errors="0"
             time="0.016030">
    <testcase name="testNewArrayIsEmpty"
              class="ArrayTest"
              file="/home/sb/ArrayTest.php"
              line="6"
              time="0.008044"/>
    <testcase name="testArrayContainsAnElement"
              class="ArrayTest"
              file="/home/sb/ArrayTest.php"
              line="15"
              time="0.007986"/>
  </testsuite>
</testsuites>

次の XML ログファイルは、テストクラス FailureErrorTest にある 2 つのテスト testFailure および testError が出力したものです。失敗やエラーがどのように表示されるのかを確認しましょう。

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite name="FailureErrorTest"
             file="/home/sb/FailureErrorTest.php"
             tests="2"
             failures="1"
             errors="1"
             time="0.019744">
    <testcase name="testFailure"
              class="FailureErrorTest"
              file="/home/sb/FailureErrorTest.php"
              line="6"
              time="0.011456">
      <failure type="PHPUnit_Framework_ExpectationFailedException">
testFailure(FailureErrorTest)
Failed asserting that &lt;integer:2&gt; matches expected value &lt;integer:1&gt;.

/home/sb/FailureErrorTest.php:8
</failure>
    </testcase>
    <testcase name="testError"
              class="FailureErrorTest"
              file="/home/sb/FailureErrorTest.php"
              line="11"
              time="0.008288">
      <error type="Exception">testError(FailureErrorTest)
Exception: 

/home/sb/FailureErrorTest.php:13
</error>
    </testcase>
  </testsuite>
</testsuites>

JavaScript Object Notation (JSON) は、軽量なデータ交換用フォーマットです。次の例は、 ArrayTest のテストが作成した JSON メッセージです。

{"event":"suiteStart","suite":"ArrayTest","tests":2}
{"event":"test","suite":"ArrayTest",
 "test":"testNewArrayIsEmpty(ArrayTest)","status":"pass",
 "time":0.000460147858,"trace":[],"message":""}
{"event":"test","suite":"ArrayTest",
 "test":"testArrayContainsAnElement(ArrayTest)","status":"pass",
 "time":0.000422954559,"trace":[],"message":""}

次の JSON メッセージは、 FailureErrorTest にある 2 つのテスト testFailure および testError が出力したものです。失敗やエラーがどのように表示されるのかを確認しましょう。

{"event":"suiteStart","suite":"FailureErrorTest","tests":2}
{"event":"test","suite":"FailureErrorTest",
 "test":"testFailure(FailureErrorTest)","status":"fail",
 "time":0.000483989716,"trace":[],"message":""}
{"event":"test","suite":"FailureErrorTest",
 "test":"testError(FailureErrorTest)","status":"error",
 "time":0.000466108322,"trace":[],"message":""}

Test Anything Protocol (TAP) は、Perl のモジュールをテストする際に使用する、 シンプルなテキストベースのインターフェイスです。 以下の例は、ArrayTest のテストが生成した TAP ログファイルです。

# TestSuite "ArrayTest" started.
ok 1 - testNewArrayIsEmpty(ArrayTest)
ok 2 - testArrayContainsAnElement(ArrayTest)
# TestSuite "ArrayTest" ended.
1..2

次の TAP ログファイルは、テストクラス FailureErrorTest にあるメソッド testFailure および testError が出力したものです。失敗やエラーがどのように表示されるのかを確認しましょう。

# TestSuite "FailureErrorTest" started.
not ok 1 - Failure: testFailure(FailureErrorTest)
not ok 2 - Error: testError(FailureErrorTest)
# TestSuite "FailureErrorTest" ended.
1..2

PHPUnit は、テスト結果を図示することができます。 GraphViz ツール群を使用すると、これを画像などの便利な形式に変換することができます。

phpunit --log-graphviz ArrayTest.dot ArrayTest
PHPUnit 3.0.0 by Sebastian Bergmann.

..

Time: 00:00

OK (2 tests)

次の例は、ArrayTest のテストから生成された (そしてカレントディレクトリの ArrayTest.dot に保存された) GraphViz マークアップです。

digraph G {
  graph [ overlap="scale", splines="true", sep=".1", fontsize="8" ];
  "ArrayTest" [ color="green" ];
  subgraph "cluster_ArrayTest" {
    label="";
    "testNewArrayIsEmpty" [ color="green" ];
    "testArrayContainsAnElement" [ color="green" ];
  }

  "ArrayTest" -> "testNewArrayIsEmpty";
  "ArrayTest" -> "testArrayContainsAnElement";
}

GraphViz ソフトウェア群に含まれるコマンドラインツール dot を使用すると、 このマークアップから図を作成することができます。

dot -T png -o ArrayTest.png ArrayTest.dot

図 15.1 は、上の GraphViz マークアップをもとに作成したテスト結果の図です。

図15.1 テスト結果を図示したもの

成功したテストは緑の線で、失敗したりエラーが発生したものは赤い線で、 そして不完全だったり省略されたりしたテストは黄色い線で表示されます。 テストスイートなどの親ノードは、もしその子ノード (テスト) が成功しなかった場合は緑の線になりません。

@assert アノテーションを メソッドのコメント部で使用すると、 シンプルではあるけれど意味のあるテストを自動的に生成することができます。 これは不完全なテストケースではありません。 例 16.2 に例を示します。

<?php
class Calculator
{
    /**
     * @assert (0, 0) == 0
     * @assert (0, 1) == 1
     * @assert (1, 0) == 1
     * @assert (1, 1) == 2
     */
    public function add($a, $b)
    {
        return $a + $b;
    }
}
?>

もとのクラスの各メソッドについて、 @assert アノテーションの内容をチェックします。 これらは、以下のようなテストコードに変換されます。

    /**
     * Generated from @assert (0, 0) == 0.
     */
    public function testAdd() {
        $o = new Calculator;
        $this->assertEquals(0, $o->add(0, 0));
    }

作成されたテストケースクラスを実行した結果を以下に示します。

phpunit CalculatorTest
PHPUnit 3.0.0 by Sebastian Bergmann.

....

Time: 00:00


OK (4 tests)

表 16.1 に、サポートされる @assert の種類と、それがどのようなテストコードに変換されるかをまとめました。

Selenium RC はテストツールのひとつです。これを使用すると、 ウェブアプリケーションのユーザインターフェイスについてのテストを自動化することができます。 あらゆるプログラミング言語で稼動しているウェブサイトに対応しており、 現在主流のあらゆるブラウザで使用することができます。Selenium RC は Selenium Core を使用しています。これは、ブラウザ上でのタスクを自動的に実行する JavaScript のライブラリです。Selenium でのテストは、 一般のユーザが使用するのと同じようにブラウザ上で直接実行されます。 主な使用例としては、受け入れテスト (各システム単体のテストではなく、結合されたシステム全体に対するテスト) や ブラウザの互換性のテスト (ウェブアプリケーションを、さまざまなオペレーティングシステムやブラウザでテストする) などがあります。

Selenium RC のインストール手順は、次のようになります。

これで、クライアント/サーバ プロトコルを用いて Selenium RC サーバにコマンドを送信できるようになりました。

PHPUnit_Extensions_SeleniumTestCase は、Selenium RC と通信するためのプロトコルを実装したものです。 また、ウェブのテスト用に特化したアサーションメソッドも提供します。

例 17.1 は、 ウェブサイト http://www.example.com/ の <title> 要素の内容をテストする方法を示したものです。

<?php
require_once 'PHPUnit/Extensions/SeleniumTestCase.php';
 
class WebTest extends PHPUnit_Extensions_SeleniumTestCase
{
    protected function setUp()
    {
        $this->setBrowser('*firefox');
        $this->setBrowserUrl('http://www.example.com/');
    }
 
    public function testTitle()
    {
        $this->open('http://www.example.com/');
        $this->assertTitleEquals('Example Web Page');
    }
}
?>

PHPUnit_Framework_TestCase クラスとは異なり、 PHPUnit_Extensions_SeleniumTestCase を継承したテストケースクラスは setUp() メソッドが必須となります。 このメソッド内で、Selenium RC セッションの設定を行います。 ここで使用できるメソッドの一覧は 表 17.1 を参照ください。

表 17.2 は、PHPUnit_Extensions_SeleniumTestCase が提供するさまざまなアサーションメソッドの一覧です。

使用できるコマンドのリファレンスや実際の使用法については Selenium Core のドキュメント を参照ください。

継続的インテグレーションでは、テストを含めたビルド手順を 完全に自動化して何度でも実行できるようにしておく必要があります。 これは、一日に何度も実行されます。 各開発者は、この仕組みによって結合を行い、結合時の問題を減らします。 自動化を実現するには cronjob を使用します。このジョブでは、まずプロジェクトの ソースコードリポジトリ から定期的に最新版をチェックアウトし、 テストを実行し、その結果を利用しやすい形式で出力します。

ここで CruiseControl のような継続的ビルドプロセス用のフレームワークの出番です。 このフレームワークには、メールでの通知や Apache Ant との統合、 またさまざまなバージョン管理ツールとの統合のためのプラグインが用意されています。 またウェブインターフェイスも用意されており、 最新のビルドおよび以前のビルドについての詳細を見ることができます。

次の例では、CruiseControl が /usr/local/cruisecontrol にインストールされていることを想定しています。

<project name="BankAccount" default="build" basedir=".">
 <target name="checkout">
  <exec dir="${basedir}/source/" executable="svn">
   <arg line="up"/>
  </exec>
 </target>

 <target name="test">
  <exec dir="${basedir}/source" executable="phpunit" failonerror="true">
   <arg line="--log-xml ${basedir}/build/logs/bankaccount.xml BankAccountTest"/>
  </exec>
 </target>

 <target name="build" depends="checkout,test"/>
</project>

<cruisecontrol>
  <project name="BankAccount">
    <plugin
    name="svnbootstrapper"
    classname="net.sourceforge.cruisecontrol.bootstrappers.SVNBootstrapper"/>
    <plugin
    name="svn"
    classname="net.sourceforge.cruisecontrol.sourcecontrols.SVN"/>

    <listeners>
      <currentbuildstatuslistener file="logs/${project.name}/status.txt"/>
    </listeners>

    <bootstrappers>
      <svnbootstrapper localWorkingCopy="projects/${project.name}/source/"/>
    </bootstrappers>

    <modificationset quietperiod="30">
      <svn localWorkingCopy="projects/${project.name}/source/"/>
    </modificationset>

    <schedule interval="300">
      <ant
      anthome="apache-ant-1.7.0"
      buildfile="projects/${project.name}/build.xml"/>
    </schedule>

    <log dir="logs/${project.name}">
      <merge dir="projects/${project.name}/build/logs/"/>
    </log>

    <publishers>
      <currentbuildstatuspublisher
      file="logs/${project.name}/buildstatus.txt"/>

      <email
      mailhost="localhost"
      buildresultsurl="http://cruise.example.com/buildresults/${project.name}"
      skipusers="true"
      spamwhilebroken="true"
      returnaddress="project@example.com">
        <failure address="dev@lists.example.com" reportWhenFixed="true"/>
      </email>
    </publishers>
  </project>
</cruisecontrol>

Apache Maven は、ソフトウェアプロジェクトの管理や理解のためのツールです。 プロジェクト指向モデル (POM) にもとづいた Apache Maven は、 プロジェクトのビルドやレポート、ドキュメントの作成を共通の情報から行います。

PHPUnit の XML ログ機能 (「XML 形式」 を参照ください) で作成した XML のログファイルは、テストスイート単位で個別の XML に分割しないと Apache Maven の surefire plugin で処理することができません。 このプラグインはプロジェクトのテストフェーズで用いるもので、 アプリケーションのユニットテストを実行します。 例 18.4 に、XML の分割を行うための XSLT スタイルシートを示します。 例 18.3 は pom.xml 設定ファイルの例です。

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
  http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <!-- ... -->
  <prerequisites>
    <maven>2.0.7</maven>
  </prerequisites>    
  <!-- ... -->
  <build>
  <!-- ... -->
    <plugins>
      <plugin>
      <dependencies>
        <dependency>
          <groupId>org.apache.ant</groupId>
          <artifactId>ant-trax</artifactId>
          <version>1.7.0</version>
        </dependency>
        <dependency>
          <groupId>net.sf.saxon</groupId>
          <artifactId>saxon</artifactId>
          <version>8.7</version>
        </dependency>
      </dependencies>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-antrun-plugin</artifactId>
      <version>1.2-SNAPSHOT</version>
      <executions>
        <execution>
          <id>codecoverage</id>
          <phase>pre-site</phase>
          <goals>
            <goal>run</goal>
          </goals>
          <configuration>
            <tasks>
              <property name="phpunit.codecoverage"
                        location="${project.reporting.outputDirectory}/phpunit/codecoverage" />
              <property name="surefire.reports"
                        location="${project.build.directory}/surefire-reports" />

              <mkdir dir="${phpunit.codecoverage}"/>
              <mkdir dir="${surefire.reports}"/>

              <!-- ${ant.phpunit} path to PHPUnit executable -->
              <!-- ${ant.pear};... this is the include path for your test execution -->
              <!-- ${test.AllTests} PHPUnit cmd line args like 'AllTests de/dmc/dashboard/AllTests.php' -->
              <exec executable="${ant.phpunit}" dir="${basedir}">
                <arg line="-d include_path=${ant.pear};${project.build.sourceDirectory};${project.build.testSourceDirectory}
                           --report ${phpunit.codecoverage} ${test.AllTests}" />
              </exec>

              <xslt in="${phpunit.codecoverage}/logfile.xml"
                    out="${surefire.reports}/xslt.info"
                    style="src/test/config/phpunit_to_surefire.xslt"
                    processor="trax">
                <!-- this is the output folder for surefire like XML Reports -->
                <param name="outputDir" expression="${surefire.reports}"/>
              </xslt>
            </tasks>
          </configuration>
        </execution>
      </executions>
      </plugin>
    </plugins>
  </build>
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>2.4-SNAPSHOT</version>
        <reportSets>
          <reportSet>
            <reports>
              <report>report-only</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
</project>

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet version="2.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:fn="http://www.w3.org/2005/xpath-functions">
  <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
  <xsl:param name="outputDir">.</xsl:param>

  <xsl:template match="testsuites">
    <xsl:apply-templates select="testsuite"/>
  </xsl:template>

  <xsl:template match="testsuite">
    <xsl:if test="testcase">
      <xsl:variable name="outputName" select="./@name"/>
      <xsl:result-document href="file:///{$outputDir}/{$outputName}.xml" method="xml">
        <xsl:copy-of select="."/>
      </xsl:result-document>
    </xsl:if>

    <xsl:apply-templates select="testsuite"/>
  </xsl:template>
</xsl:stylesheet>

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

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

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

PHPUnit 用に書かれたテストケースのほとんどは、間接的に PHPUnit_Framework_Assert を継承しています。ここには、 値を自動的にチェックして矛盾を報告するためのメソッドが含まれています。 これらのメソッドは静的に宣言されているので、 あなたが作成したメソッドの中で「規約による設計」方式のアサーションを使用し、 PHPUnit に結果を報告させることができます (例 20.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, 'これは独自のメッセージです。');
    }
}
?>

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

phpunit MessageTest.php
PHPUnit 3.0.0 by Sebastian Bergmann.

F

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

FAILURES!
Tests: 1, Failures: 1.

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

もっと複雑なアサーションを行う場合には、 PHPUnit_Framework_Constraint クラスを使用します。 これらは、assertThat() メソッドを使用して 例 20.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);
    }
}
?>

<userinput>phpunit ConstraintTest</userinput>
PHPUnit 3.0.0 by Sebastian Bergmann.

F

Time: 00:00

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.

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

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

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

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

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

PHPUnit_Framework_Test は、 テストとして働くすべてのオブジェクトが使用する、 一般的なインターフェイスです。これを実装したオブジェクトは、 ひとつあるいは複数のテストを表すことになります。 表 20.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 によって実装されているメソッドを 表 20.7 にまとめます。

このクラスには 2 つのテンプレートメソッド setUp() および tearDown() が存在します。これをオーバーライドすると、 実行しようとしているテストに関する前処理や後始末を行うことができます。 表 20.8 にこれらのメソッドをまとめます。

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

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

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

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

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

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

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

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

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

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

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

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

PHPUnit_Framework_TestCase を継承した抽象サブクラスにユーティリティメソッドを書き、 そのクラスをさらに継承してテストクラスを作成します。 これが、PHPUnit を拡張するための一番簡単な方法です。

あなたの目的に合った独自のアサーションを実装したクラスを作成します。

PHPUnit_Extensions_TestDecorator のサブクラスでテストケースあるいはテストスイートをラッピングし、 デコレータパターンを使用することで 各テストの実行前後に何らかの処理をさせることができます。

PHPUnit には、PHPUnit_Extensions_RepeatedTest および PHPUnit_Extensions_TestSetup という 2 つの具象テストデコレータが付属しています。 前者はテストを繰り返し実行し、それらが全て成功した場合にのみ成功とみなします。 後者については 第 7 章 で説明しました。

例 21.1 は、テストデコレータ PHPUnit_Extensions_RepeatedTest の一部を抜粋したものです。独自のデコレータを作成するための参考にしてください。

<?php
require_once 'PHPUnit/Extensions/TestDecorator.php';
 
class PHPUnit_Extensions_RepeatedTest extends PHPUnit_Extensions_TestDecorator
{
    private $timesRepeat = 1;
 
    public function __construct(PHPUnit_Framework_Test $test, $timesRepeat = 1)
    {
        parent::__construct($test);
 
        if (is_integer($timesRepeat) &&
            $timesRepeat >= 0) {
            $this->timesRepeat = $timesRepeat;
        }
    }
 
    public function count()
    {
        return $this->timesRepeat * $this->test->count();
    }
 
    public function run(PHPUnit_Framework_TestResult $result = NULL)
    {
        if ($result === NULL) {
            $result = $this->createResult();
        }
 
        for ($i = 0; $i < $this->timesRepeat && !$result->shouldStop(); $i++) {
            $this->test->run($result);
        }
 
        return $result;
    }
}
?>

PHPUnit_Framework_Test インターフェイスの機能は限られており、 実装するのは簡単です。PHPUnit_Framework_Test を実装するのは PHPUnit_Framework_TestCase の実装より単純で、 これを用いて例えば データ駆動のテスト (data-driven tests) などを実行します。

カンマ区切り (CSV) ファイルの値と比較する、データ駆動のテストを 例 21.2 に示します。このファイルの各行は foo;bar のような形式になっており (訳注: CSV じゃない……)、 最初の値が期待値で 2 番目の値が実際の値です。

<?php
      <programlisting><![CDATA[<?php
require_once 'PHPUnit/Framework.php';
require_once 'PHPUnit/Util/Timer.php';
require_once 'PHPUnit/TextUI/TestRunner.php';
 
class DataDrivenTest implements PHPUnit_Framework_Test
{
    private $lines;
 
    public function __construct($dataFile)
    {
        $this->lines = file($dataFile);
    }
 
    public function count()
    {
        return 1;
    }
 
    public function run(PHPUnit_Framework_TestResult $result = NULL)
    {
        if ($result === NULL) {
            $result = new PHPUnit_Framework_TestResult;
        }
 
        foreach ($this->lines as $line) {
            $result->startTest($this);
            PHPUnit_Util_Timer::start();
 
            list($expected, $actual) = explode(';', $line);
 
            try {
                PHPUnit_Framework_Assert::assertEquals(trim($expected), trim($actual));
            }
 
            catch (PHPUnit_Framework_AssertionFailedError $e) {
                $result->addFailure($this, $e, PHPUnit_Util_Timer::stop());
            }
 
            catch (Exception $e) {
                $result->addError($this, $e, PHPUnit_Util_Timer::stop());
            }
 
            $result->endTest($this, PHPUnit_Util_Timer::stop());
        }
 
        return $result;
    }
}
 
$test = new DataDrivenTest('data_file.csv');
$result = PHPUnit_TextUI_TestRunner::run($test);
?>

PHPUnit 3.0.0 by Sebastian Bergmann.

.F

Time: 0 seconds

There was 1 failure:

1) DataDrivenTest
Failed asserting that two strings are equal.
expected string <bar>
difference      <  x>
got string      <baz>
/home/sb/DataDrivenTest.php:32
/home/sb/DataDrivenTest.php:53

FAILURES!
Tests: 2, Failures: 1.

独自の PHPUnit_Framework_TestResult オブジェクトを run() メソッドに渡すと、 テストの実行方法や収集されるテスト結果を変更することができます。

テスト結果をカスタマイズするために、必ず PHPUnit_Framework_TestResult のサブクラスを書かなければならないというわけではありません。たいていは、 新しい PHPUnit_Framework_TestListener を実装して (表 20.13 を参照ください)、 テストの前にそれを PHPUnit_Framework_TestResult オブジェクトにアタッチするだけで十分です。

例 21.3 は、PHPUnit_Framework_TestListener インターフェイスを実装する単純な例です。

<?php
require_once 'PHPUnit/Framework.php';
 
class SimpleTestListener
implements PHPUnit_Framework_TestListener
{
  public function
  addError(PHPUnit_Framework_Test $test,
           Exception $e,
           $time)
  {
    printf(
      "テスト '%s' の実行中にエラーが発生しました。\n",
      $test->getName()
    );
  }
 
  public function
  addFailure(PHPUnit_Framework_Test $test,
             PHPUnit_Framework_AssertionFailedError $e,
             $time)
  {
    printf(
      "テスト '%s' に失敗しました。\n",
      $test->getName()
    );
  }
 
  public function
  addIncompleteTest(PHPUnit_Framework_Test $test,
                    Exception $e,
                    $time)
  {
    printf(
      "テスト '%s' は未完了です。\n",
      $test->getName()
    );
  }
 
  public function
  addSkippedTest(PHPUnit_Framework_Test $test,
                 Exception $e,
                 $time)
  {
    printf(
      "テスト '%s' は省略されました。\n",
      $test->getName()
    );
  }
 
  public function startTest(PHPUnit_Framework_Test $test)
  {
    printf(
      "テスト '%s' が開始されました。\n",
      $test->getName()
    );
  }
 
  public function endTest(PHPUnit_Framework_Test $test, $time)
  {
    printf(
      "テスト '%s' が終了しました。\n",
      $test->getName()
    );
  }
 
  public function
  startTestSuite(PHPUnit_Framework_TestSuite $suite)
  {
    printf(
      "テストスイート '%s' が開始されました。\n",
      $suite->getName()
    );
  }
 
  public function
  endTestSuite(PHPUnit_Framework_TestSuite $suite)
  {
    printf(
      "テストスイート '%s' が終了しました。\n",
      $suite->getName()
    );
  }
}
?>

例 21.4 は、テストスイートを実行して監視する方法を示したものです。

<?php
require_once 'PHPUnit/Framework.php';
 
require_once 'ArrayTest.php';
require_once 'SimpleTestListener.php';
 
// ArrayTest クラスのテストを含む
// テストスイートを作成します。
$suite = new PHPUnit_Framework_TestSuite('ArrayTest');
 
// テスト結果オブジェクトを作成し、そこにオブザーバとして
// SimpleTestListener をアタッチします。
$result = new PHPUnit_Framework_TestResult;
$result->addListener(new SimpleTestListener);
 
// テストを実行します。
$suite->run($result);
?>

テストスイート 'ArrayTest' が開始されました。
テスト 'testNewArrayIsEmpty' が開始されました。
テスト 'testNewArrayIsEmpty' が終了しました。
テスト 'testArrayContainsAnElement' が開始されました。
テスト 'testArrayContainsAnElement' が終了しました。
テストスイート 'ArrayTest' が終了しました。

テストの実行結果を異なる方法で受け取りたい場合には、 独自のテストランナーを作成します。その際の初めの一歩となるのが、 PHPUnit_TextUI_TestRunner クラス (PHPUnit のコマンドライン版テストランナー) の親クラスである抽象クラス PHPUnit_Runner_BaseTestRunner です。