JUnit

説明

このタスクは、JUnitテストフレームワークのテストを実行します。フレームワークの最新バージョンは、https://junit.dokyumento.jp にあります。このタスクは、JUnit 3.0 から JUnit 3.8.2 まででテストされています。JUnit 3.0 より前のバージョンでは動作しません。また、JUnit 4.x でも動作し、アノテーションのみを使用し、JUnit4TestAdapter を使用しない「純粋な」JUnit 4 テストも含まれます。

注: このタスクは、Apache Ant ディストリビューションに含まれていない外部ライブラリに依存しています。詳細については、ライブラリの依存関係 を参照してください。

注: このタスクまたはこのタスクによって起動されるテスト、あるいはテストで使用されるライブラリが、java.lang.System.exit() や java.lang.Runtime.exit() などの API を呼び出す場合は、fork=true を設定する必要があります。

注: junit.jar が利用可能である必要があります。以下のいずれかを実行できます。

1. junit.jar と ant-junit.jar の両方を ANT_HOME/lib に配置します。
2. どちらも ANT_HOME/lib に配置せず、代わりにそれらの場所を CLASSPATH 環境変数に含めます。
3. -lib を使用して、両方の JAR をクラスパスに追加します。
4. ビルドファイルの <taskdef> 内の <classpath> 要素を使用して、両方の JAR の場所を指定します。
5. ant-junit.jar を ANT_HOME/lib のデフォルトの場所に置いたまま、<junit> に渡される <classpath> に junit.jar を含めます。Ant 1.7 以降

詳細については、FAQ を参照してください。

テストは、ネストされた test または batchtest タグによって定義されます（ネストされた要素 を参照）。

パラメータ

errorproperty 属性と failureproperty 属性を使用することにより、セットアップ作業（外部サーバーの起動など）を実行し、テストを実行し、クリーンアップを行い、それでも失敗した場合にビルドを失敗させることができます。

filtertrace 属性は、エラーと失敗のスタックトレースを報告する前に圧縮します。プレーンフォーマッタと XML フォーマッタの両方で動作します。次の文字列パターンで始まる行はすべて除外されます。

   "junit.framework.TestCase"
   "junit.framework.TestResult"
   "junit.framework.TestSuite"
   "junit.framework.Assert."
   "junit.swingui.TestRunner"
   "junit.awtui.TestRunner"
   "junit.textui.TestRunner"
   "java.lang.reflect.Method.invoke("
   "sun.reflect."
   "org.apache.tools.ant."
   "org.junit."
   "junit.framework.JUnit4TestAdapter"
   " more"

ネストされた要素として指定されたパラメータ

<junit> タスクは、パスのような構造 を表すネストされた <classpath> 要素をサポートしています。

*Ant 1.7 以降*、このクラスパスは、テストとテスト対象のコードだけでなく、junit.jar を参照するためにも使用できます。

jvmarg

fork が true の場合、ネストされた <jvmarg> 要素を介して新しい JVM に追加のパラメータを渡すことができます。例えば

<junit fork="yes">
  <jvmarg value="-Dfoo=bar"/>
  ...
</junit>

は、JIT なしで JVM でテストを実行します。

<jvmarg> は、コマンドライン引数 で説明されているすべての属性を許可します。

sysproperty

ネストされた <sysproperty> 要素を使用して、クラスに必要なシステムプロパティを指定します。これらのプロパティは、テストの実行中（Ant の JVM または fork=true の場合はフォークされた JVM）に JVM で使用できるようになります。この要素の属性は、環境変数 の属性と同じです。

<junit fork="no">
  <sysproperty key="basedir" value="${basedir}"/>
  ...
</junit>

は、Ant の JVM でテストを実行し、basedir プロパティをテストで使用できるようにします。

syspropertyset

Ant 1.6 以降

syspropertyset を使用して、システムプロパティとして使用するプロパティのセットを指定できます。

env

