TDoclet

概要

 テストドライバ(もし JUnit を使用しているならば JUnit の junit.framework.TestCase クラスを継承し て作成するクラスのことと考えてください)のソースコード内のカスタムタグに記述されたテスト内容からテ スト一覧を出力するドックレットです。テスト結果を取り込んで、テストの一覧とそれに対するテストの結果 とその履歴を出力します。現在は JUnit が出力するテスト結果ファイルに対応しています。

 これにより、TDoclet はユーザにテスト内容の一覧を示すことを要求された時に行わなければならなくなっ てしまう作業を助けてくれます。実装したテストケースからどのようなチェックを行っているかをいちいち抽 出してまとめる必要が無くなり、プログラムを読むことができない人へテスト内容の一覧を伝えることが可能 になります。
 また、出力されるドキュメント(現在は固有の XML ファイルを出力します)にはテストフレームワークの実 行結果も含まれていますので、テストが成功した割合だけでなく表形式で確認することができます。きっと 開発者の作業にも役立つ場合があると思います。

 現在の目標は JUnit 用に作成したテストケースを XML に出力することを目標としています。このとき JUnit が出力したテスト結果を格納した XML ファイルを読込んでテスト結果も取り込みます。
 出力される単位はテスト項目と呼びます。 テスト項目はテストメソッドに対して複数定義できます。テス ト項目を一意に識別するには テストクラス、テストメソッド、テスト項目ID(これは定義時に任意に指定する ことが出来ます)を指定します。テスト項目ID は1つのメソッドの中で一意になっている必要があります。

 入力ファイルとしてはカスタムタグの記述のあるソースファイル、JUnit などが出力するテスト結果ファイ ル、および過去のテスト一覧が出力されているファイルの 3 つです。

インストール

 インストールは、ダウンロードしたアーカイブに含まれている tdoclet.jar をクラスパスを通すだけです。

実行方法

 javadoc のカスタム doclet として動作します。コマンドラインからの実行は次のようになります(本当は 1 行で指定します)。

% javadoc -doclet jp.co.tticc.tool.doclet.TestListDoclet -report dir report
           -destfile testlist.xml src/unit/jp/co/tticc/util/ArraysTest.java
 このカスタム doclet は独自に 2 つのオプションを追加しています。-report および -destfile です。-report は JUnit の実行結果の XML ファイルを探すパスを指定します。 -destfile には出力する XML ファイルの名前を指定します。また、過去のテスト結果は古い出力ファ イルから獲得します。

Jakarta ant を使っての実行

 Jakarta Ant で利用するには現在使用している build.xml ファイルに以下の用にターゲットを追加すれば すぐに(もちろんいくつかは環境に合わせて書き換える必要がありますが)利用できます。

<target name="tlist" depends="init">
    <mkdir dir="${report.dir}/unitlist" >
    <javadoc
    packagenames="samples.*"
	sourcepath="src"
	Verbose="false" >
	<classpath>
	    <pathelement path="${resource.dir}" />
	    <pathelement path="${classes.dest.dir}" />
	    <pathelement path="${java.class.path}" />
	</classpath>
	<doclet name="tdoclet.TDoclet" path="${classes.dest.dir}" >
	    <param name="-reportdir" value="${report.dir}" />
	<param name="-destfile" value="${report.dir}/unitlist/testlist.xml" />
	</doclet>
    </javadoc>
</target>

使用方法

javadoc ドキュメントの挿入

 先に述べましたが、出力される単位はテスト項目と呼ばれるものです。テスト項目の定義は JUnit 用のテ スト用のソースファイル(TestCase を継承したクラス)に以下のように javadoc 用のコメントを追加します。
/**
 * メソッド説明。
 *
 * @target ターゲットクラス
 * @test id1 : 説明
 * @test id2 : 説明
 */
public void testMethod1() {
     .
     .
     .
}

 現在の実装ではメソッドに関する説明の記述は無視されます。
 カスタムタグ @target にはテスト対象となるクラス、すなわちテストを行いたいクラスを記述する ことを想定していますが、現在の実装は特別な処理は行わずその内容を出力 XML ファイルへ出力していま す。
 カスタムタグ @test に記述した内容がテスト項目となります。: で区切ってテスト項目の ID とテスト項目の説明を記述します。ID は 1 つのメソッドで一意でなくてはなりません。同一の ID を持 っている場合は同一のテスト項目とみなされます。また省略した場合はそのあとに続くテスト項目概要がテス ト項目 ID とされます。この場合はテスト項目説明を修正すると以降は別のテスト項目とみなされます。
 テスト項目はメソッドに複数定義できます。例えばファイル読込みのテストクラスを実装したとすると、 「任意の場所のデータを正しく読込めたか。」、「最後のデータを正しく読込めたか。」、「ファイルの終わ りの先を読込んだ場合。」などのテストを行うはずです(この例は「リファクタリング:プログラミングの体質 改善テクニック(マーチン・ファウラー,ピアソン・エデュケーション,2000)」を参考にしました)。そのテス ト用のメソッドには assertEqual() メソッドもしくは他の Assert クラスのメソッドが 3 つあるはずです。 このとき 3 つのテスト項目を定義することが可能です。それ以上の項目を定義することも可能です(意味があ るとは思えませんが)。これは強制されるものではありません。プロジェクトではメソッド 1 つについて 1 つのテスト項目としているのであれば 1 つだけ定義すれば問題ありません。とにかくテスト項目を定義す る単位は利用者の自由です。

テスト履歴の扱い

 過去のテストの履歴情報は生成する xml ファイル名と同一のファイルが検索パスに既にある場合はそこか ら獲得します。実際には何もしません。最新のテスト結果をそこへ追加するだけです。

テスト一覧の XML ファイルから HTML ファイルを生成する

Xalan などの XSLT プロセッサを使用すれば、 TDoclet によって生成された XML ファイルから HTML を生成することができます。ダウンロードしたアーカ イブには、サンプルの XSLT ファイル testlist.xsl が含まれています。Xalan がインストール去れているの であれば、
% xalan -IN report/unitlist/testlist.xml -XSL testlist.xsl -OUT testcase_list.html
を実行すればテスト一覧表を表示するための testcase_list.html が生成されます。
SourceForge.jp