JUnitLauncher

説明

このタスクを使用すると、JUnit 5 フレームワークを使用してテストを起動し、実行できます。

JUnit 5 は、テストを記述して起動するための新しい API セットを導入しました。また、テストエンジンの概念も導入しました。テストエンジンは、どのクラスをテストケースと見なし、それらをどのように実行するかを決定します。JUnit 5 は、JUnit 4 の構成要素を使用して記述されたテストと、JUnit 5 の構成要素を使用して記述されたテストの両方を実行できます。JUnit 5 自体の詳細については、JUnit 5 プロジェクトのドキュメント (https://junit.dokyumento.jp/junit5/) を参照してください。

この junitlauncher タスクの目的は、JUnit 5 テストランチャーを起動し、テストリクエストを構築して、選択されたテストを JUnit 5 でサポートされているテストエンジンによって解析および実行できるようにすることです。このタスク自体は、テストケースが何であるかを理解しておらず、テスト自体を実行することもありません。

このタスクは、一時ディレクトリ内にテスト出力と設定データをキャプチャします。

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

注意: テストのクラスパスに必要な JUnit 5 ライブラリが必要です。このドキュメントの執筆時点では、テストを実行するために必要な JUnit 5 プラットフォームライブラリのリストは次のとおりです。

• junit-platform-commons.jar
• junit-platform-engine.jar
• junit-platform-launcher.jar
• opentest4j.jar

テストで使用するテストエンジンによっては、さらに次のライブラリがクラスパスに必要になります。

junit-vintage エンジンの場合

• junit-vintage-engine.jar
• junit.jar (JUnit 4.x バージョン)

junit-jupiter エンジンの場合

• junit-jupiter-api.jar
• junit-jupiter-engine.jar

これらをテストクラスパスに含めるには、次のいずれかの方法に従います。

• Ant 1.10.6 以降の推奨されるアプローチ: ant-junitlauncher.jar を ANT_HOME/lib ディレクトリに配置し、ネストされた <classpath> 要素を使用して、残りの JUnit 固有の jar（上記）の場所を指定します。詳細については、classpath 要素の使用セクションを参照してください。
• または、これらの関連するすべての jar を ant-junitlauncher.jar と共に ANT_HOME/lib ディレクトリに配置します。
• または、ant-junitlauncher.jar を ANT_HOME/lib ディレクトリに配置し、Ant を呼び出す際に -lib オプションとして渡すことで、他のすべての関連する jar をクラスパスに含めます。

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

パラメータ

ネストされた要素

classpath

PATH のような構造を表すネストされた <classpath> 要素を使用して、テストの検索と実行にこのクラスパスを使用するようにタスクを設定できます。このクラスパスは、次の目的で使用されます。

• 実行するテストクラスの検索
• テストを実行するテストエンジンの検索
• 設定されている場合、必要なすべての JUnit ライブラリの検索

タスクに classpath 要素が設定されていない場合、Ant 自体のクラスパスがテストクラスと JUnit ライブラリの検索に使用されます。

以下は、テストの実行中に Jupiter テストエンジンと JUnit プラットフォームライブラリを含めるようにクラスパスを設定する例です。

<project>

    <property name="output.dir" value="${basedir}/build"/>
    <property name="src.test.dir" value="${basedir}/src/test"/>
    <property name="build.classes.dir" value="${output.dir}/classes"/>

    <target name="init">
        <mkdir dir="${output.dir}"/>
    </target>

    <path id="junit.platform.libs.classpath">
        <fileset dir="${basedir}/src/lib/junit-platform/"/>
    </path>

    <path id="junit.engine.jupiter.classpath">
        <fileset dir="${basedir}/src/lib/jupiter/"/>
    </path>

    <target name="compile-test" depends="init">
        <mkdir dir="${build.classes.dir}"/>
        <javac srcdir="${src.test.dir}"
           destdir="${build.classes.dir}">
           <!-- our tests only need JUnit Jupiter engine
           libraries in our compile classpath for the tests -->
           <classpath refid="junit.engine.jupiter.classpath"/>
        </javac>
    </target>

    <target name="test" depends="compile-test">
        <junitlauncher>
            <!-- include the JUnit platform related libraries
            required to run the tests -->
            <classpath refid="junit.platform.libs.classpath"/>

            <!-- include the JUnit Jupiter engine libraries -->
            <classpath refid="junit.engine.jupiter.classpath"/>

            <classpath>
                <!-- the test classes themselves -->
                <pathelement location="${build.classes.dir}"/>
            </classpath>
            <testclasses outputdir="${output.dir}">
                <fileset dir="${build.classes.dir}"/>
                <listener type="legacy-brief" sendSysOut="true"/>
                <listener type="legacy-xml" sendSysErr="true" sendSysOut="true"/>

            </testclasses>
        </junitlauncher>
    </target>
</project>
    

上記の例では、

• src/lib/jupiter ディレクトリには、Jupiter テストエンジン関連の jar（このドキュメントの前のセクションにリストされています）が含まれていると想定されています。
• src/lib/junit-platform ディレクトリには、JUnit プラットフォーム jar（このドキュメントの前のセクションにリストされています）が含まれていると想定されています。

test ターゲットでは、ネストされた classpath 要素を使用して、これらの jar を含む junit.engine.jupiter.classpath と junit.platform.libs.classpath を指します。この test ターゲットでは、別の classpath 要素を使用して、テストクラスを含む場所を指します。必要に応じて、これらのクラスパスはすべて 1 つにまとめることができます。

リスナー

junitlauncher タスクは、テスト実行イベント（テスト実行の開始、完了など）をリッスンするように listener で設定できます。リスナーは、org.junit.platform.launcher.TestExecutionListener を実装するクラスである必要があります。この TestExecutionListener インターフェースは、JUnit 5 プラットフォーム API によって公開される API であり、Ant 固有のものではありません。そのため、このタスクでは、TestExecutionListener の既存の実装を使用できます。

テスト結果フォーマッタ

junitlauncher は、テスト実行結果をカスタマイズ可能な方法でフォーマットして表示する方法を提供します。タスクでは、listener 要素を使用してテスト結果フォーマッタを設定できます。前述のように、listener 要素は、リスナーが org.junit.platform.launcher.TestExecutionListener インターフェースを実装することを期待しています。通常、結果フォーマッタには、テスト実行中にフォーマットされた結果を書き込む場所などの詳細な設定が必要です。このようなリスナーは、オプションで org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter インターフェースを実装できます。このインターフェースは Ant junitlauncher タスクに固有であり、org.junit.platform.launcher.TestExecutionListener インターフェースを拡張します。

junitlauncher タスクには、次の定義済みテスト結果フォーマッタタイプが付属しています。

• legacy-plain : このフォーマッタは、すべてのテストケースの簡単な統計行を出力します。
• legacy-brief : このフォーマッタは、失敗したテストまたはスキップされたテストの情報を出力します。
• legacy-xml : このフォーマッタは、テストの統計を XML 形式で出力します。

注意: legacy という名前のこれらのフォーマッタはそれぞれ、junit タスクのフォーマッタが行っていた 것과 類似した方法で結果をフォーマットしようとします。さらに、legacy-xml フォーマッタは、junit タスクの XML フォーマッタが従っていたのと同じスキーマに準拠するように XML を生成します。そのため、このフォーマッタによって生成された XML は、junitreport タスクでそのまま使用できます。

listener 要素は、次の属性をサポートしています。

test

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

テストは、ネストされた listener 要素を介して独自のリスナーを定義できます。

fork ネストされた要素を使用して、新しくフォークされた JVM でテストを実行できます。

testclasses

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

testclasses は、ネストされた任意の数の リソースコレクション から含まれる リソース を収集します。そして、名前が .class で終わる各リソースを選択します。これらのクラスは、JUnit 5 プラットフォームに渡され、テストとして決定および実行されます。

testclasses は、ネストされた listener 要素を介して独自のリスナーを定義できます。

fork ネスト要素を使用すると、新しくフォークされた JVM でテストを実行できます。この testclasses 要素の一部であるすべてのテストは、新しくフォークされた JVM の単一のインスタンスで実行されます。

fork

Ant 1.10.6 以降

jvmarg

追加の JVM 引数は、jvmarg 要素を介してフォークされた JVM に渡すことができます。例えば

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

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

sysproperty

sysproperty 要素を使用すると、Java システムプロパティをフォークされた JVM に渡すことができます。

    <fork>
        <sysproperty key="greeting" value="hello world"/>
    ...
    </fork>
    

この要素の属性は、環境変数と同じです。

syspropertyset

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

env

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

modulepath

Java モジュールの場所は、パスのような構造である modulepath 要素を使用して指定できます。

<fork>
  <modulepath>
    <pathelement location="lib"/>
    <pathelement location="dist/test.jar"/>
  </modulepath>
  ...
</fork>

upgrademodulepath

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

例

JUnit 5 プラットフォームを起動して、org.myapp.SimpleTest テストを実行します。

<path id="test.classpath">
    ...
</path>

<junitlauncher>
    <classpath refid="test.classpath"/>
    <test name="org.myapp.SimpleTest"/>
</junitlauncher>

JUnit 5 プラットフォームを起動して、org.myapp.SimpleTest テストと org.myapp.AnotherTest テストを実行します。 org.myapp.SimpleTest のいずれかのテストが失敗した場合、ビルドプロセスは停止します。

<junitlauncher>
    <classpath refid="test.classpath"/>
    <test name="org.myapp.SimpleTest" haltOnFailure="true"/>
    <test name="org.myapp.AnotherTest"/>
</junitlauncher>

JUnit 5 プラットフォームを起動して、org.myapp.SimpleTest テストクラスの testFoo メソッドと testBar メソッドのみを実行します。

<junitlauncher>
    <classpath refid="test.classpath"/>
    <test name="org.myapp.SimpleTest" methods="testFoo, testBar"/>
</junitlauncher>

${build.classes.dir} の下で org/example/**/tests/**/ fileset フィルターに一致する .class ファイルを選択し、それらのクラスをテストとして実行するために JUnit 5 プラットフォームに渡します。

<junitlauncher>
    <classpath refid="test.classpath"/>

    <testclasses outputdir="${output.dir}">
        <fileset dir="${build.classes.dir}">
            <include name="org/example/**/tests/**/"/>
        </fileset>
    </testclasses>
</junitlauncher>

${build.classes.dir} の下で org/example/**/tests/**/ fileset フィルターに一致する .class ファイルを選択し、それらのクラスをテストとして実行するために JUnit 5 プラットフォームに渡します。テスト結果は、legacy-xml および legacy-plain フォーマッターによって、別々のファイルで ${output.dir} に書き込まれます。さらに、上記の legacy-xml リスナーと legacy-plain リスナーの両方が、テストによって生成された標準出力コンテンツを受信するように構成されています。 legacy-xml リスナーは、標準エラーコンテンツも受信するように構成されています。

<junitlauncher>
    <classpath refid="test.classpath"/>

    <testclasses outputdir="${output.dir}">
        <fileset dir="${build.classes.dir}">
            <include name="org/example/**/tests/**/"/>
        </fileset>
        <listener type="legacy-xml" sendSysOut="true" sendSysErr="true"/>
        <listener type="legacy-plain" sendSysOut="true" />
    </testclasses>
</junitlauncher>