Gradle plugin

This Gradle plugin supports automatically gathering and publishing the XML test results to the Projektor server. It listens to the end of the build, gathers up all the XML results generated by Test tasks in the build, then sends those to the Projektor server.

Example Projektor report from the plugin’s build: https://projektorlive.herokuapp.com/tests/8VQSLOBCSCWA

Use plugin

To apply this plugin to your project:

plugins {
  id "dev.projektor.publish" version "9.0.0"
}

See https://plugins.gradle.org/plugin/dev.projektor.publish for the latest version.

By default the plugin publishes results from all Test tasks in the project when the build finishes.

The plugin also adds a publishResults task that lets you publish test results from a build after it has executed (for example, if you didn’t have auto-publish on) This can be a good way to easily share a specific test failure with colleagues.

./gradlew publishResults

Note: If you have a multi-project build, please apply the plugin to the root project.

Configuration

All the configuration of the plugin is inside the projektor block. To use the plugin, first set the URL of the Projektor server:

projektor {
  serverUrl = "https://myserver"
}

You can also include results from arbitrary directories in your build with the additionalResultsDirs configuration option:

projektor {
  serverUrl = "https://myserver"
  additionalResultsDirs = ['build/testResultsDir']
}

Resiliency

The plugin includes configurable retry and timeout settings to help make publishing results to the Projektor server more resilient against network hiccups:

projektor {
  serverUrl = "https://myserver"
  publishRetryMaxAttempts = 3
  publishRetryInterval = 100
  publishTimeout = 10_000
}

Slack message

It can be helpful to proactively notify folks when a CI build fails via Slack. To help make that easier, the Projektor Gradle plugin has the option to write a formatted Slack message in a JSON file. This Slack message includes a direct link to the Projektor test report so users can quickly investigate test failures.

To use it, set the writeSlackMessageFile parameter to true.

By default, the Slack message is written to a file named projektor_failure_message.json, but you can specify your own file name by setting slackMessageFileName

Code coverage

Starting with plugin version 5.5.4 and server 3.5.1, Projektor has the ability to publish and visualize code coverage data as part of the Projektor report.

To include code coverage stats in your Projektor reports, first ensure you are using plugin version 5.5.4 or higher, enable Jacoco in your build, and include the jacocoTestReport task with your build. That’s it. The Projektor Gradle plugin will automatically configure, collect and upload the XML coverage reports from each project in the build that uses Jacoco.

For an example Projektor report with coverage, check out https://projektorlive.herokuapp.com/tests/SUWSHGIRS6JP/coverage

Ironically, this example build shows that the code coverage of the coverage parsing module in Projektor is low. Need to work on that.

Update: Coverage for the parsing module looking better now: https://projektorlive.herokuapp.com/tests/0M7BEOCS9VJA/coverage

Kover code coverage

Kover is a recent code coverage tool from JetBrains for the Kotlin language: https://github.com/Kotlin/kotlinx-kover

Starting in Projektor Gradle plugin 7.8.2 Projektor supports gathering and publishing reports from the Kover plugin when it is configured to use the Jacoco engine.

Projektor supports gathering Jacoco and Kover reports from different subprojects in a multi-project build. For example, you may have a multi-project build where some subprojects use Java so they gather code coverage with the Jacoco plugin and other Kotlin subprojects that use Kover for code coverage.

But don’t add both the Jacoco and Kover Gradle plugins in the same subproject, only use one or the other. Otherwise, you may get duplicate coverage reports in Projektor.

Key for using Kover coverage with Projektor:

• Use Projektor Gradle plugin 7.8.2 or higher
• Configure Kover to use the Jacoco engine
• Only have the Kover Gradle plugin in the project, don’t add the Jacoco Gradle plugin as well

Combining code coverage from multiple test tasks

Some projects have separate test tasks, such as test and integrationTest. Projektor will automatically collect coverage stats for all projects in a multi-project build, but if your project has multiple test tasks in the same project you’ll need a bit of extra configuration in your build.gradle file to have Jacoco combine the coverage data from the different test tasks before the coverage data is sent to the Projektor server:

// Combine the coverage data from the all test tasks into a single coverage report under the "jacocoTestReport" task
jacocoTestReport {
    dependsOn tasks.withType(Test)
    executionData { tasks.withType(Test)*.jacoco.destinationFile }
}

Code quality reports

