Gradle Test Logger Plugin

A Gradle plugin for printing beautiful logs on the console while running tests.

Screenshots

Standard theme

standard

Mocha theme

mocha

Scroll down for more themes and customisation options or visit the screenshots page for more demos.

Usage

Using the plugins DSL

plugins {
    id 'com.adarshr.test-logger' version '2.0.0'
}

Using legacy plugin application

buildscript {
    repositories {
        maven {
            url 'https://plugins.gradle.org/m2/'
        }
    }
    dependencies {
        classpath 'com.adarshr:gradle-test-logger-plugin:2.0.0'
    }
}

apply plugin: 'com.adarshr.test-logger'

Note: Test logger 2.x is incompatible with Gradle 4.x; please use test logger 1.7.1.

Configuration

The plugin registers an extension called testlogger (all lowercase and one word) at project level
as well as for each task of type Test.

The following shows the complete default configuration applied when you configure nothing.

testlogger {
    theme 'standard'
    showExceptions true
    showStackTraces true
    showFullStackTraces false
    showCauses true
    slowThreshold 2000
    showSummary true
    showSimpleNames false
    showPassed true
    showSkipped true
    showFailed true
    showStandardStreams false
    showPassedStandardStreams true
    showSkippedStandardStreams true
    showFailedStandardStreams true
}

Project vs task level configuration

Settings configured at the project level can be overridden by redefining them at task level. Settings
not defined at task level will inherit project level values. Consider the below configuration.

testlogger {
    theme 'mocha' // project level
    slowThreshold 5000
}

test {
    testlogger {
        theme 'standard-parallel' // task level
    }
}

In the above example, the effective theme will be standard-parallel and slowThreshold will be 5000 whereas rest of
the settings will retain their default values.

Overriding settings at runtime

All the above settings can either be specified in build.gradle or be set at runtime using system properties or both.
For instance, we could have theme set to mocha in the build file but it can be overridden to be standard at runtime
by using -Dtestlogger.theme=standard on the command line. Since they are system properties we have a number of ways of
specifying them including JAVA_OPTS and gradle.properties.

  • The convention used for determining the name of the system property is testlogger.<configuration setting>.
  • System property overrides will be applied after combining task and project level settings.
  • Specifying a system property override will apply the same setting for all tasks, regardless of any configuration
    defined in the build file.

Switch themes

testlogger {
    theme 'mocha'
}

The following themes are currently supported:

  1. plain - displays no colours or Unicode symbols
  2. standard - displays colours but no Unicode symbols
  3. mocha - similar to what Mocha's spec reporter
    prints, with colours and Unicode symbols
  4. plain-parallel - similar to the plain theme but supports parallel test execution
  5. standard-parallel - similar to the standard theme but supports parallel test execution
  6. mocha-parallel - similar to the mocha theme but supports parallel test execution

Hide exceptions

By default, the showExceptions flag is turned on. This shows why the tests failed including the location of the
failure. Of course, you can switch off this slightly more verbose logging by setting showExceptions to false.

testlogger {
    showExceptions false
}

Hide exception stack traces

Sometimes it is useful to just see the exception message instead of the stack trace. This can be configured by
setting showStackTraces to false.

testlogger {
    showStackTraces false
}

Hide exception causes

The default behaviour of the plugin is to print all the causes of the exception. If it is too verbose to your taste, you
can turn it off by setting showCauses to false.

testlogger {
    showCauses false
}

Show full exception stack traces

Just like Gradle itself, by default only the last frame that matches the test class's name in a stack trace is printed. For vast
majority of cases, that is sufficient. Sometimes, it is useful to remove this filtering in order to see the entirety of the stack
trace. This can be done by setting showFullStackTraces to true.

testlogger {
    showFullStackTraces true
}

Define slow threshold

Tests that are too slow will have their duration logged. However, "slow" is a relative terminology varying widely
depending on the type of tests being executed, environment, kind of project and various other factors. Therefore you
can define what you consider as slow to suit your needs.

testlogger {
    slowThreshold 5000
}

The default value of slowThreshold is 2 seconds. So all tests that take longer than a second to run will have their
actual execution time logged.

If you want to turn off the logging of time taken completely, simply set the threshold to a very large value.

Please note that in themes that support colours, the duration is displayed using a warning style if it is greater than
half the slow threshold. For instance, if slowThreshold is 5 seconds any tests that take longer than 2.5 seconds to
run would have their durations logged using a warning style and those that take longer than 5 seconds to run using an
error style.

Hide summary

By default, a useful summary containing a breakdown of passing, failing and skipped tests along with the total time
taken to execute all the tests is shown. Of course, you can disable this if you prefer a more succinct output.

testlogger {
    showSummary false
}

Show simple names

If you don't like seeing long, fully-qualified class names being used for displaying the test suite names, you can choose to
show only simple names by setting the below flag to true.

testlogger {
    showSimpleNames true
}

Show standard streams

The display of standard output and error streams alongside the test logs can be controlled using the below configuration.

testlogger {
    showStandardStreams true
}

Filter standard streams

If the display standard output and error streams is enabled, it can often produce too much output to overwhelm anyone.
Fortunately, we can filter this output based on the type of the test result.

testlogger {
    showStandardStreams true
    showPassedStandardStreams false
    showSkippedStandardStreams false
    showFailedStandardStreams true
}

All the three filter flags are enabled by default. In other words, the standard stream output is not filtered if
showStandardStreams is enabled but none of the filter flags are configured.

If showStandardStreams is set to false, the filter flags don't have any effect.

Filter test results

Sometimes it is useful to hide test results of a certain type. For instance, if an application has hundreds of tests, the
sheer volume of the output produced by passing tests could be enough to bury any valuable test failures. Similarly there
might be a need to hide skipped tests or in rare instances even the failed ones.

We can perform test result filtering by using the below settings.

testlogger {
    showPassed false
    showSkipped false
    showFailed true
}

By default all the above three flags are turned on. If you have chosen to display standard streams by setting
showStandardStreams flag to true, any output produced by filtered out tests will not be displayed.

Relationship between testlogger and Test.testLogging

Where possible, the plugin's testlogger extension tries to react to equivalent properties of Gradle's Test.testLogging
extension. However, if a value is explicitly configured under the testlogger extension, the plugin does not react to the
corresponding property of Test.testLogging. The below table demonstrates this in more detail.

Property Test.testLogging value testlogger value Effective value
showStandardStreams true not configured true
showStandardStreams true false false
showStandardStreams false true true
showExceptions true not configured true
showExceptions true false false
showExceptions false true true
showStackTraces true not configured true
showStackTraces true false false
showStackTraces false true true
showFullStackTraces testLogging.exceptionFormat = FULL not configured true
showFullStackTraces testLogging.exceptionFormat = SHORT not configured false
showFullStackTraces testLogging.exceptionFormat = FULL false false
showFullStackTraces testLogging.exceptionFormat = SHORT true true
showCauses true not configured true
showCauses true false false
showCauses false true true

In other words, an explicitly configured testlogger property, despite it being false, takes precedence over any
value of Test.testLogging.

GitHub