Teamscale Gradle Plugin

The Teamscale Gradle Plugin is split into two cooperating pieces.

• The com.teamscale plugin, applied to each subproject, instruments individual test tasks: it attaches a coverage agent to the JVM, collects execution data per test, and optionally enables Test Impact Analysis so only tests affected by recent changes are run.
• The com.teamscale.aggregation plugin, applied once at a project that depends on all projects from which data should be aggregated (e.g. the root project or the application project), acts as a collection point: it pulls the coverage and JUnit XML produced by all projects it depends on (also transitively), merges them into a single report per test suite, and exposes TeamscaleUpload tasks that send those merged reports to the Teamscale server.

Step-By-Step Instructions

See our how-to.

• teamscale Extension Options
  • server
  • Optional commit and baseline properties
• Automatically Created Aggregation Tasks for JVM Test Suites
• TeamscaleUpload Task
  • Properties & Methods
• CompactCoverageReport Task
  • Properties & Methods
• TestwiseCoverageReport Task
  • Properties & Methods
• Test Extension (TeamscaleTaskExtension)
  • Properties

teamscale Extension Options

All options are configured inside the teamscale {} block. The server block is required; all other properties are optional:

teamscale {
    server {
        url = 'https://mycompany.teamscale.io/'
        project = 'my-project'
        userName = 'build'
        userAccessToken = property('teamscale.access-token')
    }
}

server

