PHPUnit ポケットガイド

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

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

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

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

<?php
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/Extensions/TestSetup.php';
 
class DatabaseTestSetup extends PHPUnit2_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 PHPUnit2_Framework_TestSuite('DatabaseTests')
        );
    }
}
?>

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

例外をテストするにはどうすればいいのでしょう? 例外が発生したかどうかを直接検出することはできないので、その代わりに PHP の例外処理機能を使用してテストを書きましょう。 例外をテストするための例を以下に示します。

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

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

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

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

phpunit ExceptionTest
PHPUnit 2.3.0 by Sebastian Bergmann.

F

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

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

表 6.1 は、PHPUnit2_Extensions_ExceptionTestCase が実装している外部プロトコルをまとめたものです。

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

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

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

表 6.2 は、PHPUnit2_Extensions_PerformanceTestCase. が実装している外部プロトコルをまとめたものです。

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

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

<?php
require_once 'PHPUnit2/Framework/TestCase.php';
require_once 'BankAccount.php';
 
class BankAccountTest extends PHPUnit2_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() メソッドを 例 8.2 のように実装することです。

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

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

phpunit BankAccountTest
PHPUnit 2.3.0 by Sebastian Bergmann.

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

ふたつめの規約のテストをクリアするには、withdrawMoney()、 depositMoney() および setBalance() の各メソッドを 例 8.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 2.3.0 by Sebastian Bergmann.

....

Time: 0.057038

OK (4 tests)

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

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

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

オブジェクトが正しくコールされたかどうかを確かめなければならないこともあるでしょう。 コールされるオブジェクトの完全なスタブを作ることはできますが、 正確な結果を返しているかどうかを確かめるのは不便です。もっと簡単な方法は、 自己シャント (Self Shunt) パターンを使用して、 テストケース自身をスタブとして使用することです。自己シャントというのは医学用語で、 薬を注入する場所を確保するため、 チューブを挿入して動脈からとった血液を静脈にもどすことを意味します。

ここに例を示します。別のオブジェクトを観察 (observe) しているオブジェクト上で、 正しいメソッドがコールされたかどうかをテストしたいとします。まず、 Observer を実装したテストケースクラスを作成します。

class ObserverTest extends PHPUnit2_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 オブジェクトを作成したことに注意してください。スタブを利用する際には、 このような設計をお勧めします。こうすると、 オブジェクト間の結合度が緩やかになり、再利用性が高まります。

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