ネストされた <env> 要素を介して、フォークされた JVM に渡す環境変数を指定できます。<env> 要素の属性の説明については、exec タスクの説明を参照してください。

fork=false の場合、設定は無視されます。

bootclasspath

Ant 1.6 以降.

ブートストラップクラスファイルの場所は、この パスのような構造 を使用して指定できます。fork が false の場合、またはターゲット JVM がそれをサポートしていない場合（つまり Java 1.1）は無視されます。

permissions

Ant 1.6 以降.

注:
この要素は、Java 18 以降のバージョンで実行されている場合はサポートされなくなりました。詳細については、permissions を参照してください。

ネストされた permissions 要素を介して、クラスの実行中にセキュリティパーミッションを取り消したり、付与したりできます。詳細については、permissions を参照してください。

fork=true の場合、設定は無視されます。

assertions

Ant 1.6 以降.

<assertions> サブ要素を使用して、Java 1.4 アサーションの有効化を制御できます。

アサーションステートメントは、現在、非フォークモードでは無視されます。

modulepath

Ant 1.9.8 以降

モジュールの場所は、この パスのような構造 を使用して指定できます。
modulepath を使用するには、fork を true に設定する必要があります。

upgrademodulepath

Ant 1.9.8 以降

ランタイムイメージでアップグレード可能なモジュールを置き換えるモジュールの場所は、この パスのような構造 を使用して指定できます。
upgrademodulepath を使用するには、fork を true に設定する必要があります。

formatter

テストの結果は、さまざまな形式で出力できます。usefile 属性を false に設定しない限り、出力は常にファイルに送信されます。ファイルの名前はテストの名前によって決まり、<test> の outfile 属性によって設定できます。

定義済みのフォーマッタは 4 つあります。1 つはテスト結果を XML 形式で出力し、もう 1 つはプレーンテキストで出力します。brief という名前のフォーマッタは、失敗したテストケースの詳細情報のみを出力しますが、plain はすべてのテストケースの簡単な統計行を出力します。org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter を実装する必要があるカスタムフォーマッタを指定できます。

XML フォーマッタを使用する場合、テストが出力したものと同じ出力が含まれない場合があります。これは、一部の文字が XML ドキュメントでは不正であり、削除されるためです。

failure という名前の 4 番目のフォーマッタ（*Ant 1.8.0 以降*）は、失敗したすべての testXXX() メソッドを収集し、これらの失敗したメソッドのみを委任する新しい TestCase を作成します。名前と場所は、Java システムプロパティまたは Ant プロパティ ant.junit.failureCollector で指定できます。値は、結果のクラスのディレクトリと名前（サフィックスなし）を指している必要があります。デフォルトは java-tmp-dir/FailedTests です。

test（テスト）

単一のテストクラスを定義します。

テストは、ネストされた <formatter> 要素を介して独自のフォーマッタを定義できます。

batchtest（バッチテスト）

パターンマッチングに基づいて複数のテストを定義します。

batchtest は、ネストされた任意の数のリソースコレクションから含まれるリソースを収集します。そして、.java または .class で終わる各リソースのテストクラス名を生成します。

ネストされた要素として、あらゆる種類のリソースコレクションがサポートされています。Ant 1.7より前は、<fileset> のみがサポートされていました。

バッチテストは、ネストされた<formatter>要素を介して独自のフォーマッタを定義できます。

フォークされたテストと tearDown()

フォークされたテストがタイムアウトになった場合、Ant は作成した JVM プロセスを終了します。これは、テストの tearDown() メソッドが呼び出されない可能性があることを意味します。フォークされた JVM が他の理由でクラッシュした場合も同様です。

Ant 1.8.0以降、Ant には、フォークされた JVM にあったテストケースを読み込んで、そのクラスの tearDown() メソッドを呼び出そうとする特別なフォーマッタが付属しています。このフォーマッタには、以下の制限があります。

