# Interface TestEventReporter

All Superinterfaces:
  `AutoCloseable`

All Known Subinterfaces:
  `GroupTestEventReporter`

@Incubating public interface TestEventReporter extends AutoCloseable
Reports test events.

Since:
  8.12

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Close the generator.
  `default void`
  `failed(Instant endTime)`
  Emit a failure event for the test.
  `default void`
  `failed(Instant endTime, String message)`
  Emit a failure event for the test.
  `void`
  `failed(Instant endTime, String message, String additionalContent)`
  Emit a failure event for the test.
  `void`
  `metadata(Instant logTime, String key, String value)`
  Emit an event containing metadata about the test or test group currently being run.
  `void`
  `metadata(Instant logTime, Map<String,String> values)`
  Emit an event containing metadata about the test or test group currently being run.
  `void`
  `output(Instant logTime, TestOutputEvent.Destination destination, String output)`
  Emit an output event for the test.
  `void`
  `skipped(Instant endTime)`
  Emit a skipped event for the test.
  `void`
  `started(Instant startTime)`
  Emit a start event for the test.
  `void`
  `succeeded(Instant endTime)`
  Emit a successful completion event for the test.

- ## Method Details

  - ### started

    void started(Instant startTime)
    Emit a start event for the test. Can only be called once, and must be followed by a call to `succeeded(Instant)`, `skipped(Instant)`, `failed(Instant)`, or `failed(Instant, String)`.
    Parameters:
      `startTime` - the time the test started
    Since:
      8.12

  - ### output

    void output(Instant logTime, TestOutputEvent.Destination destination, String output)
    Emit an output event for the test. May be called multiple times. May not be called before `started(Instant)`.
    Parameters:
      `logTime` - the time the output was logged, must be between the start and end times of the test
      `destination` - the destination of the output
      `output` - some output from the test
    Since:
      8.12

  - ### metadata

    void metadata(Instant logTime, String key, String value)
    Emit an event containing metadata about the test or test group currently being run.

    Producers can supply the same value as the test start time to indicate that the metadata is "timeless", such as environment information that isn't tied to a specific point during test execution. Otherwise, the time should be between the start and end times of the test (inclusive), but this is not enforced.

    Keys should usually be unique within the scope of a single test, but this is not enforced.

    Parameters:
      `logTime` - the time the metadata was logged, should be between the start and end times of the test (inclusive)
      `key` - a key to identify the metadata
      `value` - the metadata value
    Since:
      9.4.0

  - ### metadata

    void metadata(Instant logTime, Map<String,String> values)
    Emit an event containing metadata about the test or test group currently being run. The metadata is a map containing potentially multiple key-value pairs to be reported to any consumer as a single event.

    Producers can supply the same value as the test start time to indicate that the metadata is "timeless", such as environment information that isn't tied to a specific point during test execution. Otherwise, the time should be between the start and end times of the test (inclusive), but this is not enforced.

    Keys should usually be unique within the scope of a single test, but this is not enforced.

    Parameters:
      `logTime` - the time the metadata was logged, should be between the start and end times of the test (inclusive)
      `values` - the key-value pairs
    Since:
      8.13

  - ### succeeded

    void succeeded(Instant endTime)
    Emit a successful completion event for the test. May not be called before `started(Instant)`.
    Parameters:
      `endTime` - the time the test completed
    Since:
      8.12

  - ### skipped

    void skipped(Instant endTime)
    Emit a skipped event for the test. May not be called before `started(Instant)`.
    Parameters:
      `endTime` - the time the test completed
    Since:
      8.12

  - ### failed

    default void failed(Instant endTime)
    Emit a failure event for the test. May not be called before `started(Instant)`.
    Parameters:
      `endTime` - the time the test completed
    Since:
      8.12

  - ### failed

    default void failed(Instant endTime, String message)
    Emit a failure event for the test. May not be called before `started(Instant)`.
    Parameters:
      `endTime` - the time the test completed
      `message` - the failure message
    Since:
      8.12

  - ### failed

    void failed(Instant endTime, String message, String additionalContent)
    Emit a failure event for the test. May not be called before `started(Instant)`.
    Parameters:
      `endTime` - the time the test completed
      `message` - the failure message
      `additionalContent` - additional content for the failure, like a stacktrace
    Since:
      8.12

  - ### close

    void close()
    Close the generator. No further events can be emitted after this.
    Specified by:
      `close` in interface `AutoCloseable`
    Since:
      8.12