一般的に、エクストリームプログラミングのようなアジャイルプロセスを採用しているプロジェクトでは、 ドキュメントの内容が実際の設計やコードに追いついていないことが多いものです。 エクストリームプログラミングでは コードの共同所有 (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 クラス (例 8.1 を参照ください) のアジャイルな文書の例です。

BankAccount
 - Balance is initially zero
 - Balance cannot become negative

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

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

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

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

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

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

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

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

リファクタリングとは既存のコードの設計をよりよくするためのテクニックですが、 これを安全に行えるのは、きちんとしたテストスイートを持っている場合のみです。 さもないと、リファクタリングによってシステムを壊してしまっても あなたはそれに気づかないでしょう。リファクタリングは、 振る舞いを保持したままの細かい変更の繰り返しと考えることができます。

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

必須要素である <batchtest> 以外にも、 <phpunit2> には別の要素を含めることができます。 <formatter> はテスト結果の出力書式を変更するために使用するものです。 usefile 属性を false にしない限り、 出力は常にファイルに送信されます。 ファイル名はフォーマッタによって事前に決められていますが、 outfile 属性を使用して変更することも可能です。 定義済みのフォーマッタには以下のようなものがあります。

<formatter> タスクを設定するために使用できるパラメータの一覧を 表 12.2 にまとめます。

テスト結果を HTML 形式で出力するには <phpunit2report> タスクを使用します。これは、<formatter> タスクで作成した XML ログファイルに XSLT スタイルシートを適用するものです。 Phing には phpunit2-frames.xsl と phpunit2-noframes.xsl の 2 種類の XSLT スタイルシートが含まれており、それぞれフレーム使用版/フレーム未使用版の HTML を生成します。

例 12.2 では、Phing で BankAccountTest クラスのテストを実行し、 XSLT スタイルシート phpunit2-frames.xsl を使用して結果を HTML 形式で得るための build.xml ファイルを示します。レポートが生成した HTML ファイルは report/ ディレクトリに保存されます。このディレクトリは prepare <target> で作成され、clean <target> で削除されます。

<?xml version="1.0"?>

<project name="BankAccount" basedir="." default="report">
  <target name="prepare">
    <mkdir dir="report"/>
  </target>

  <target name="clean"> 
    <delete dir="report"/>
  </target>

  <target name="report" depends="prepare">
    <phpunit2>
      <batchtest>
        <fileset dir=".">
          <include name="*Test.php"/>
        </fileset>
      </batchtest>

      <formatter type="xml" todir="report" outfile="logfile.xml"/>
    </phpunit2>

    <phpunit2report infile="report/logfile.xml"
                    styledir="/usr/lib/php/data/phing/etc"
                    format="frames"
                    todir="report"/>
  </target>
</project>

以下に、phing コマンドを実行した際の出力例を示します。

phing
Buildfile: /home/sb/build.xml

BankAccount > prepare:
    [mkdir] Created dir: /home/sb/report

BankAccount > report:

BUILD FINISHED

Total time: 0.1112 seconds

生成されたテストレポートのタイトルページは 図 12.1 のようになります。

図12.1 生成されたテストレポート

<phpunit2report> タスクを設定するために使用できるパラメータの一覧を 表 12.3 にまとめます。

いま作成したテストレポートのほかに、 Phing ではコードカバレッジレポートを作成することもできます。そのためには、 <coverage-setup> タスクおよび <coverage-report> タスクを使用します。 前者はテストの実行中にコードカバレッジ情報を保存するためのデータベースを準備するタスクで、 後者は XSLT スタイルシートを使用して結果を HTML 形式に変換するタスクです。

例 12.3 では、 Phing で BankAccountTest クラスのテストを実行し、 HTML 形式のコードカバレッジレポートを生成するための build.xml ファイルを示します。

<?xml version="1.0"?>

<project name="BankAccount" basedir="." default="coverage-report">
  <target name="prepare">
    <mkdir dir="coverage-report"/>
  </target>

  <target name="clean"> 
    <delete dir="coverage-report"/>
  </target>

  <target name="coverage-report" depends="prepare">
    <coverage-setup database="./coverage-report/database">
      <fileset dir=".">
        <include name="*.php"/>
        <exclude name="*Test.php"/>
      </fileset>
    </coverage-setup>

    <phpunit2 codecoverage="true">
      <batchtest>
        <fileset dir=".">
          <include name="*Test.php"/>
        </fileset>
      </batchtest>
    </phpunit2>

    <coverage-report outfile="coverage-report/coverage.xml">
      <report styledir="/usr/lib/php/data/phing/etc"
              todir="coverage-report"/>
    </coverage-report>
  </target>
</project>

生成されたコードカバレッジレポートのタイトルページは 図 12.2 のようになります。

図12.2 生成されたコードカバレッジレポート

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

PHPUnit の、5 つの基本クラス/インターフェイスである PHPUnit2_Framework_Assert、 PHPUnit2_Framework_Test、 PHPUnit2_Framework_TestCase、 PHPUnit2_Framework_TestSuite および PHPUnit2_Framework_TestResult の関係を 図 14.1 に示します。

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

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

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

Fatal error: Uncaught exception 'PHPUnit2_Framework_AssertionFailedError'
with message 'expected: <NOT NULL> but was: <NULL>'

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

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

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

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

phpunit MessageTest.php
PHPUnit 2.3.0 by Sebastian Bergmann.

F

Time: 0.102507
There was 1 failure:
1) testMessage(MessageTest)
これは独自のメッセージです。

FAILURES!!!
Tests run: 1, Failures: 1, Errors: 0, Incomplete Tests: 0.

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

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

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

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

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

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

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

PHPUnit2_Framework_TestCase によって実装されている外部プロトコルを 表 14.4 にまとめます。

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

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

