# Interface TestLogging

All Known Subinterfaces:
  `TestLoggingContainer`

public interface TestLogging
Options that determine which test events get logged, and at which detail.

Since:
  1.1

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `events(Object... events)`
  Sets the events to be logged.
  `int`
  `getDisplayGranularity()`
  Returns the display granularity of the events to be logged.
  `Set<TestLogEvent>`
  `getEvents()`
  Returns the events to be logged.
  `TestExceptionFormat`
  `getExceptionFormat()`
  Returns the format to be used for logging test exceptions.
  `int`
  `getMaxGranularity()`
  Returns the maximum granularity of the events to be logged.
  `int`
  `getMinGranularity()`
  Returns the minimum granularity of the events to be logged.
  `boolean`
  `getShowCauses()`
  Tells whether causes of exceptions that occur during test execution will be logged.
  `boolean`
  `getShowExceptions()`
  Tells whether exceptions that occur during test execution will be logged.
  `boolean`
  `getShowStackTraces()`
  Tells whether stack traces of exceptions that occur during test execution will be logged.
  `boolean`
  `getShowStandardStreams()`
  Tells whether output on standard out and standard error will be logged.
  `Set<TestStackTraceFilter>`
  `getStackTraceFilters()`
  Returns the set of filters to be used for sanitizing test stack traces.
  `void`
  `setDisplayGranularity(int granularity)`
  Sets the display granularity of the events to be logged.
  `void`
  `setEvents(Iterable<?> events)`
  Sets the events to be logged.
  `void`
  `setEvents(Set<TestLogEvent> events)`
  Sets the events to be logged.
  `void`
  `setExceptionFormat(Object exceptionFormat)`
  Sets the format to be used for logging test exceptions.
  `void`
  `setExceptionFormat(TestExceptionFormat exceptionFormat)`
  Sets the format to be used for logging test exceptions.
  `void`
  `setMaxGranularity(int granularity)`
  Returns the maximum granularity of the events to be logged.
  `void`
  `setMinGranularity(int granularity)`
  Sets the minimum granularity of the events to be logged.
  `void`
  `setShowCauses(boolean flag)`
  Sets whether causes of exceptions that occur during test execution will be logged.
  `void`
  `setShowExceptions(boolean flag)`
  Sets whether exceptions that occur during test execution will be logged.
  `void`
  `setShowStackTraces(boolean flag)`
  Sets whether stack traces of exceptions that occur during test execution will be logged.
  `TestLogging`
  `setShowStandardStreams(boolean flag)`
  Sets whether output on standard out and standard error will be logged.
  `void`
  `setStackTraceFilters(Iterable<?> stackTraces)`
  Sets the set of filters to be used for sanitizing test stack traces.
  `void`
  `setStackTraceFilters(Set<TestStackTraceFilter> stackTraces)`
  Sets the set of filters to be used for sanitizing test stack traces.
  `void`
  `stackTraceFilters(Object... stackTraces)`
  Convenience method for `setStackTraceFilters(java.lang.Iterable)`.

