Teamscale Maven Plugin

The Teamscale Maven Plugin provides integration between Maven-based builds and Teamscale.

Overview

The plugin offers the following main features:

1. Test Impact Analysis (TIA) – Automatically fetches and executes only impacted tests
2. Testwise Coverage Recording – Records coverage data per test case
3. 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.2</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/or prepare-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).
• Surefire Version: TIA only supports Surefire versions >= 3.1.0
• 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 the propertyName 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"