測試報告 API 允許您以程式化的方式捕獲測試執行事件,並產生類似於 Gradle 內建 `Test` 任務的結果。它特別適用於將非 JVM 測試結果整合到 Gradle 的測試基礎架構中,並將它們發布在 Gradle 的 HTML 測試報告中。

此 API 主要針對外掛開發人員和平台供應商,並以 Javadoc 作為主要參考資料。

讓我們來看一個快速範例,它定義了一個自訂的 Gradle 任務 `CustomTest`,示範如何捕獲和報告測試事件

src/main/java/com/example/CustomTest.java
package com.example;

import org.gradle.api.DefaultTask;
import org.gradle.api.file.ProjectLayout;
import org.gradle.api.tasks.TaskAction;
import org.gradle.api.tasks.testing.GroupTestEventReporter;
import org.gradle.api.tasks.testing.TestEventReporter;
import org.gradle.api.tasks.testing.TestEventReporterFactory;
import org.junit.platform.launcher.Launcher;
import org.junit.platform.launcher.LauncherDiscoveryRequest;
import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;
import org.junit.platform.launcher.core.LauncherFactory;
import org.junit.platform.launcher.listeners.SummaryGeneratingListener;
import org.junit.platform.launcher.listeners.TestExecutionSummary;

import javax.inject.Inject;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;

import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;

/**
 * A custom task that demonstrates the {@code TestEventReporter} API.
 */
public abstract class CustomTest extends DefaultTask {

    @Inject
    public abstract ProjectLayout getLayout();

    @Inject
    protected abstract TestEventReporterFactory getTestEventReporterFactory();


    @TaskAction
    void runTests() {
        try (GroupTestEventReporter root = getTestEventReporterFactory().createTestEventReporter(
            "root",
            getLayout().getBuildDirectory().dir("test-results/custom-test").get(),
            getLayout().getBuildDirectory().dir("reports/tests/custom-test").get()
        )) {
            root.started(Instant.now());

            List<String> failedTests = new ArrayList<>();

            try (GroupTestEventReporter junittest = root.reportTestGroup("CustomJUnitTestSuite")) {
                junittest.started(Instant.now());

                LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
                    .selectors(
                        selectClass(MyTest1.class)
                    )
                    .build();

                Launcher launcher = LauncherFactory.create();
                TestExecutionSummary summary = executeTests(launcher, request);

                summary.getFailures().forEach(result -> {
                    try (TestEventReporter test = junittest.reportTest(result.getTestIdentifier().getDisplayName(),
                        result.getTestIdentifier().getLegacyReportingName())) {
                        test.started(Instant.now());
                        String testName = String.valueOf(result.getTestIdentifier().getParentIdObject());
                        failedTests.add(testName);
                        test.metadata(Instant.now(),"Parent class:", String.valueOf(result.getTestIdentifier().getParentId().get()));
                        test.failed(Instant.now(), String.valueOf(result.getException()));
                    }
                });

                String failedTestsList = String.join(", ", failedTests);
                junittest.metadata(Instant.now(), "Tests that failed:", failedTestsList);

                if (summary.getTestsFailedCount() > 0) {
                    junittest.failed(Instant.now());
                } else {
                    junittest.succeeded(Instant.now());
                }
            }

            if (!failedTests.isEmpty()) {
                root.failed(Instant.now());
            } else {
                root.succeeded(Instant.now());
            }
        }
    }

    private TestExecutionSummary executeTests(Launcher launcher, LauncherDiscoveryRequest request) {
        // Use SummaryGeneratingListener to collect test execution data
        SummaryGeneratingListener listener = new SummaryGeneratingListener();
        launcher.registerTestExecutionListeners(listener);

        // Execute the tests
        launcher.execute(request);

        // Return the summary generated by the listener
        return listener.getSummary();
    }
}
  1. `GroupTestEventReporter` 被初始化為作為根事件報告器。

    它在專案的建置目錄下建立用於測試結果和報告的目錄

    這建立了報告階層。支援巢狀結構

  2. 此任務使用 JUnit Platform 動態發現和執行測試,這將被您的自訂測試系統/平台取代

    它選擇類別 `MyTest1` 進行測試。

    JUnit 的 `Launcher` 用於執行測試並收集結果摘要。

  3. `TestEventReporter` 用於記錄每個測試的詳細事件。

    對於每個失敗,測試都會連同元數據一起報告,並標記為失敗。

  4. 每個測試群組 (`junittest`) 和根 (`root`) 都會根據測試結果完成並標示為成功或失敗。

透過使用測試報告 API

  • 整合:自訂測試(即使是 JVM 框架之外的測試)也可以產生與 Gradle 測試報告基礎架構相容的事件。

  • 豐富的元數據:開發人員可以將額外的上下文(例如,錯誤訊息或父類別詳細資訊)附加到測試事件。

  • 一致性:結果與 Gradle 的 HTML 報告無縫整合,使其更容易除錯和理解測試結果。

有關 HTML 報告本身的更多詳細資訊,請參閱 JVM 測試文件

如需可下載的範例,請參考 自訂測試任務範例