- ## Method Details

  - ### getEvents

    @Internal Set<TestLogEvent> getEvents()
    Returns the events to be logged.
    Returns:
      the events to be logged
    Since:
      1.1

  - ### setEvents

    void setEvents(Set<TestLogEvent> events)
    Sets the events to be logged.
    Parameters:
      `events` - the events to be logged
    Since:
      4.0

  - ### setEvents

    void setEvents(Iterable<?> events)
    Sets the events to be logged.
    Parameters:
      `events` - the events to be logged
    Since:
      1.1

  - ### events

    void events(Object... events)
    Sets the events to be logged. Events can be passed as enum values (e.g. `TestLogEvent.FAILED`) or Strings (e.g. "failed").
    Parameters:
      `events` - the events to be logged
    Since:
      1.1

  - ### getMinGranularity

    @Internal int getMinGranularity()
    Returns the minimum granularity of the events to be logged. Typically, 0 corresponds to events from the Gradle-generated test suite for the whole test run, 1 corresponds to the Gradle-generated test suite for a particular test JVM, 2 corresponds to a test class, and 3 corresponds to a test method. These values may extend higher if user-defined suites or parameterized test methods are executed. Events from levels lower than the specified granularity will be ignored.

    The default granularity is -1, which specifies that test events from only the most granular level should be logged. In other words, if a test method is not parameterized, only events from the test method will be logged and events from the test class and lower will be ignored. On the other hand, if a test method is parameterized, then events from the iterations of that test method will be logged and events from the test method and lower will be ignored.

    Returns:
      the minimum granularity of the events to be logged
    Since:
      1.1

  - ### setMinGranularity

    void setMinGranularity(int granularity)
    Sets the minimum granularity of the events to be logged. Typically, 0 corresponds to events from the Gradle-generated test suite for the whole test run, 1 corresponds to the Gradle-generated test suite for a particular test JVM, 2 corresponds to a test class, and 3 corresponds to a test method. These values may extend higher if user-defined suites or parameterized test methods are executed. Events from levels lower than the specified granularity will be ignored.

    The default granularity is -1, which specifies that test events from only the most granular level should be logged. In other words, if a test method is not parameterized, only events from the test method will be logged and events from the test class and lower will be ignored. On the other hand, if a test method is parameterized, then events from the iterations of that test method will be logged and events from the test method and lower will be ignored.

    Parameters:
      `granularity` - the minimum granularity of the events to be logged
    Since:
      1.1

  - ### getMaxGranularity

    @Internal int getMaxGranularity()
    Returns the maximum granularity of the events to be logged. Typically, 0 corresponds to the Gradle-generated test suite for the whole test run, 1 corresponds to the Gradle-generated test suite for a particular test JVM, 2 corresponds to a test class, and 3 corresponds to a test method. These values may extend higher if user-defined suites or parameterized test methods are executed. Events from levels higher than the specified granularity will be ignored.

    The default granularity is -1, which specifies that test events from only the most granular level should be logged. Setting this value to something lower will cause events from a higher level to be ignored. For example, setting the value to 3 will cause only events from the test method level to be logged and any events from iterations of a parameterized test method will be ignored.

    Returns:
      the maximum granularity of the events to be logged
    Since:
      1.1

  - ### setMaxGranularity

    void setMaxGranularity(int granularity)
    Returns the maximum granularity of the events to be logged. Typically, 0 corresponds to the Gradle-generated test suite for the whole test run, 1 corresponds to the Gradle-generated test suite for a particular test JVM, 2 corresponds to a test class, and 3 corresponds to a test method. These values may extend higher if user-defined suites or parameterized test methods are executed. Events from levels higher than the specified granularity will be ignored.

    The default granularity is -1, which specifies that test events from only the most granular level should be logged. Setting this value to something lower will cause events from a higher level to be ignored. For example, setting the value to 3 will cause only events from the test method level to be logged and any events from iterations of a parameterized test method will be ignored.

    Note that since the default value of `getMinGranularity()` is -1 (the highest level of granularity) it only makes sense to configure the maximum granularity while also setting the minimum granularity to a value greater than -1.

    Parameters:
      `granularity` - the maximum granularity of the events to be logged
    Since:
      1.1

  - ### getDisplayGranularity

    @Internal int getDisplayGranularity()
    Returns the display granularity of the events to be logged. For example, if set to 0, a method-level event will be displayed as "Test Run > Test Worker x > org.SomeClass > org.someMethod". If set to 2, the same event will be displayed as "org.someClass > org.someMethod".

    -1 denotes the highest granularity and corresponds to an atomic test.

    Returns:
      the display granularity of the events to be logged
    Since:
      1.1

  - ### setDisplayGranularity

    void setDisplayGranularity(int granularity)
    Sets the display granularity of the events to be logged. For example, if set to 0, a method-level event will be displayed as "Test Run > Test Worker x > org.SomeClass > org.someMethod". If set to 2, the same event will be displayed as "org.someClass > org.someMethod".

    -1 denotes the highest granularity and corresponds to an atomic test.

    Parameters:
      `granularity` - the display granularity of the events to be logged
    Since:
      1.1

  - ### getShowExceptions

    @Internal boolean getShowExceptions()
    Tells whether exceptions that occur during test execution will be logged. Typically these exceptions coincide with a "failed" event. Defaults to true.
    Returns:
      whether exceptions that occur during test execution will be logged
    Since:
      1.1

  - ### setShowExceptions

    void setShowExceptions(boolean flag)
    Sets whether exceptions that occur during test execution will be logged. Defaults to true.
    Parameters:
      `flag` - whether exceptions that occur during test execution will be logged
    Since:
      1.1

  - ### getShowCauses

    @Internal boolean getShowCauses()
    Tells whether causes of exceptions that occur during test execution will be logged. Only relevant if `showExceptions` is `true`. Defaults to true.
    Returns:
      whether causes of exceptions that occur during test execution will be logged
    Since:
      1.1

  - ### setShowCauses

    void setShowCauses(boolean flag)
    Sets whether causes of exceptions that occur during test execution will be logged. Only relevant if `showExceptions` is `true`. Defaults to true.
    Parameters:
      `flag` - whether causes of exceptions that occur during test execution will be logged
    Since:
      1.1

  - ### getShowStackTraces

    @Internal boolean getShowStackTraces()
    Tells whether stack traces of exceptions that occur during test execution will be logged. Defaults to true.
    Returns:
      whether stack traces of exceptions that occur during test execution will be logged
    Since:
      1.1

  - ### setShowStackTraces

    void setShowStackTraces(boolean flag)
    Sets whether stack traces of exceptions that occur during test execution will be logged. Defaults to true.
    Parameters:
      `flag` - whether stack traces of exceptions that occur during test execution will be logged
    Since:
      1.1

  - ### getExceptionFormat

    @Internal TestExceptionFormat getExceptionFormat()
    Returns the format to be used for logging test exceptions. Only relevant if `showStackTraces` is `true`. Defaults to `TestExceptionFormat.FULL` for the INFO and DEBUG log levels and `TestExceptionFormat.SHORT` for the LIFECYCLE log level.
    Returns:
      the format to be used for logging test exceptions
    Since:
      1.1

  - ### setExceptionFormat

    void setExceptionFormat(TestExceptionFormat exceptionFormat)
    Sets the format to be used for logging test exceptions. Only relevant if `showStackTraces` is `true`. Defaults to `TestExceptionFormat.FULL` for the INFO and DEBUG log levels and `TestExceptionFormat.SHORT` for the LIFECYCLE log level.
    Parameters:
      `exceptionFormat` - the format to be used for logging test exceptions
    Since:
      4.0

  - ### setExceptionFormat

    void setExceptionFormat(Object exceptionFormat)
    Sets the format to be used for logging test exceptions. Only relevant if `showStackTraces` is `true`. Defaults to `TestExceptionFormat.FULL` for the INFO and DEBUG log levels and `TestExceptionFormat.SHORT` for the LIFECYCLE log level.
    Parameters:
      `exceptionFormat` - the format to be used for logging test exceptions
    Since:
      1.1

  - ### getStackTraceFilters

    @Internal Set<TestStackTraceFilter> getStackTraceFilters()
    Returns the set of filters to be used for sanitizing test stack traces.
    Returns:
      the set of filters to be used for sanitizing test stack traces
    Since:
      1.1

  - ### setStackTraceFilters

    void setStackTraceFilters(Set<TestStackTraceFilter> stackTraces)
    Sets the set of filters to be used for sanitizing test stack traces.
    Parameters:
      `stackTraces` - the set of filters to be used for sanitizing test stack traces
    Since:
      4.0

  - ### setStackTraceFilters

    void setStackTraceFilters(Iterable<?> stackTraces)
    Sets the set of filters to be used for sanitizing test stack traces.
    Parameters:
      `stackTraces` - the set of filters to be used for sanitizing test stack traces
    Since:
      1.1

  - ### stackTraceFilters

    void stackTraceFilters(Object... stackTraces)
    Convenience method for `setStackTraceFilters(java.lang.Iterable)`. Accepts both enum values and Strings.
    Since:
      1.1

  - ### getShowStandardStreams

    @Internal boolean getShowStandardStreams()
    Tells whether output on standard out and standard error will be logged. Equivalent to checking if both log events `TestLogEvent.STANDARD_OUT` and `TestLogEvent.STANDARD_ERROR` are set.
    Since:
      1.1

  - ### setShowStandardStreams

    TestLogging setShowStandardStreams(boolean flag)
    Sets whether output on standard out and standard error will be logged. Equivalent to setting log events `TestLogEvent.STANDARD_OUT` and `TestLogEvent.STANDARD_ERROR`.
    Since:
      1.1