Teamscale Maven Plugin
The Teamscale Maven Plugin provides integration between Maven-based builds and Teamscale.
Overview
The plugin offers the following main features:
- Test Impact Analysis (TIA) – Automatically fetches and executes only impacted tests
- Testwise Coverage Recording – Records coverage data per test case
- Coverage Upload – Uploads Testwise Coverage or JaCoCo coverage reports to Teamscale
Goals
The plugin provides the following goals:
Goal | Description |
---|---|
prepare-tia-unit-test | Instruments Surefire unit tests to run impacted tests and collect Testwise Coverage |
prepare-tia-integration-test | Instruments Failsafe integration tests to run impacted tests and collect Testwise Coverage |
testwise-coverage-report | Converts binary data produced during the tests to testwise coverage reports |
upload-coverage | Uploads JaCoCo and Testwise Coverage reports to Teamscale |
help | Displays help information for the plugin |
Usage
Add the plugin to your Maven POM file:
<project>
<properties>
<teamscale.plugin.version>35.0.0</teamscale.plugin.version>
</properties>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>com.teamscale</groupId>
<artifactId>teamscale-maven-plugin</artifactId>
<version>${teamscale.plugin.version}</version>
<configuration>
<teamscaleUrl>https://company.teamscale.io</teamscaleUrl>
<projectId>myProject</projectId>
<username>build</username>
<accessToken>myAccessToken</accessToken>
<includes>
<include>*com.company.*</include>
</includes>
<!-- More options see below -->
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
Check here for the latest version.
Test Impact Analysis
To perform Test Impact Analysis and/or collect Testwise Coverage you need to:
- Put the
impacted-test-engine
on the test classpath. This JUnit engine is responsible for querying Teamscale for impacted tests, makes sure to only run the returned subset of tests and informs the coverage profiler about when tests start and end. - Run the
prepare-tia-unit-test
and/orprepare-tia-integration-test
goals to attach the coverage profiler to the test JVM.
Apply those settings to all modules that contain relevant tests:
<project>
<dependencies>
<dependency>
<groupId>com.teamscale</groupId>
<artifactId>impacted-test-engine</artifactId>
<version>${teamscale.plugin.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>com.teamscale</groupId>
<artifactId>teamscale-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>prepare-tia-unit-test</goal>
<goal>prepare-tia-integration-test</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
You might also want to only add this conditionally. By moving the configuration into a profile you can enable TIA by running the build with -Dtia
<project>
<profiles>
<profile>
<id>tia</id>
<activation>
<property>
<name>tia</name>
</property>
</activation>
<!-- Configuration from above -->
</profile>
</profiles>
</project>
The profiler produces binary data that needs to be converted into a proper report before it can be uploaded to Teamscale. The testwise-coverage-report
goal is responsible for performing this conversion. The goal should only be run once, i.e., in your aggregator module (see below).
Limitations
- JUnit 5: The plugin only supports tests based on the JUnit Platform and frameworks built on it (e.g., Serenity).
- Parallel Tests: TIA does not support parallelized tests. Ensure Surefire and Failsafe use:
<forkCount>1</forkCount>
<threadCount>1</threadCount>
- Custom Test Execution: If your system-under-test is launched by means other than Surefire or Failsafe, ensure the
argLine
property is passed to that JVM. You can also use another property by specifying it via thepropertyName
configuration.
Upload to Teamscale
The upload to Teamscale should typically only happen once for the whole build. To achieve this with Maven, you need an aggregator module that has a dependency (directly or indirectly) on all modules of your project. If you intend to collect Testwise Coverage, apply the plugin with the testwise-coverage-report
goal in your aggregator module. If you intend to upload JaCoCo coverage, make sure to configure the JaCoCo Maven Plugin in the modules to generate XML reports.
<project>
<build>
<plugins>
<plugin>
<groupId>com.teamscale</groupId>
<artifactId>teamscale-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<!-- Only needed if you collect Testwise Coverage -->
<goal>testwise-coverage-report</goal>
<goal>upload-coverage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Common Configuration Parameters
Authentication and Connection
Parameter | Description | Required |
---|---|---|
teamscaleUrl | URL of your Teamscale instance | Yes |
projectId | ID of your Teamscale project | Yes |
username | Username for Teamscale authentication | Yes |
accessToken | Access token for Teamscale authentication | Yes |
Commit and Revision Specification
Parameter | Description | Default |
---|---|---|
commit | Override the commit to upload coverage to (format: BRANCH:UNIX_EPOCH_TIMESTAMP_IN_MILLISECONDS ) | Auto-detected Git commit |
revision | Override the revision to upload coverage to | Auto-detected Git revision |
repository | Repository ID in Teamscale for revision lookup | All repositories in project |
Code Coverage Control
Parameter | Description | Default |
---|---|---|
includes | Patterns for code to include in coverage instrumentation | No default |
excludes | Patterns for code to exclude from coverage instrumentation | No default |
Test Execution Control
Parameter | Description | Default |
---|---|---|
runImpacted | Whether to execute only impacted tests | true |
runAllTests | Whether to execute all tests regardless of impact | false |
skip | Whether to skip the execution of the goal | false |
` |
Goal-Specific Parameters
TIA Configuration (prepare-tia-unit-test
and prepare-tia-integration-test
)
Parameter | Description | Default |
---|---|---|
unitTestPartition | Partition name for unit test reports (prepare-tia-unit-test only) | "Unit Tests" |
integrationTestPartition | Partition name for integration test reports (prepare-tia-integration-test only) | "Integration Tests" |
propertyName | Property name for JVM arguments | argLine /spring-boot.run.jvmArguments /tycho.testArgLine |
additionalAgentOptions | Additional options for the Teamscale JaCoCo agent | None |
agentPort | Port for Java agent communication | Auto-selected |
debugLogging | Enable DEBUG level logging for the agent | false |
baselineCommit | Baseline for impact analysis | None |
baselineRevision | VCS revision for baseline | None |
Testwise Coverage Converter (testwise-coverage-converter
)
Parameter | Description | Default |
---|---|---|
includes | Wildcard include patterns for JaCoCo class traversal | ** |
excludes | Wildcard exclude patterns for JaCoCo class traversal | None |
splitAfter | Number of tests after which to split coverage into multiple reports | 5000 |
Coverage Upload (upload-coverage
)
Parameter | Description | Default |
---|---|---|
unitTestPartition | Partition name for unit test reports | "Unit Tests" |
integrationTestPartition | Partition name for integration test reports | "Integration Tests" |
aggregatedTestPartition | Partition name for aggregated test reports | "Aggregated Tests" |