| API 文档 | Test |
|---|
执行 JUnit (3.8.x, 4.x 或 5.x) 或 TestNG 测试。测试始终在（一个或多个）单独的 JVM 中运行。
以下示例展示了各种配置选项。
plugins {
id("java-library") // adds 'test' task
}
test {
// discover and execute JUnit4-based tests
useJUnit()
// discover and execute TestNG-based tests
useTestNG()
// discover and execute JUnit Platform-based tests
useJUnitPlatform()
// set a system property for the test JVM(s)
systemProperty 'some.prop', 'value'
// explicitly include or exclude tests
include 'org/foo/**'
exclude 'org/boo/**'
// show standard out and standard error of the test JVM(s) on the console
testLogging.showStandardStreams = true
// set heap size for the test JVM(s)
minHeapSize = "128m"
maxHeapSize = "512m"
// set JVM arguments for the test JVM(s)
jvmArgs('-XX:MaxPermSize=256m')
// listen to events in the test execution lifecycle
beforeTest { descriptor ->
logger.lifecycle("Running test: " + descriptor)
}
// fail the 'test' task on the first test failure
failFast = true
// skip an actual test execution
dryRun = true
// listen to standard out and standard error of the test JVM(s)
onOutput { descriptor, event ->
logger.lifecycle("Test: " + descriptor + " produced standard out/err: " + event.message )
}
}
通过在调用构建时提供 `--debug-jvm` 开关，可以临时以调试模式启动测试进程（参见 Test.getDebug()）。
gradle someTestTask --debug-jvm
| 属性 | 描述 |
allJvmArgs | 用于启动进程 JVM 的完整参数集。这包括定义系统属性、最小/最大堆大小和引导类路径的参数。 |
binaryResultsDirectory | 内部二进制格式测试结果的根目录属性。 |
bootstrapClasspath | 用于进程的引导类路径。当此类路径为空时，使用 JVM 的默认引导类路径。 |
类路径 | 用于执行测试的类路径。 |
调试 | 确定是否为测试进程启用调试。启用时—— |
debugOptions | 进程的 Java Debug Wire Protocol 属性。如果启用，则 |
dryRun | 孵化中 指示此任务是否跳过单个测试执行。 |
enableAssertions | 如果为进程启用了断言，则返回 true。 |
environment | 用于进程的环境变量。默认为当前进程的环境。 |
excludes | 测试执行的排除模式。 |
可执行文件 | 要使用的可执行文件的名称。 |
failFast | 指示此任务是否在第一个失败的测试上失败。 |
failOnNoDiscoveredTests | 如果存在测试源，但在测试执行期间未发现任何测试，任务是否应该失败。默认为 true。 |
forkEvery | 在分叉测试进程中执行的最大测试类数量。达到此限制时，分叉测试进程将重新启动。 |
ignoreFailures | 指定此任务执行的验证失败时是否应中断构建。 |
includes | 测试执行的包含模式。 |
javaLauncher | 配置用于运行测试的 Java 可执行文件。 |
jvmArgs | 用于启动进程 JVM 的额外参数。不包括系统属性和最小/最大堆大小。 |
jvmArgumentProviders | 用于分叉 Java 进程的命令行参数提供者。 |
maxHeapSize | 进程的最大堆大小（如果有）。 |
maxParallelForks | 并行启动的最大测试进程数量。 |
minHeapSize | 进程的最小堆大小（如果有）。 |
modularity | 此测试任务的模块路径处理。 |
options | 返回测试框架特定选项。在使用此方法之前，请务必调用 |
reports | 此任务可能生成的报告。 |
scanForTestClasses | 指定是否应检测测试类。当 |
systemProperties | 将用于进程的系统属性。 |
testClassesDirs | 已编译测试源的目录。 |
testLogging | 允许设置与哪些测试事件记录到控制台以及在哪个详细级别相关的选项。例如，要显示更多关于异常的信息，请使用 |
workingDir | 进程的工作目录。默认为项目目录。 |
| 属性 | 描述 |
jacoco | 由 jacoco 插件添加的 |
| 方法 | 描述 |
addTestListener(listener) | 向此任务注册测试监听器。还可以考虑以下便捷方法，以更快地挂接到测试执行中： |
addTestOutputListener(listener) | 向此任务注册输出监听器。挂接输出事件的更快方法是使用 |
afterSuite(closure) | 添加一个闭包，在测试套件执行后得到通知。 |
afterTest(closure) | 添加一个闭包，在测试执行后得到通知。 |
beforeSuite(closure) | 添加一个闭包，在测试套件执行前得到通知。 |
beforeTest(closure) | 添加一个闭包，在测试执行前得到通知。 |
bootstrapClasspath(classpath) | 将给定值添加到进程的引导类路径的末尾。 |
copyTo(target) | 将这些选项复制到给定选项。 |
copyTo(target) | 将这些选项复制到给定目标选项。 |
debugOptions(action) | 配置进程的 Java Debug Wire Protocol 属性。如果启用了 |
environment(name, value) | 向此进程的环境中添加一个环境变量。 |
environment(environmentVariables) | 向此进程的环境中添加一些环境变量。 |
exclude(excludeSpec) | 添加一个排除规范。此方法可以多次调用以追加新的规范。给定的闭包将 |
exclude(excludes) | 为测试类目录中的文件添加排除模式（例如 '**/*Test.class')）。 |
exclude(excludes) | 为测试类目录中的文件添加排除模式（例如 '**/*Test.class')）。 |
exclude(excludeSpec) | 添加排除规范。此方法可以多次调用以追加新的规范。如果未提供排除，则不会排除任何文件。如果提供了排除，则文件必须不匹配任何排除模式才能进行处理。 |
executable(executable) | 设置要使用的可执行文件的名称。 |
include(includeSpec) | 添加一个包含规范。此方法可以多次调用以追加新的规范。给定的闭包将 |
include(includes) | 为测试类目录中的文件添加包含模式（例如 '**/*Test.class')）。 |
include(includes) | 为测试类目录中的文件添加包含模式（例如 '**/*Test.class')）。 |
include(includeSpec) | 添加一个包含规范。此方法可以多次调用以追加新的规范。如果未提供包含，则此容器中的所有文件都将被包含。如果提供了包含，则文件必须至少匹配一个包含模式或规范才能被包含。 |
jvmArgs(arguments) | 添加一些用于启动进程 JVM 的参数。 |
jvmArgs(arguments) | 添加一些用于启动进程 JVM 的参数。 |
onOutput(closure) | 添加一个闭包，在收到来自测试的输出时得到通知。 |
options(testFrameworkConfigure) | 配置测试框架特定选项。 |
removeTestListener(listener) | 从此任务注销测试监听器。此方法只会删除通过在此任务上调用 |
removeTestOutputListener(listener) | 从此任务注销测试输出监听器。此方法只会删除通过在此任务上调用 |
reports(configureAction) | 配置此任务可能生成的报告。 |
setTestNameIncludePatterns(testNamePattern) | 设置要包含在执行中的测试名称模式。支持类名或方法名，支持通配符 '*'。有关更多信息，请参阅测试的用户指南章节。有关支持模式的更多信息，请参阅 |
systemProperties(properties) | 添加一些用于进程的系统属性。 |
useJUnit() | 指定应使用 JUnit4 来发现和执行测试。 |
useJUnit(testFrameworkConfigure) | 指定应使用 JUnit4 来发现和执行测试，并进行额外配置。 |
useJUnit(testFrameworkConfigure) | 指定应使用 JUnit4 来发现和执行测试，并进行额外配置。 |
useJUnitPlatform() | 指定应使用 JUnit Platform 来发现和执行测试。 |
useJUnitPlatform(testFrameworkConfigure) | 指定应使用 JUnit Platform 来发现和执行测试，并进行额外配置。 |
useTestNG() | 指定应使用 TestNG 来发现和执行测试。 |
useTestNG(testFrameworkConfigure) | 指定应使用 TestNG 来发现和执行测试，并进行额外配置。 |
useTestNG(testFrameworkConfigure) | 指定应使用 TestNG 来发现和执行测试，并进行额外配置。 |
workingDir(dir) | 设置进程的工作目录。提供的参数按照 |
DirectoryProperty binaryResultsDirectory
内部二进制格式测试结果的根目录属性。
- 默认值
project.testResultsDir/binary/task.name
FileCollection classpath
用于执行测试的类路径。
确定是否为测试进程启用调试。启用时——debug = true——进程以暂停状态启动，侦听端口 5005。调试时应禁用并行测试执行，并且如果 Test.getForkEvery() 的值不为零，您将需要偶尔重新附加调试器。
自 Gradle 5.6 起，您可以通过 JavaForkOptions.debugOptions(org.gradle.api.Action) 配置端口和其他 Java 调试属性。
- 默认与
java插件一起使用 false
JavaDebugOptions debugOptions （只读）
进程的 Java Debug Wire Protocol 属性。如果启用，则 -agentlib:jdwp=... 将附加到 JVM 参数中，并使用参数中的配置。
注意：此属性处于孵化中，可能会在 Gradle 的未来版本中更改。
指示此任务是否跳过单个测试执行。
对于 JUnit 4 和 5，这将报告本应执行的测试为跳过。对于 TestNG，这将报告本应执行的测试为通过。
仅支持支持原生空运行的 TestNG 版本，即 TestNG 6.14 或更高版本。
在分叉测试进程中执行的最大测试类数量。达到此限制时，分叉测试进程将重新启动。
默认情况下，Gradle 在执行测试时会自动使用单独的 JVM。
- 值
0（无限制）表示对所有测试类重用测试进程。这是默认值。 - 值
1表示为 每个 测试类启动一个新的测试进程。这非常耗费资源。 - 值
N表示在N个测试类之后启动一个新的测试进程。
由于停止和启动每个测试进程的成本，此属性可能对性能产生巨大影响。此属性通常不会从默认值更改。
- 默认与
java插件一起使用 0
并行启动的最大测试进程数量。
默认情况下，Gradle 一次执行一个测试类。
- 值
1表示一次仅在一个测试进程中执行一个测试类。这是默认值。 - 值
N表示最多将启动N个测试进程来执行测试类。这可以通过并行运行多个测试类来提高测试执行时间。
此属性不能超过当前构建的 max-workers 值。Gradle 还将限制所有 Test 任务中启动的测试进程数量。
- 默认与
java插件一起使用 1
ModularitySpec modularity （只读）
此测试任务的模块路径处理。
TestFrameworkOptions options （只读）
返回测试框架特定选项。在使用此方法之前，请务必调用 Test.useJUnit()、Test.useJUnitPlatform() 或 Test.useTestNG()。
TestTaskReports reports （只读）
此任务可能生成的报告。
指定是否应检测测试类。当 true 时，扫描匹配包含和排除模式的类以查找测试类，并执行任何找到的测试。当 false 时，执行匹配包含和排除模式的类。
- 默认与
java插件一起使用 true
FileCollection testClassesDirs
已编译测试源的目录。
TestLoggingContainer testLogging （只读）
允许设置与哪些测试事件记录到控制台以及在哪个详细级别相关的选项。例如，要显示更多关于异常的信息，请使用
apply plugin: 'java' test.testLogging { exceptionFormat = "full" }
有关更多信息，请参阅 TestLoggingContainer。
JacocoTaskExtension jacoco （只读）
由 jacoco 插件添加的 JacocoTaskExtension。
void addTestListener(TestListener listener)
向此任务注册测试监听器。还可以考虑以下便捷方法，以更快地挂接到测试执行中：AbstractTestTask.beforeTest(groovy.lang.Closure)、AbstractTestTask.afterTest(groovy.lang.Closure)、AbstractTestTask.beforeSuite(groovy.lang.Closure)、AbstractTestTask.afterSuite(groovy.lang.Closure)
此监听器不会收到其他任务执行的测试的通知。要获得该行为，请使用 Gradle.addListener(java.lang.Object)。
void addTestOutputListener(TestOutputListener listener)
向此任务注册输出监听器。挂接输出事件的更快方法是使用 AbstractTestTask.onOutput(groovy.lang.Closure) 方法。
void afterSuite(Closure closure)
添加一个闭包，在测试套件执行后得到通知。TestDescriptor 和 TestResult 实例作为参数传递给闭包。
此方法也在所有测试套件执行后调用。提供的描述符将具有一个空父套件。
void afterTest(Closure closure)
添加一个闭包，在测试执行后得到通知。TestDescriptor 和 TestResult 实例作为参数传递给闭包。
void beforeSuite(Closure closure)
添加一个闭包，在测试套件执行前得到通知。TestDescriptor 实例作为参数传递给闭包。
此方法也在任何测试套件执行前调用。提供的描述符将具有一个空父套件。
void beforeTest(Closure closure)
添加一个闭包，在测试执行前得到通知。TestDescriptor 实例作为参数传递给闭包。
Test copyTo(JavaForkOptions target)
将这些选项复制到给定选项。
Test copyTo(ProcessForkOptions target)
将这些选项复制到给定目标选项。
void debugOptions(Action<JavaDebugOptions>
Action<JavaDebugOptions>配置进程的 Java Debug Wire Protocol 属性。如果启用了 JavaForkOptions.setDebug(boolean)，则 -agentlib:jdwp=... 将附加到 JVM 参数中，并使用参数中的配置。
添加一个排除规范。此方法可以多次调用以追加新的规范。给定的闭包将 FileTreeElement 作为其参数传递。闭包应返回 true 或 false。示例
copySpec {
from 'source'
into 'destination'
//an example of excluding files from certain configuration:
exclude { it.file in configurations.someConf.files }
}
如果未提供排除项，则不会排除任何文件。如果提供了排除项，则文件必须不匹配任何排除模式才能进行处理。
Test exclude(Spec<FileTreeElement>
Spec<FileTreeElement>添加排除规范。此方法可以多次调用以追加新的规范。如果未提供排除，则不会排除任何文件。如果提供了排除，则文件必须不匹配任何排除模式才能进行处理。
添加一个包含规范。此方法可以多次调用以追加新的规范。给定的闭包将 FileTreeElement 作为其参数。如果未提供包含，则此容器中的所有文件都将被包含。如果提供了包含，则文件必须至少匹配一个包含模式或规范才能被包含。
Test include(Spec<FileTreeElement>
Spec<FileTreeElement>添加一个包含规范。此方法可以多次调用以追加新的规范。如果未提供包含，则此容器中的所有文件都将被包含。如果提供了包含，则文件必须至少匹配一个包含模式或规范才能被包含。
void onOutput(Closure closure)
添加一个闭包，在收到来自测试的输出时得到通知。TestDescriptor 和 TestOutputEvent 实例作为参数传递给闭包。
apply plugin: 'java' test { onOutput { descriptor, event -> if (event.destination == TestOutputEvent.Destination.StdErr) { logger.error("Test: " + descriptor + ", error: " + event.message) } } }
TestFrameworkOptions options(Action<? super TestFrameworkOptions>
Action<? super TestFrameworkOptions>配置测试框架特定选项。
当在测试套件外部创建 Test 任务时，在使用此方法之前，您应该调用 Test.useJUnit()、Test.useJUnitPlatform() 或 Test.useTestNG()。如果未设置测试框架，任务将假定为 JUnit4。
void removeTestListener(TestListener listener)
从此任务注销测试监听器。此方法只会删除通过在此任务上调用 AbstractTestTask.addTestListener(org.gradle.api.tasks.testing.TestListener) 添加的监听器。如果监听器是使用 Gradle.addListener(java.lang.Object) 向 Gradle 注册的，则此方法将不执行任何操作。相反，请使用 Gradle.removeListener(java.lang.Object)。
void removeTestOutputListener(TestOutputListener listener)
从此任务注销测试输出监听器。此方法只会删除通过在此任务上调用 AbstractTestTask.addTestOutputListener(org.gradle.api.tasks.testing.TestOutputListener) 添加的监听器。如果监听器是使用 Gradle.addListener(java.lang.Object) 向 Gradle 注册的，则此方法将不执行任何操作。相反，请使用 Gradle.removeListener(java.lang.Object)。
TestTaskReports reports(Action<? super TestTaskReports>
Action<? super TestTaskReports>配置此任务可能生成的报告。
AbstractTestTask setTestNameIncludePatterns(List<String>
List<String>设置要包含在执行中的测试名称模式。支持类名或方法名，支持通配符 '*'。有关更多信息，请参阅测试的用户指南章节。有关支持模式的更多信息，请参阅 TestFilter
void useJUnit(Closure testFrameworkConfigure)
指定应使用 JUnit4 来发现和执行测试，并进行额外配置。
提供的动作配置了 JUnitOptions 的实例。
void useJUnit(Action<? super JUnitOptions>
Action<? super JUnitOptions>指定应使用 JUnit4 来发现和执行测试，并进行额外配置。
提供的动作配置了 JUnitOptions 的实例。
指定应使用 JUnit Platform 来发现和执行测试。
如果您的测试使用 JUnit Jupiter/JUnit5，请使用此选项。
JUnit Platform 支持多个测试引擎，这允许在其之上构建其他测试框架。即使您不直接使用 JUnit，也可能需要使用此选项。
void useJUnitPlatform(Action<? super JUnitPlatformOptions>
Action<? super JUnitPlatformOptions>指定应使用 JUnit Platform 来发现和执行测试，并进行额外配置。
如果您的测试使用 JUnit Jupiter/JUnit5，请使用此选项。
JUnit Platform 支持多个测试引擎，这允许在其之上构建其他测试框架。即使您不直接使用 JUnit，也可能需要使用此选项。
提供的动作配置了 JUnitPlatformOptions 的实例。
void useTestNG(Closure testFrameworkConfigure)
指定应使用 TestNG 来发现和执行测试，并进行额外配置。
提供的动作配置了 TestNGOptions 的实例。
void useTestNG(Action<? super TestNGOptions>
Action<? super TestNGOptions>指定应使用 TestNG 来发现和执行测试，并进行额外配置。
提供的动作配置了 TestNGOptions 的实例。
设置进程的工作目录。提供的参数按照 Project.file(java.lang.Object) 进行评估。
配置测试框架特定选项。
当在测试套件外部创建 Test 任务时，在使用此方法之前，您应该调用 Test.useJUnit()、Test.useJUnitPlatform() 或 Test.useTestNG()。如果未设置测试框架，任务将假定为 JUnit4。
- 委托给
TestFrameworkOptions来自options