// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[test_reporting_api]]
= Test Event Reporting API

The Test Event Reporting API allows you to capture test execution events programmatically and produce results similar to Gradle's built-in `Test` task.
It's particularly useful to integrate non-JVM test results into Gradle's testing infrastructure and publish them in Gradle's HTML test reports.

The API is primarily targeted at plugin developers and platform providers, with the link:{javadocPath}/org/gradle/api/tasks/testing/TestEventReporter.html[Javadoc] serving as the main reference.

WARNING: The Test Event Reporting API is incubating.

Let's take a look at a quick example that defines a custom Gradle task, `CustomTest`, which demonstrates how to capture and report test events:

====
include::sample[dir="snippets/tasks/customTest/groovy",files="src/main/java/com/example/CustomTest.java[]"]
====

<1> The `GroupTestEventReporter` is initialized to act as the root event reporter.
+
It creates directories for test results and reports under the project's build directory:
This establishes the reporting hierarchy.
+
*Nesting is supported*.
<2> The task uses JUnit Platform to dynamically discover and execute tests, *this would be replaced with your custom test system/platform*.
+
It selects the class `MyTest1` for testing.
+
JUnit’s `Launcher` is used to execute the tests and collect a summary of the results.
<3> The `TestEventReporter` is used to record detailed events for each test.
+
For each failure, the test is reported with metadata and marked as failed.
<4> Each test group (`junittest`) and the root (`root`) are finalized with success or failure based on the test results.

By using the Test Event Reporting API:

- **Integration**: Custom tests (even those outside JVM frameworks) can generate events compatible with Gradle's test reporting infrastructure.
- **Rich Metadata**: Developers can attach additional context (e.g., error messages or parent class details) to test events.
- **Consistency**: Results integrate seamlessly with Gradle’s HTML reports, making it easier to debug and understand test outcomes.

For a downloadable example, refer to the link:../samples/sample_custom_test_task.html[Custom Test Task Sample].
