| API 文件 | 測試 |
|---|
執行 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 的預設啟動類別路徑。 |
classpath | 用於執行測試的類別路徑。 |
debug | 確定是否為測試程序啟用偵錯。 啟用時 — |
debugOptions | 程序的 Java 偵錯線路協定屬性。 如果啟用，則 |
dryRun | 開發中 指示此任務是否將跳過個別測試執行。 |
enableAssertions | 如果為程序啟用斷言，則傳回 true。 |
environment | 用於程序的環境變數。 預設為此程序的環境。 |
excludes | 測試執行的排除模式。 |
executable | 要使用的可執行檔名稱。 |
failFast | 指示此任務是否將在第一個失敗的測試時失敗 |
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 偵錯線路協定屬性。 如果啟用 |
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
確定是否為測試程序啟用偵錯。 啟用時 — debug = true — 程序將在暫停狀態下啟動，並監聽 5005 端口。 偵錯時應停用並行測試執行，如果為 Test.getForkEvery() 使用非零值，則需要偶爾重新連接偵錯器。
自 Gradle 5.6 起，您可以通過 JavaForkOptions.debugOptions(org.gradle.api.Action) 設定端口和其他 Java 偵錯屬性。
- 預設值 (使用
java外掛程式時) false
JavaDebugOptions debugOptions (唯讀)
程序的 Java 偵錯線路協定屬性。 如果啟用，則 -agentlib:jdwp=... 將附加到 JVM 參數，並使用來自參數的設定。
注意：此屬性為開發中，並且可能會在 Gradle 的未來版本中變更。
指示此任務是否將跳過個別測試執行。
對於 JUnit 4 和 5，這將報告本應執行但跳過的測試。 對於 TestNG，這將報告本應執行但通過的測試。
僅支援支援原生空跑的 TestNG 版本，即 TestNG 6.14 或更高版本。
在分叉測試程序中執行的最大測試類別數。 當達到此限制時，將重新啟動分叉測試程序。
預設情況下，Gradle 在執行測試時會自動使用單獨的 JVM。
- 值
0（無限制）表示為所有測試類別重複使用測試程序。 這是預設值。 - 值
1表示為每個測試類別啟動新的測試程序。 這非常昂貴。 - 值
N表示在N個測試類別後啟動新的測試程序。
由於停止和啟動每個測試程序的成本，此屬性可能會對效能產生很大的影響。 從預設值更改此屬性是不尋常的。
- 預設值 (使用
java外掛程式時) 0
List<CommandLineArgumentProvider>jvmArgumentProviders (唯讀)
List<CommandLineArgumentProvider>要分叉的 java 程序的命令列參數提供者。
- 預設值 (使用
java外掛程式時) []
要並行啟動的最大測試程序數。
預設情況下，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
編譯後測試原始碼的目錄。
- 預設值 (使用
java外掛程式時) project.sourceSets.test.output.classesDirs
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 實例作為參數傳遞給閉包。
此方法也會在所有測試套件執行後調用。提供的描述符將具有 null 父套件。
void afterTest(Closure closure)
新增一個閉包，以便在測試執行後收到通知。 TestDescriptor 和 TestResult 實例作為參數傳遞給閉包。
void beforeSuite(Closure closure)
新增一個閉包，以便在測試套件執行前收到通知。 TestDescriptor 實例作為參數傳遞給閉包。
此方法也會在任何測試套件執行之前調用。提供的描述符將具有 null 父套件。
void beforeTest(Closure closure)
新增一個閉包，以便在測試執行前收到通知。 TestDescriptor 實例作為參數傳遞給閉包。
Test copyTo(JavaForkOptions target)
將這些選項複製到給定的選項。
Test copyTo(ProcessForkOptions target)
將這些選項複製到給定的目標選項。
void debugOptions(Action<JavaDebugOptions>
Action<JavaDebugOptions>設定程序的 Java 偵錯線路協定屬性。 如果啟用 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 來探索和執行測試，並帶有其他設定。
提供的 action 會配置一個 JUnitOptions 的實例。
void useJUnit(Action<? super JUnitOptions>
Action<? super JUnitOptions>指定應使用 JUnit4 來探索和執行測試，並帶有其他設定。
提供的 action 會配置一個 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，您可能也需要使用此選項。
提供的 action 會配置一個 JUnitPlatformOptions 的實例。
void useTestNG(Closure testFrameworkConfigure)
指定應使用 TestNG 來探索和執行測試，並帶有其他設定。
提供的 action 會配置一個 TestNGOptions 的實例。
void useTestNG(Action<? super TestNGOptions>
Action<? super TestNGOptions>指定應使用 TestNG 來探索和執行測試，並帶有其他設定。
提供的 action 會配置一個 TestNGOptions 的實例。
設定程序的工作目錄。 提供的參數會根據 Project.file(java.lang.Object) 進行評估。
設定測試框架特定選項。
當在測試套件外部建立 Test 任務時，您應該在使用此方法之前調用 Test.useJUnit()、 Test.useJUnitPlatform() 或 Test.useTestNG()。如果沒有設定測試框架，則任務將假設為 JUnit4。
- 委派至
TestFrameworkOptionsfromoptions