Skip to content

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:

GoalDescription
prepare-tia-unit-testInstruments Surefire unit tests to run impacted tests and collect Testwise Coverage
prepare-tia-integration-testInstruments Failsafe integration tests to run impacted tests and collect Testwise Coverage
testwise-coverage-reportConverts binary data produced during the tests to testwise coverage reports
upload-coverageUploads JaCoCo and Testwise Coverage reports to Teamscale
helpDisplays help information for the plugin

Usage

Add the plugin to your Maven POM file:

xml
<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/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:

xml

<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

xml
<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:
xml
<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.

xml
<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

ParameterDescriptionRequired
teamscaleUrlURL of your Teamscale instanceYes
projectIdID of your Teamscale projectYes
usernameUsername for Teamscale authenticationYes
accessTokenAccess token for Teamscale authenticationYes

Commit and Revision Specification

ParameterDescriptionDefault
commitOverride the commit to upload coverage to (format: BRANCH:UNIX_EPOCH_TIMESTAMP_IN_MILLISECONDS)Auto-detected Git commit
revisionOverride the revision to upload coverage toAuto-detected Git revision
repositoryRepository ID in Teamscale for revision lookupAll repositories in project

Code Coverage Control

ParameterDescriptionDefault
includesPatterns for code to include in coverage instrumentationNo default
excludesPatterns for code to exclude from coverage instrumentationNo default

Test Execution Control

ParameterDescriptionDefault
runImpactedWhether to execute only impacted teststrue
runAllTestsWhether to execute all tests regardless of impactfalse
skipWhether to skip the execution of the goalfalse
`

Goal-Specific Parameters

TIA Configuration (prepare-tia-unit-test and prepare-tia-integration-test)

ParameterDescriptionDefault
unitTestPartitionPartition name for unit test reports (prepare-tia-unit-test only)"Unit Tests"
integrationTestPartitionPartition name for integration test reports (prepare-tia-integration-test only)"Integration Tests"
propertyNameProperty name for JVM argumentsargLine/spring-boot.run.jvmArguments/tycho.testArgLine
additionalAgentOptionsAdditional options for the Teamscale JaCoCo agentNone
agentPortPort for Java agent communicationAuto-selected
debugLoggingEnable DEBUG level logging for the agentfalse
baselineCommitBaseline for impact analysisNone
baselineRevisionVCS revision for baselineNone

Testwise Coverage Converter (testwise-coverage-converter)

ParameterDescriptionDefault
includesWildcard include patterns for JaCoCo class traversal**
excludesWildcard exclude patterns for JaCoCo class traversalNone
splitAfterNumber of tests after which to split coverage into multiple reports5000

Coverage Upload (upload-coverage)

ParameterDescriptionDefault
unitTestPartitionPartition name for unit test reports"Unit Tests"
integrationTestPartitionPartition name for integration test reports"Integration Tests"
aggregatedTestPartitionPartition name for aggregated test reports"Aggregated Tests"