---
url: /reference/integrations/gradle-plugin.md
---

# 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.

::: tip Step-By-Step Instructions
See [our how-to](/howto/integrating-with-gradle/).
:::

\[\[toc]]

## `teamscale` Extension Options

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

:::: tabs key:gradle\_lang
\== Groovy

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

\== Kotlin DSL

```kotlin
teamscale {
    server {
        url = "https://mycompany.teamscale.io/"
        project = "my-project"
        userName = "build"
        userAccessToken = System.getProperty("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](/glossary/#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](/glossary/#java-timestamp-unix-timestamp) of the commit in Teamscale of current code. Prefer `commit.revision` if possible.                         |
| `baseline.timestamp` | `Property<Any>`    | The numerical [timestamp](/glossary/#java-timestamp-unix-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](https://docs.gradle.org/current/userguide/jvm_test_suite_plugin.html), aggregate reports and their tasks are automatically created for each test suite:

* testSuiteAggregateCompactCoverageReport - [`CompactCoverageReport`](#compactcoveragereport-task) that contains the coverage of all aggregated projects.
* testSuiteAggregateJUnitReport - `JUnitReportCollectionTask` that collects all the JUnit reports from all aggregated projects.
* testSuiteAggregateTestwiseCoverageReport - [`TestwiseCoverageReport`](#testwisecoveragereport-task) that collects all the binary testwise coverage data from all aggregated projects.

For a complete example including `TeamscaleUpload` registration, see [our how-to](/howto/integrating-with-gradle/#with-jvm-test-suites).

## TeamscaleUpload Task

The `TeamscaleUpload` task uploads reports to Teamscale.

:::: tabs key:gradle\_lang
\== Groovy

```groovy
import com.teamscale.TeamscaleUpload

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

\== Kotlin DSL

```kotlin
import com.teamscale.TeamscaleUpload

tasks.register<TeamscaleUpload>("teamscaleTestUpload") {
	partition = "Unit Tests"
	from(tasks.named("test"))
	from(tasks.named("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](../../upload-formats-and-samples/) to be uploaded                                                                                                                                                                                |

## `CompactCoverageReport` Task

This task is an alternative to `JaCoCoReport`, that produces [Compact Coverage](../../upload-formats-and-samples/teamscale-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.

:::: tabs key:gradle\_lang
\== Groovy

```groovy
import com.teamscale.reporting.compact.CompactCoverageReport

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

\== Kotlin DSL

```kotlin
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](../../upload-formats-and-samples/testwise-coverage/) 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.

:::: tabs key:gradle\_lang
\== Groovy

```groovy
import com.teamscale.reporting.testwise.TestwiseCoverageReport

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

\== Kotlin DSL

```kotlin
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.

:::: tabs key:gradle\_lang
\== Groovy

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

\== Kotlin DSL

```kotlin
import com.teamscale.extension.TeamscaleTaskExtension

tasks.register<Test>("unitTest") {
	configure<TeamscaleTaskExtension> {
		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 |

***
