第7回　DocTestを使ってUnitTestをやってみよう - テスト講座

DocTestとは

PHPでUnitTestを行うためには前回紹介したようなPHPUnitやSimpleTestといったツールを通常利用します。

既にこれらのツールを使ってみたことがある方は以下のような感想をお持ちだったかもしれません。

• 自分が開発しているもの以外にテストを記述したファイルを作らないといけないので、余計なものを作っている感じがする。(手間が増えた感じがする)
• 自分が開発しているファイルとテストを記述したファイルを行ったり来たりするのが面倒臭い。(やっぱり手間が増えた感じがする)

UnitTestに慣れてくると、こういうことすらも楽しく感じられるようになるのですが、UnitTestを試してみようという最初の段階では大きなハードルになるのではないでしょうか?

手間が増えた、面倒だと思ったことは続きません。できる限り手間をかけずに最大限の効果を得たいと欲張って作っているのが、"DocTest"です。

DocTestは次のような特徴があります。

• 自分が開発しているクラスやメソッドに対するテストをそのクラスやメソッドに対するDocコメントとして記述する

※ Docコメントとはクラスやメソッドの宣言直前につける特別なコメントで、/** で始まり */ で終わらせるという規約があります。引数の説明(@param)や返却値の説明(@return)などを今まで記述したことがある方も多いのではないでしょうか?

「たったそれだけ?」と思われるかもしれませんが、これによって最初に挙げた2つのハードルを解消できると考えています。

DocTestをインストールしてみよう

では、早速DocTestをインストールしてみましょう。

DocTestは以下の環境で動作します。

• PHP 5.1.4以上
• PEAR 1.4.3以上
• PHPUnit3が必要

PHPはセキュリティーホール対策などを考えると、できる限り最新バージョンを利用することが推奨されていますので、可能であれば5.2.6を利用してください。
※ 2008年8月26日現在は5.2.6が安定版最新のため

また、DocTestはPHPUnit3を使用しますので、PHPUnit3の最新版をインストールするようにしてください。(インストール手順は後述)

!!!注意!!!　これ以降解説するインストール手順は必ず個人の開発環境で行ってください。会社のPCや仕事で利用しているサーバなどで行うとその環境に問題が出る可能性があります。

(1) テストを試すディレクトリおよびファイルを作成する

次の手順であらかじめディレクトリおよびファイルを作っておきます。

!!!注意!!!　これ以降Windowsを使用していることを前提で説明します。*nix環境やMacの方はそれぞれのコマンドに"sudo"が必要な場合があります。ディレクトリなども適宜ご自分の環境に合わせて読み替えてください。

実行手順1 ディレクトリの作成

C:\>cd \
C:\>mkdir Temp
C:\>cd Temp
C:\Temp>mkdir phppro
C:\Temp>cd phppro
C:\Temp\phppro>mkdir classes
C:\Temp\phppro>mkdir tests_c

あわせて以下の作業を行ってください。これらのファイルはDocTestがテストディレクトリの位置を判別するために利用します。

• "C:\Temp\phppro\classes\__BASEDIR__"というファイルを作ってください。中身は空でかまいません。
• "C:\Temp\phppro\tests_c\__BASEDIR__"というファイルを作ってください。中身は空でかまいません。

上記の2ファイル(__BASEDIR__)が無事作成できたことがエクスプローラーで確認できますか? きちんと作成されていない場合はこの後のテストが正しく動作しないので忘れずにファイルを作成してください。

これ以降、"C:\Temp\phppro"というディレクトリで作業しているものとして説明を行います。

(2) PHPUnit3をインストールする

次にPHPUnit3をインストールします。インストールされているPEAR自体のバージョンが古い可能性がありますので、まずはそのアップデートから行いましょう。

実行手順2 PEAR自体のアップデート

C:\Temp\phppro>pear channel-update pear.php.net
C:\Temp\phppro>pear upgrade PEAR

続いてPHPUnit3をインストールしましょう。

実行手順3 PHPUnit3のインストール

C:\Temp\phppro>pear channel-discover pear.phpunit.de
C:\Temp\phppro>pear install phpunit/PHPUnit

(3) Maple4_DocTestをインストールする

Maple4_DocTestもpearコマンドでインストールできます。

実行手順4 Maple4_DocTestのインストール

C:\Temp\phppro>pear install http://kunit.jp/maple4/Maple4_DocTest-0.2.0.tgz

(4) Maple4_DocTestの実行用スクリプトを作成する

次のファイルを"C:\Temp\phppro\doctest.php"として作成してください。このファイルを使用してDoctestを実行することになります。

コード1 DocTestの実行用スクリプト

<?php
require_once 'Maple4/DocTest.php';
 
if (isset($argv[1]) && realpath($argv[1])) {
    $pathname = realpath($argv[1]);
} else {
    echo "Usage: php doctest.php [dirname or filename]\n";
    exit;
}
 
$options = array(
    'compileDir' => dirname(__FILE__) . '/tests_c',
    'color' => false,
    'report' => null,
    'forceCompile' => true,
    'notify' => null,
);
 
Maple4_DocTest::create()->run($pathname, $options);

上記のスクリプトに関して、*nixおよびMacの方は'color'オプションを'false'から'true'にするとテスト結果に色がつきます。成功はGREEN、失敗はREDがつくのでより今の状況がわかっていいと思います(残念ながらWindowsのコマンドプロンプトでは色はつきません)。

(5) Maple4_DocTestの実行用スクリプトを実行してみる

(3)の手順で作成したファイルを実行してみましょう。

実行手順5 DocTestの実行

C:\Temp\phppro>php doctest.php classes

まだ何も作成してないので、何も表示されないのが正しい状態です。ここでエラーが表示されるような場合は、ここまでの手順に問題があったかもしれませんので、一つ一つ確かめてください。