Starting with Gradle plugin 7.5.1, Projektor supports any and all code quality tools (linting, static analysis, etc.) that can output their results in text files.

To be able to see the code quality reports in your Projektor build, pass the paths to the reports in the codeQualityReports plugin config parameter.

For example, to collect the text reports from the ktlint tool in a single-project Gradle build:

projektor {
    serverUrl = "https://myserver"
    codeQualityReports = [fileTree(dir: "build/reports/ktlint", include: "*.txt")]
}

Or to collect the reports from a Gradle multi-project build:

projektor {
    serverUrl = "https://myserver"
    codeQualityReports = [fileTree(dir: ".", include: "**/build/reports/ktlint/**/*.txt")]
}

All configuration options

** Required

Compatibility

Configure and apply via another plugin

In larger organizations it can be common to have base plugins that apply and configure a common set of plugins used by each project. To apply the ProjektorPublishPlugin this way from another plugin:

dependencies {
  api "dev.projektor.publish:dev.projektor.publish.gradle.plugin:9.0.0"
}

class MyPlugin implements Plugin<Project> {

    @Override
    void apply(Project project) {

        project.plugins.apply(ProjektorPublishPlugin)

        project.projektor {
            serverUrl = "https://myserver"
        }
    }
}

Changelog

• 9.0.0
  • Breaking change: Projektor Gradle plugin now requires Java 17+
• 8.7.0
  • Jackson and OkHttp updates
• 8.6.0
  • Updating dependencies
• 8.5.0
  • Upgrading to Gradle publish plugin 1.2.0
• 8.4.0
  • Adding support for Kover >= 0.6 in Gradle plugin
• 8.3.0
  • Breaking change: Projektor Gradle plugin now requires Gradle 7.6.1+
  • Updating to Kotlin 1.8.22
• 8.0.0
  • Breaking change: Projektor Gradle plugin now requires Gradle 7+
• 7.8.0
  • Adding support for Kover code coverage
• 7.7.0
  • Tweaking retry config in Gradle plugin to work with Java 17
• 7.6.0
  • Use non-deprecated report properties when available
• 7.5.2
  • Don’t log task-graph-not-ready stacktrace when executing Gradle task that doesn’t exist
• 7.5.1
  • Beefing up logging for code quality reports
• 7.5.0
  • Adding initial support for code quality reports
• 7.4.0
  • Adding support for code coverage in Gradle plugin publish task
• 7.3.0
  • Adding support for sending group name for appending results together
• 7.2.3
  • Improve handling of Gradle task graph not being ready yet
• 7.2.2
  • Guard against Gradle plugin failure when syncing project in IDE
• 7.2.1
  • Guard against Gradle plugin failure when syncing project in IDE
• 7.2.0
  • Sending pull request number from Gradle plugin
• 7.1.0
  • Passing Git commit SHA from Gradle plugin
• 7.0.0
  • Combining coverage results with test results in Gradle plugins
• 6.2.1
  • Removing deprecated AbstractTask from Gradle plugin
• 6.2.0
  • Adding coverage base file path
• 6.1.0
  • Compressing coverage reports in Gradle plugin for improved performance when sending them to the server
• 6.0.0
  • Always publish in CI from Gradle plugin
• 5.6.1
  • Don’t publish when no test results or coverage data
• 5.6.0
  • Passing is-CI flag from Gradle plugin to server
• 5.5.6
  • Adding wall clock duration to Gradle plugin
• 5.5.4
  • Making Gradle plugin backwards compatible with Gradle 5
• 5.5.3
  • Adding test report ID to results file written by Gradle plugin
• 5.5.2
  • Update Gradle plugin CI calculation to support CI env variable set to some arbitrary string value instead of just ‘true’
• 5.5.1
  • Always publish coverage report in CI
• 5.5.0
  • Always publish all coverage reports so comparisons are apples to apples
• 5.4.0
  • Writing file with link to report in Gradle plugin
• 5.2.0
  • Enabling publish by default in CI when code coverage is present
• 5.1.0
  • Initial support for Jacoco coverage stats
• 5.0.3
  • Upping failure stacktrace to info level for easier debugging
• 5.0.2
  • Adding support for writing Slack message to file
• 5.0.1
  • Adding configurable retries to Gradle plugin
• 5.0.0
  • Adding compression to the results call from the Gradle plugin
• 4.0.2
  • Don’t show large stacktrace on Gradle plugin post failure