JUnitLauncher

說明

此任務允許使用 JUnit 5 架構啟動並執行測試。

JUnit 5 引入了一組較新的 API 來撰寫和啟動測試。它也引入了測試引擎的概念。測試引擎決定哪些類別被視為測試案例以及如何執行它們。JUnit 5 支援執行使用 JUnit 4 結構撰寫的測試，以及使用 JUnit 5 結構撰寫的測試。有關 JUnit 5 本身的更多詳細資訊，請參閱 JUnit 5 專案的說明文件，網址為 https://junit.dev.org.tw/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 檔案的位置（如上所述）。請閱讀 使用類別路徑元素 部分以取得更多詳細資訊。
• 或者將所有這些相關 JAR 檔案連同 ant-junitlauncher.jar 放入 ANT_HOME/lib 目錄中
• 或將 ant-junitlauncher.jar 放入 ANT_HOME/lib 目錄，並在呼叫 Ant 時，將所有其他相關 jar 檔案包含在類別路徑中，傳遞它們作為 -lib 選項

測試由巢狀元素定義，例如 test、testclasses 標籤（請參閱 巢狀元素）。

參數

巢狀元素

classpath

巢狀 <classpath> 元素表示 類似 PATH 的結構，可用於將任務設定為使用此類別路徑來尋找和執行測試。此類別路徑將用於

• 尋找要執行的測試類別
• 尋找執行測試的測試引擎
• 如果 設定為執行此動作，則尋找所有必要的 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 元素指向包含我們測試類別的位置。如有需要，所有這些類別路徑都可以合併成一個。

監聽器

junitlauncher 任務可以使用 listener(s) 來監聽測試執行事件（例如測試執行開始、完成等）。預期監聽器是一個實作 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 格式化程式會產生 XML 以符合 junit 任務的 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

可透過 jvmarg 元素將其他 JVM 引數傳遞至分岔 JVM。例如

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

jvmarg 允許 命令列引數 中說明的所有屬性

sysproperty

sysproperty 元素允許將 Java 系統屬性傳遞給分岔的 JVM

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

此元素的屬性與 環境變數 的屬性相同

syspropertyset

您可以使用 syspropertyset(s) 指定一組屬性，作為系統屬性使用

env

可以透過嵌套的 env 元素來指定要傳遞給分岔 JVM 的環境變數。有關 env 元素屬性的說明，請參閱 exec 任務中的說明。

modulepath

可以使用 modulepath 元素來指定 Java 模組的位置，它是一個 類似路徑的結構。

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

upgrademodulepath

可以使用 upgrademodulepath 元素來指定 Java 模組的位置，它會取代執行階段中可升級的模組，它是一個 類似路徑的結構。

範例

啟動 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>

選取任何符合 org/example/**/tests/**/ fileset 篩選器的 .class 檔案，在 ${build.classes.dir} 下，並將這些類別傳遞給 JUnit 5 平台，作為測試執行。

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

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

選取任何符合 org/example/**/tests/**/ fileset 篩選器的 .class 檔案，在 ${build.classes.dir} 下，並將這些類別傳遞給 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>