Property	Type	Description
url	String	Base URL of your Teamscale instance (e.g. https://mycompany.teamscale.io/)
project	String	The Teamscale project ID to upload data to
userName	String	The Teamscale user that performs the upload
userAccessToken	String	Access token for the user. Store it in a Gradle property to avoid hardcoding it in the build file.

Optional commit and baseline properties

By default, the plugin tries to detect the commit from CI environment variables or the local Git repository. The following environment variables are checked:

Variable	CI/CD System
COMMIT	Generic fallback
GIT_COMMIT	Jenkins (Git)
Build.SourceVersion	Azure DevOps
CIRCLE_SHA1	CircleCI
TRAVIS_COMMIT	Travis CI
BITBUCKET_COMMIT	Bitbucket Pipelines
CI_COMMIT_SHA	GitLab CI/CD
APPVEYOR_REPO_COMMIT	AppVeyor
GITHUB_SHA	GitHub Actions
SVN_REVISION	Jenkins (SVN)
build_vcs_number	TeamCity

If needed, you can manually specify a commit by using either a revision or branch and timestamp:

Property	Type	Description
commit.revision	Property<String>	The current commit revision (e.g., Git SHA1 hash or SVN revision).
commit.branchName	Property<String>	The branch name in Teamscale of current code. Prefer commit.revision if possible.
commit.timestamp	Property<Any>	The timestamp of the commit in Teamscale of current code. Prefer commit.revision if possible.
baseline.timestamp	Property<Any>	The numerical timestamp of the baseline commit (as obtained from the VCS history). Used to calculate impacted tests.
baseline.revision	Property<String>	Allows setting the baseline using a VCS revision (e.g., a Git SHA1) instead of a timestamp. Used to calculate impacted tests.
repository	Property<String>	Specifies the repository in which the commit.revision and baseline.revision should be resolved. Useful when multiple repositories exist in a Teamscale project.

Automatically Created Aggregation Tasks for JVM Test Suites

When using the JVM Test Suite Plugin, aggregate reports and their tasks are automatically created for each test suite:

• testSuiteAggregateCompactCoverageReport - CompactCoverageReport that contains the coverage of all aggregated projects.
• testSuiteAggregateJUnitReport - JUnitReportCollectionTask that collects all the JUnit reports from all aggregated projects.
• testSuiteAggregateTestwiseCoverageReport - TestwiseCoverageReport that collects all the binary testwise coverage data from all aggregated projects.

For a complete example including TeamscaleUpload registration, see our how-to.

TeamscaleUpload Task

The TeamscaleUpload task uploads reports to Teamscale.

import com.teamscale.TeamscaleUpload

tasks.register('teamscaleTestUpload', TeamscaleUpload) {
	partition = "Unit Tests"
	from(tasks.test)
	from(tasks.jacocoTestReport)
}

Properties & Methods

Property	Type	Description
partition	Property<String>	The partition to upload the report to (required)
message	Property<String>	Optional message to attach to the upload
ignoreFailures	Property<Boolean>	Whether the task should fail when the upload failed (default false)
from(task: Task/TaskProvider)		Adds the reports produced by the given task to the upload. Supported task types are Test (JUNIT) JaCoCoReport (JACOCO) CompactCoverageReport (TEAMSCALE_COMPACT_COVERAGE) TestwiseCoverageReport (TESTWISE_COVERAGE)
addReport(format: String, reports: Any)		Adds additional report files in the given format to be uploaded

CompactCoverageReport Task

This task is an alternative to JaCoCoReport, that produces Compact Coverage instead of a JaCoCo XML report. Compact Coverage is way smaller than JaCoCo and can be processed more efficiently by Teamscale.

When using the com.teamscale.aggregation plugin, you do not need to manually register these tasks. The CompactCoverage aggregation tasks automatically produce a compact coverage report.

import com.teamscale.reporting.compact.CompactCoverageReport

tasks.register("compactCoverageReport", CompactCoverageReport) {
    executionData(tasks.test)
    sourceSets(sourceSets.main)
}

Properties & Methods

Property	Type	Description
executionData	ConfigurableFileCollection	The JaCoCo execution data files (e.g., *.exec files) to process.
executionData(vararg tasks: Task)		Adds execution data generated by tasks with a JacocoTaskExtension for coverage analysis. Tasks without this extension are ignored.
executionData(vararg files: Any)		Adds one or more execution data files for coverage analysis.
classDirectories	ConfigurableFileCollection	The directories containing compiled classes to include in the coverage report.
sourceSets(vararg sourceSets: SourceSet)		Adds one or more source sets (class outputs) to be included in the report.
reports.compactCoverage.required	Property<Boolean>	Enable/disable generating the report.
reports.compactCoverage.outputLocation	RegularFileProperty	Destination of the generated report.

TestwiseCoverageReport Task

This task generates a Testwise Coverage report from the binary data produced by the Test task. The required binary data is produced when teamscale.collectTestwiseCoverage is enabled for the Test task. Testwise Coverage reports are required to perform Test Impact Analysis.

import com.teamscale.reporting.testwise.TestwiseCoverageReport

tasks.register("testwiseCoverageReport", TestwiseCoverageReport) {
    executionData(tasks.test)
	sourceSets(sourceSets.main)
}

Properties & Methods

Property	Type	Description
executionData	ConfigurableFileCollection	The binary data produced by the Test task to be converted.
executionData(vararg tasks: Task)		Sets the execution data, classDirectories and partial flag based on the given test task. Only tasks of type Test will be accepted.
classDirectories	ConfigurableFileCollection	The directories containing compiled classes to include in the coverage report.
sourceSets(vararg sourceSets: SourceSet)		Adds one or more source sets (class outputs) to be included in the report.
partial	Property<Boolean>	Indicates whether the tests were only partially executed. This is typically set via executionData(task).
reports.testwiseCoverage.required	Property<Boolean>	Enable/disable generating the report.
reports.testwiseCoverage.outputLocation	RegularFileProperty	Destination of the generated testwise coverage report.

Test Extension (TeamscaleTaskExtension)

Test Impact Analysis can be configured directly on Test tasks using the teamscale extension.

tasks.register('unitTest', Test) {
	teamscale {
		collectTestwiseCoverage = true
		runImpacted = true
		includeAddedTests = true
		includeFailedAndSkipped = true
		partition = "Unit Tests"
	}
}

Properties

Property	Type	Default	Description
collectTestwiseCoverage	Property<Boolean>	false	Enables testwise coverage collection
runImpacted	Property<Boolean>	false	Runs only tests impacted by changes
runAllTests	Property<Boolean>	false	Forces running all tests even when impacted mode is enabled
includeAddedTests	Property<Boolean>	true	Includes newly added tests when running in impacted mode
includeFailedAndSkipped	Property<Boolean>	true	Includes previously failed or skipped tests in impacted mode
partition	Property<String>	null	The partition name for the test data
debugLogging	Property<Boolean>	false	Enables debug logging for the Java profiler and the impacted test engine

---