JUnitLauncher

描述

此任务允许使用 JUnit 5 框架启动和运行测试。

JUnit 5 引入了编写和启动测试的新 API 集。它还引入了测试引擎的概念。测试引擎决定哪些类被视为测试用例以及如何执行它们。JUnit 5 支持运行使用 JUnit 4 结构编写的测试，以及使用 JUnit 5 结构编写的测试。有关 JUnit 5 本身的更多详细信息，请参阅 JUnit 5 项目的文档：https://junit.cn/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 目录中，并将所有其他相关 jar 包含在类路径中，方法是在调用 Ant 时将它们作为 -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 元素指向包含测试类的位置。如果需要，所有这些类路径都可以组合成一个。

listener

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 格式化程序生成的 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 指定一组用作系统属性的属性

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>

选择与 ${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>