run(PHPUnit2_Framework_TestResult $result) および countTestCases() の 2 つに加え、 PHPUnit2_Framework_TestSuite は名前つきインスタンス、 名前なしインスタンスを作成するためのプロトコルも用意しています。 PHPUnit2_Framework_TestSuite のインスタンスを作成するための方法を 表 14.6 に示します。

PHPUnit2_Framework_TestSuite には、 PHPUnit2_Framework_Test を追加したり取得したりするためのプロトコルも用意されています。これを 表 14.7 にまとめます。

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

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

階層化されたテストケースを組み合わせた PHPUnit2_Framework_TestSuite の使用例として、PHPUnit 自身のテストスイートを見てみましょう。

例 14.4 は Tests/AllTests.php の一部を抜粋したもの、そして 例 14.5 は Tests/Framework/AllTests.php の一部を抜粋したものです。

<?php
if (!defined('PHPUnit2_MAIN_METHOD')) {
    define('PHPUnit2_MAIN_METHOD', 'AllTests::main');
}
 
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';
 
require_once 'Framework/AllTests.php';
// ...
 
class AllTests {
    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
 
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite('PHPUnit');
 
        $suite->addTest(Framework_AllTests::suite());
        // ...
 
        return $suite;
    }
}
 
if (PHPUnit2_MAIN_METHOD == 'AllTests::main') {
    AllTests::main();
}
?>

<?php
if (!defined('PHPUnit2_MAIN_METHOD')) {
    define('PHPUnit2_MAIN_METHOD', 'Framework_AllTests::main');
}
 
require_once 'PHPUnit2/Framework/TestSuite.php';
require_once 'PHPUnit2/TextUI/TestRunner.php';
 
require_once 'Framework/AssertTest.php';
// ...
 
class Framework_AllTests {
    public static function main() {
        PHPUnit2_TextUI_TestRunner::run(self::suite());
    }
 
    public static function suite() {
        $suite = new PHPUnit2_Framework_TestSuite('PHPUnit Framework');
 
        $suite->addTestSuite('Framework_AssertTest');
        // ...
 
        return $suite;
    }
}
 
if (PHPUnit2_MAIN_METHOD == 'Framework_AllTests::main') {
    Framework_AllTests::main();
}
?>

Framework_AssertTest クラスは、 PHPUnit2_Framework_TestCase を継承した一般的なテストケースです。

Tests/AllTests.php を実行すると、TextUI テストランナーを使用し、すべてのテストを実行します。一方 Tests/Framework/AllTests.php を実行すると、 PHPUnit2_Framework_* クラスのテストのみを実行します。

PHPUnit テストスイートの実行結果は、このようになります。

php AllTests.php
PHPUnit 2.3.0 by Sebastian Bergmann.

.........................................
.........................................
.......

Time: 4.642600

OK (89 tests)

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

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

表 14.8 は、 PHPUnit2_Framework_TestResult の外部プロトコルをまとめたものです。

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

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

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

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

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

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

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

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

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

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

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

<?php
require_once 'PHPUnit2/Framework/Assert.php';
require_once 'PHPUnit2/Framework/Test.php';
require_once 'PHPUnit2/Framework/TestResult.php';
 
class DataDrivenTest implements PHPUnit2_Framework_Test {
    private $lines;
 
    public function __construct($dataFile) {
        $this->lines = file($dataFile);
    }
 
    public function countTestCases() {
        return sizeof($this->lines);
    }
 
    public function run($result = NULL) {
        if ($result === NULL) {
            $result = new PHPUnit2_Framework_TestResult;
        }
 
        $result->startTest($this);
 
        foreach ($this->lines as $line) {
            list($expected, $actual) = explode(';', $line);
 
            try {
                PHPUnit2_Framework_Assert::assertEquals(trim($expected), trim($actual));
            }
 
            catch (PHPUnit2_Framework_ComparisonFailure $e) {
                $result->addFailure($this, $e);
            }
 
            catch (Exception $e) {
                $result->addError($this, $e);
            }
        }
 
        $result->endTest($this);
 
        return $result;
    }
}
 
$test   = new DataDrivenTest('data_file.csv');
$result = $test->run();
 
$failures = $result->failures();
print $failures[0]->thrownException()->toString();
?>

expected: <foo> but was: <bar>

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

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

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

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

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

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

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

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