JUnit

說明

此任務會執行 JUnit 測試架構中的測試。您可以在 https://junit.dev.org.tw 找到架構的最新版本。此任務已使用 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.jar 包含在傳遞給 <junit> 的 <classpath> 中。自 Ant 1.7 起

請參閱 常見問題集以取得詳細資訊。

測試由巢狀 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> 元素來指定類別所需的系統屬性。這些屬性會在測試執行期間提供給 JVM（如果 fork=true，則為 Ant 的 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 屬性設定。

有四種預先定義好的格式化程式，一個會以 XML 格式列印測試結果，另一個會發出純文字。名為 brief 的格式化程式只會列印失敗測試案例的詳細資訊，而 plain 則會為所有測試案例提供簡要的統計資料行。可以指定需要實作 org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter 的自訂格式化程式。

如果您使用 XML 格式化程式，它可能不會包含您的測試所寫入的相同輸出，因為某些字元在 XML 文件中是非法的，因此會被捨棄。

第四個名為 failure 的格式化程式（自 Ant 1.8.0 起）會收集所有失敗的 testXXX() 方法，並建立一個新的 TestCase，只委派這些失敗的方法。名稱和位置可透過 Java 系統屬性或 Ant 屬性 ant.junit.failureCollector 指定。該值必須指向目錄和結果類別的名稱（沒有字尾）。預設為 java-tmp-dir/FailedTests。

測試

定義單一測試類別。

測試可透過巢狀 <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 執行多個測試，它無法判斷逾時/崩潰發生時執行了哪個測試。亦即，格式化程式無法與 forkMode 以外的任何其他 perTest 搭配使用，而且如果測試類別包含 suite() 方法，它不會執行任何動作。

如果格式化程式辨識出不相容的 forkMode 或 suite() 方法，或無法載入測試類別，它會在不發出任何訊息的情況下執行任何動作。

格式化程式不會對未分岔或未導致逾時或 JVM 崩潰的測試產生任何影響。

若要啟用格式化程式，請新增一個類似於

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

的 formatter 到您的 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 中定義的測試。在測試結束時，將會列印一行摘要。可在 TEST-my.test.TestCase.txt 中找到測試的詳細報告。如果測試失敗，將會停止建置程序。

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

在同一個 JVM 中執行 my.test.TestCase，忽略指定的 CLASSPATH；如果此測試失敗，只會列印警告。除了純文字測試結果外，此測試的 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 中建立一個 Java 原始檔，它會延伸 junit.framework.TestCase，並從 suite() 方法傳回失敗測試的測試套件。
在第二次執行時，收集器類別存在，並且會執行單一的 <test/>，而不是 <batchtest/>。因此，只會重新執行失敗的測試案例。兩個巢狀格式化程式用於顯示（給使用者）和更新收集器類別。

<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 屬性指定的 fork JVM 中，以白盒測試方式執行 my.test.TestCase。JUnit 函式庫是未命名模組的一部分，而受測專案和所需的模組則在模組路徑上。測試沒有 module-info 檔案，並在由 module.name 屬性指定的專案模組中執行。
--patch-module Java 選項會在由 module.name 屬性指定的模組中執行建置到 ${build.test.classes} 的測試。
--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 屬性指定的 fork JVM 中，以黑盒測試方式執行 my.test.TestCase。JUnit 函式庫用作自動模組。測試的 module-info 需要受測模組和 JUnit。
--add-modules Java 選項會啟用測試模組。
--add-exports Java 選項會讓未輸出的測試套件 my.test 可供 JUnit 模組和 Ant 的測試執行器存取。另一個可能性是透過 exports my.test 指令在測試的 module-info 中輸出測試套件。

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