• Ant 自体と同じ JVM で実行されます。これは、テストを実行していた JVM とは異なる JVM であり、異なるクラスローダーが表示される場合があります（そのため、テストクラスを読み込めない場合があります）。
• フォークされた JVM が複数のテストを実行していた場合、タイムアウト/クラッシュが発生したときにどのテストが実行されていたかを判断できません。つまり、フォーマッタは perTest 以外の forkMode では動作せず、テストクラスに suite() メソッドが含まれている場合は何も実行しません。

フォーマッタが互換性のない forkMode または suite() メソッドを認識するか、テストクラスの読み込みに失敗した場合、サイレントに何も実行しません。

フォーマッタは、フォークされていないテスト、またはタイムアウトや JVM クラッシュを引き起こさなかったテストには影響しません。

フォーマッタを有効にするには、次のような formatter を追加します。

<formatter classname="org.apache.tools.ant.taskdefs.optional.junit.TearDownOnVmCrash"
           usefile="false"/>

を junit タスクに追加します。

ant.junit.enabletestlistenerevents マジックプロパティ

Ant 1.8.2以降、タスクの enableTestListenerEvents 属性は、きめ細かいログメッセージがタスクの詳細ログに送信されるかどうかを制御します。この属性に加えて、Ant はプロパティ ant.junit.enabletestlistenerevents を参照し、プロパティの値は属性の設定をオーバーライドします。

このプロパティは、追加のロギングイベントに依存する Ant を実行しているコンテナが、ビルドファイルで無効になっている場合でも、それらが生成されることを保証できるようにするために存在します。

例

同じ VM で my.test.TestCase に定義されたテストを実行します。テストが失敗しない限り、出力は生成されません。

<junit>
    <test name="my.test.TestCase"/>
</junit>

別の JVM で my.test.TestCase に定義されたテストを実行します。テストの最後に、1 行のサマリーが出力されます。テストの詳細なレポートは、TEST-my.test.TestCase.txt にあります。テストが失敗すると、ビルドプロセスは停止します。

<junit printsummary="yes" fork="yes" haltonfailure="yes">
    <formatter type="plain"/>
    <test name="my.test.TestCase"/>
</junit>

指定された CLASSPATH を無視して、同じ JVM で my.test.TestCase を実行します。このテストが失敗した場合、警告のみが出力されます。プレーンテキストのテスト結果に加えて、このテストの XML 結果が result.xml に出力されます。次に、${src.tests} に定義されたディレクトリ内の一致するファイルごとに、別の JVM でテストが実行されます。テストが失敗すると、ビルドプロセスは中止されます。結果は TEST-name.txt という名前のファイルに収集され、${reports.tests} に書き込まれます。

<junit printsummary="yes" haltonfailure="yes">
    <classpath>
        <pathelement location="${build.tests}"/>
        <pathelement path="${java.class.path}"/>
    </classpath>

    <formatter type="plain"/>

    <test name="my.test.TestCase" haltonfailure="no" outfile="result">
        <formatter type="xml"/>
    </test>

    <batchtest fork="yes" todir="${reports.tests}">
        <fileset dir="${src.tests}">
            <include name="**/*Test*.java"/>
            <exclude name="**/AllTests.java"/>
        </fileset>
    </batchtest>
</junit>

最初の実行では、すべてのテストは <batchtest/> 要素を介して収集されます。その plain フォーマッタは、コンソールに出力を表示します。failure フォーマッタは、${build.dir}/failingTests/FailedTests.java に junit.framework.TestCase を拡張し、suite() メソッドから失敗したテストのテストスイートを返す Java ソースファイルを作成します。
2 回目の実行では、コレクタクラスが存在し、<batchtest/> の代わりに単一の <test/> が実行されます。そのため、失敗したテストケースのみが再実行されます。2 つのネストされたフォーマッタは、（ユーザー向けに）表示するためと、コレクタクラスを更新するためのものです。

