Gradle 测试日志插件

一个用于在运行测试时在控制台上打印漂亮日志的 Gradle 插件。

截图

标准主题

Mocha 主题

向下滚动查看更多主题和自定义选项，或访问截图页面以获取更多演示。

使用方法

使用插件 DSL

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

使用传统插件应用方式

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

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

兼容性矩阵

测试日志插件版本	最低 Gradle 版本
1.x	4.x
2.x	5.x
3.x	6.5
4.x	7.6

配置

该插件在项目级别以及每个 Test 类型的任务中注册了一个名为 testlogger（全小写且为一个单词）的扩展。

以下显示了在未配置任何内容时应用的完整默认配置。

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

项目级别与任务级别配置

在项目级别配置的设置可以通过在任务级别重新定义来覆盖。任务级别未定义的设置将继承项目级别的值。考虑以下配置。

testlogger {
    theme 'mocha' // 项目级别
    slowThreshold 5000
}

test {
    testlogger {
        theme 'standard-parallel' // 任务级别
    }
}

在上面的示例中，有效的主题将是 standard-parallel，slowThreshold 将为 5000，而其他设置将保留其默认值。

在运行时覆盖设置

上述所有设置可以在 build.gradle 中指定，也可以在运行时使用系统属性设置，或者两者都使用。例如，我们可以在构建文件中将 theme 设置为 mocha，但可以在运行时通过在命令行上使用 -Dtestlogger.theme=standard 将其覆盖为 standard。由于它们是系统属性，我们有多种方式指定它们，包括 JAVA_OPTS 和 gradle.properties。

确定系统属性名称的约定是 testlogger.<配置设置>。
系统属性覆盖将在合并任务和项目级别设置后应用。
指定系统属性覆盖将对所有任务应用相同的设置，无论构建文件中定义了什么配置。

切换主题

testlogger {
    theme 'mocha'
}

当前支持以下主题：

plain - 不显示颜色或 Unicode 符号
standard - 显示颜色但不显示 Unicode 符号
mocha - 类似于 Mocha 的 spec 报告器打印的内容，带有颜色和 Unicode 符号
plain-parallel - 类似于 plain 主题，但支持并行测试执行
standard-parallel - 类似于 standard 主题，但支持并行测试执行
mocha-parallel - 类似于 mocha 主题，但支持并行测试执行

隐藏异常

默认情况下，showExceptions 标志是打开的。这会显示测试失败的原因，包括失败的位置。当然，你可以通过将 showExceptions 设置为 false 来关闭这种稍微详细的日志记录。

testlogger {
    showExceptions false
}

隐藏异常堆栈跟踪

有时只查看异常消息而不查看堆栈跟踪会很有用。这可以通过将 showStackTraces 设置为 false 来配置。

testlogger {
    showStackTraces false
}

隐藏异常原因

插件的默认行为是打印异常的所有原因。如果你觉得这太冗长，可以通过将 showCauses 设置为 false 来关闭它。

testlogger {
    showCauses false
}

显示完整的异常堆栈跟踪

就像 Gradle 本身一样，默认情况下只打印堆栈跟踪中最后一个与测试类名匹配的帧。对于绝大多数情况来说，这已经足够了。有时，为了查看整个堆栈跟踪，需要移除这个过滤。可以通过将 showFullStackTraces 设置为 true 来实现。

testlogger {
    showFullStackTraces true
}

定义慢速阈值

运行时间过长的测试将记录其持续时间。然而，"慢"是一个相对的术语，根据正在执行的测试类型、环境、项目类型和各种其他因素而有很大的差异。因此，你可以根据自己的需求定义你认为的慢速。

testlogger {
    slowThreshold 5000
}

slowThreshold 的默认值是 2 秒。因此，所有运行时间超过一秒的测试都会记录其实际执行时间。

如果你想完全关闭时间记录，只需将阈值设置为一个非常大的值。

请注意，在支持颜色的主题中，如果持续时间大于慢速阈值的一半，则会使用警告样式显示。例如，如果 slowThreshold 为 5 秒，那么运行时间超过 2.5 秒的任何测试都会使用警告样式记录其持续时间，而运行时间超过 5 秒的测试则使用错误样式。

隐藏摘要

默认情况下，会显示一个有用的摘要，其中包含通过、失败和跳过的测试的细分，以及执行所有测试所需的总时间。当然，如果你更喜欢简洁的输出，可以禁用此功能。

testlogger {
    showSummary false
}

显示简单名称

如果你不喜欢看到用于显示测试套件名称的长的、完全限定的类名，可以通过将以下标志设置为 true 来选择只显示简单名称。

testlogger {
    showSimpleNames true
}

显示标准流

可以使用以下配置控制标准输出和错误流与测试日志一起显示。

testlogger {
    showStandardStreams true
}

过滤标准流

如果启用了显示标准输出和错误流,它往往会产生太多输出,使人难以应付。幸运的是,我们可以根据测试结果的类型来过滤这些输出。