<target name="test">
    <property name="collector.dir" value="${build.dir}/failingTests"/>
    <property name="collector.class" value="FailedTests"/>
    <!-- Delete 'old' collector classes -->
    <delete>
        <fileset dir="${collector.dir}" includes="${collector.class}*.class"/>
    </delete>
    <!-- compile the FailedTests class if present -->
    <javac srcdir="${collector.dir}" destdir="${collector.dir}"/>
    <available file="${collector.dir}/${collector.class}.class" property="hasFailingTests"/>
    <junit haltonerror="false" haltonfailure="false">
        <sysproperty key="ant.junit.failureCollector" value="${collector.dir}/${collector.class}"/>
        <classpath>
            <pathelement location="${collector.dir}"/>
        </classpath>
        <batchtest todir="${collector.dir}" unless="hasFailingTests">
            <fileset dir="${collector.dir}" includes="**/*.java" excludes="**/${collector.class}.*"/>
            <!-- for initial creation of the FailingTests.java -->
            <formatter type="failure"/>
            <!-- I want to see something ... -->
            <formatter type="plain" usefile="false"/>
        </batchtest>
        <test name="FailedTests" if="hasFailingTests">
            <!-- update the FailingTests.java -->
            <formatter type="failure"/>
            <!-- again, I want to see something -->
            <formatter type="plain" usefile="false"/>
        </test>
    </junit>
</target>

platform.java プロパティで指定されたフォークされた JVM で、my.test.TestCase をホワイトボックステストとして実行します。JUnit ライブラリは無名モジュールの一部であり、テスト対象のプロジェクトと必要なモジュールはモジュールパス上にあります。テストには module-info ファイルがなく、`module.name` プロパティで指定されたプロジェクトモジュールで実行されます。
--patch-module Java オプションは、${build.test.classes} に組み込まれたテストを、`module.name` プロパティで指定されたモジュールで実行します。
--add-modules Java オプションは、テスト対象のモジュールを有効にします。
--add-reads Java オプションは、JUnit を含む無名モジュールをテスト対象モジュールから読み取り可能にします。
--add-exports Java オプションは、エクスポートされていないテストパッケージ `my.test` を、JUnit を含む無名モジュールからアクセスできるようにします。

<junit fork="true"
       jvm="${platform.java}">
    <jvmarg line="--patch-module ${module.name}=${build.test.classes}"/>
    <jvmarg line="--add-modules ${module.name}"/>
    <jvmarg line="--add-reads ${module.name}=ALL-UNNAMED"/>
    <jvmarg line="--add-exports ${module.name}/my.test=ALL-UNNAMED"/>
    <classpath>
        <pathelement path="${libs.junit}"/>
    </classpath>
    <modulepath>
        <pathelement path="${modules}:${build.classes}"/>
    </modulepath>
    <formatter type="plain"/>
    <test name="my.test.TestCase"/>
</junit>

platform.java プロパティで指定されたフォークされた JVM で、`my.test.TestCase` をブラックボックステストとして実行します。JUnit ライブラリは自動モジュールとして使用されます。テストの module-info は、テスト対象モジュールと JUnit を必要とします。
--add-modules Java オプションは、テストモジュールを有効にします。
--add-exports Java オプションは、エクスポートされていないテストパッケージ `my.test` を JUnit モジュールと Ant のテストランナーからアクセスできるようにします。別の方法として、テストの module-info で `exports my.test` ディレクティブを使用してテストパッケージをエクスポートすることもできます。

<junit fork="true"
       jvm="${platform.java}">
    <jvmarg line="--add-modules ${test.module.name}"/>
    <jvmarg line="--add-exports ${test.module.name}/my.test=junit,ALL-UNNAMED"/>
    <modulepath>
        <pathelement path="${modules}:${build.classes}:${libs.junit}"/>
    </modulepath>
    <formatter type="plain"/>
    <test name="my.test.TestCase"/>
</junit>