testlogger {
    showStandardStreams true
    showPassedStandardStreams false
    showSkippedStandardStreams false
    showFailedStandardStreams true
}

默认情况下,这三个过滤标志都是启用的。换句话说,如果启用了showStandardStreams但没有配置任何过滤标志,则不会过滤标准流输出。

如果将showStandardStreams设置为false,过滤标志将不起任何作用。

过滤测试结果

有时隐藏某种类型的测试结果会很有用。例如,如果一个应用程序有数百个测试,通过测试产生的大量输出可能足以掩盖任何有价值的测试失败。同样,可能需要隐藏跳过的测试,或者在极少数情况下甚至隐藏失败的测试。

我们可以使用以下设置来执行测试结果过滤。

testlogger {
    showPassed false
    showSkipped false
    showFailed true
    showOnlySlow false
}

默认情况下,showPassed、showSkipped和showFailed标志是打开的,而showOnlySlow是关闭的。如果你选择通过将showStandardStreams标志设置为true来显示标准流,被过滤掉的测试产生的任何输出都不会显示。

更改日志级别

默认情况下,结果以标准的lifecycle Gradle日志级别输出。这可以通过logLevel进行配置。例如,以下设置将在使用--quiet运行时也输出结果。

testlogger {
    logLevel 'quiet'
}

`testlogger`和`Test.testLogging`之间的关系

在可能的情况下,插件的testlogger扩展会尝试响应Gradle的Test.testLogging扩展的等效属性。但是,如果在testlogger扩展下明确配置了一个值,插件__不会__响应Test.testLogging的相应属性。下表更详细地演示了这一点。

属性	`Test.testLogging`值	`testlogger`值	有效值
`showStandardStreams`	`true`	未配置	`true`
`showStandardStreams`	`true`	`false`	`false`
`showStandardStreams`	`false`	`true`	`true`
`showExceptions`	`true`	未配置	`true`
`showExceptions`	`true`	`false`	`false`
`showExceptions`	`false`	`true`	`true`
`showStackTraces`	`true`	未配置	`true`
`showStackTraces`	`true`	`false`	`false`
`showStackTraces`	`false`	`true`	`true`
`showFullStackTraces`	`testLogging.exceptionFormat = FULL`	未配置	`true`
`showFullStackTraces`	`testLogging.exceptionFormat = SHORT`	未配置	`false`
`showFullStackTraces`	`testLogging.exceptionFormat = FULL`	`false`	`false`
`showFullStackTraces`	`testLogging.exceptionFormat = SHORT`	`true`	`true`
`showCauses`	`true`	未配置	`true`
`showCauses`	`true`	`false`	`false`
`showCauses`	`false`	`true`	`true`

换句话说,显式配置的testlogger属性,即使是false,也优先于Test.testLogging的任何值。

Kotlin DSL

如果你使用Kotlin DSL,testlogger扩展DSL的语法会略有变化。以下是使用Kotlin DSL样式的默认配置属性。

testlogger {
    theme = ThemeType.STANDARD
    showExceptions = true
    showStackTraces = true
    showFullStackTraces = false
    showCauses = true
    slowThreshold = 2000
    showSummary = true
    showSimpleNames = false
    showPassed = true
    showSkipped = true
    showFailed = true
    showOnlySlow = false
    showStandardStreams = false
    showPassedStandardStreams = true
    showSkippedStandardStreams = true
    showFailedStandardStreams = true
    logLevel = LogLevel.LIFECYCLE
}

关于Kotlin DSL的一个注意事项是,如果你有子项目试图使用与父项目不同的testlogger设置,语法会略有变化。

subprojects {

    apply {
        plugin("com.adarshr.test-logger")
    }

    configure<TestLoggerExtension> {
        theme = ThemeType.STANDARD
        showExceptions = true
        ...
    }
}

常见问题

它在Windows上可以工作吗?

大部分可以。standard和plain主题可以直接使用,但当使用mocha主题时,你可能需要对系统设置进行一些修改才能看到Unicode符号。

设置或更新JAVA_OPTS系统属性为-Dfile.encoding=UTF-8
通过执行chcp 65001将终端代码页更改为65001

如何在运行时禁用颜色和Unicode符号,例如在Jenkins控制台上?

你可以通过在Gradle命令行中添加--console=plain来关闭ANSI控制字符和Unicode符号。

它支持并行测试执行吗?

是的。不过你需要切换到合适的并行主题。这可以是plain-parallel、standard-parallel或mocha-parallel中的一个。并行主题专门设计用于maxParallelForks设置大于1的情况。它们通过牺牲对测试进行分组的能力来实现这一点,因此会失去一些可读性。

这个插件可以与junit-platform-gradle-plugin共存吗?

由于某些未知原因,junit-platform-gradle-plugin与gradle-test-logger-plugin不兼容。如果你仍在使用junit-platform-gradle-plugin,值得注意的是这个插件在JUnit Platform 1.2中被弃用,并在JUnit Platform 1.3中被移除。

然而,测试日志器插件完全兼容Gradle原生方式使用JUnit 5。