Parallel Tests

The Parallel Tests build feature breaks test suites down into multiple batches and assigns each batch to a separate build agent, all running in parallel. The larger your test suite is and the more batches you configure, the more dramatic and noticeable this performance boost is.

For Maven, Gradle, IntelliJ IDEA Project, and .NET build steps, you do not need to do anything beyond adding this feature and choosing the desired number of batches. TeamCity will handle tests filtering automatically.

For other runners, additional setup is required. See the Custom execution of parallelized tests section and the Using the Parallel Tests build feature with any build runner knowledge base article for more information.

Run tests in parallel

The Parallel tests build feature solves the task of parallel tests execution on different agents.

To enable this feature in an existing build configuration:

Open configuration settings and navigate to the Build Features settings tab.
Click Add build feature and choose the Parallel tests type.
Set the number of test batches, which also means the number of parallel agents to use in a build.

Before TeamCity splits tests into batches to run in parallel, it needs to gather test statistics of at least one preceding build. This information helps subdivide tests in semi-equally sized batches (based on tests duration) so that the total build time is as short as possible. If you enable this feature in a freshly added build configuration, its first build will run in the normal mode; when it finishes and produces test reports, TeamCity will be able to split the second one.

TeamCity takes into account not only the latest tests run, but also the history of your tests: the next builds with parallel tests will also contribute to this statistics and allow TeamCity to make smarter decisions.

Under the hood

If the test statistics is available, then the following happens when a new build is triggered:

TeamCity generates copies of the current build configuration according to the number of batches specified in the build feature. These build configurations will have the same build steps as the original one. In the future, the changes to the build steps of the original configuration will be propagated to the generated ones automatically.
The triggered build will be transformed into a composite build with dependencies on the builds from the generated build configurations.
As soon as the first dependency build starts, the composite build will start too.

A build of a generated build configuration will run the same set of build steps as defined in the original build configuration. If some of these steps are of the Maven, Gradle, IntelliJ IDEA Project, or .NET type, and they were executing some tests, then these build runners will automatically run only the fraction of the tests corresponding to the current batch.

If you run tests differently, you can still enable the Parallel tests build feature for your configuration and benefit from automatic test division: you will obtain the information about the tests to execute from the build parameters that will be provided by the build feature.

Runner-specific requirements

Automatic execution of a batch of tests instead of the whole set of tests is only supported if the following requirements are met:

Maven
- Maven minimal supported version: 3.x.
- Maven Surefire plugin minimal supported version: 2.13.
- Maven Failsafe Plugin minimal supported version: 2.13.
Gradle
- Gradle minimal supported version: 5.0.
.NET
- Microsoft.NET.Test.Sdk minimal supported version: 16.0.

Custom execution of parallelized tests

In some workflows, TeamCity cannot split tests into batches because it does not control test execution. For example, when tests are generated dynamically, reported by a custom build step, or imported from a file.

Still, TeamCity tracks executed tests and analyzes previous runs to calculate the optimal batch distribution. This data is available via the following parameters:

teamcity.build.parallelTests.currentBatch — current batch number (starting from 1).
teamcity.build.parallelTests.totalBatches — total number of batches.
system.teamcity.build.parallelTests.excludesFile — the path on the agent machine to the excludesFile.txt file that stores information on which tests should be disabled when the currentBatch is running.

To run tests in parallel, implement a custom mechanism (such as a test framework extension or build step) that reads these parameters and disables tests that do not belong to the current batch.

The excludesFile file is generated by the TeamCity server and should not be manually modified. This file has the following format:

#version=<value>
#algorithm=<value>
#current_batch=<value>
#total_batches=<value>
#suite=<value1>
#suite=<value2>
...
<newline-separated list of test classes>

version

An integer value that is the file format version. It is implied that the custom tests execution logic checks the version and reports an error or fails a build if the version has an unexpected value.

algorithm

The type of the algorithm responsible for breaking down tests into batches. Available values:

DURATION — prioritizes the execution time of test classes as the primary metric to create batches with approximately equal runtime.
SPLIT_SUITE — splits each test class within a test suite into N batches.
GROUP_SUITES — same as DURATION but groups all tests from the same suite into a single batch, ignoring individual test classes.

current_batch

The number of the current batch, same as teamcity.build.parallelTests.currentBatch parameter.

total_batches

The total number of batches, same as teamcity.build.parallelTests.totalBatches parameter.

suite

The test suite name. This parameter may be empty. If a batch includes tests from multiple suites, each suite is listed on a separate line.

Note: Java and .NET test frameworks usually report tests to TeamCity in the following format:

[<suite name>: ]<fully qualified test class name>.<test method>[<test arguments>]

Where <suite name> and <test arguments> are optional and not always present.

For example, the following Java Test class:

package org.example.tests;

class TestCase1 {

  public void testMethod1() { /* ... */ }

  public void testMethod2() { /* ... */ }
}

will produce the following test names in TeamCity:

org.example.tests.TestCase1.testMethod1
org.example.tests.TestCase1.testMethod2

Then the parameter system.teamcity.build.parallelTests.excludesFile will point to a text file with the following content:

#version=1
#current_batch=1
#total_batches=3
#suite=
org.example.tests.TestCase1

Alternative Test Filtering for .NET

If the .NET runner handles a large amount of test classes, parallel testing may produce huge test filters that are hard to parse and consume for test engines like NUnit.

To avoid potential performance issues, TeamCity automatically employs an alternative test filtering mode optimized for these cases. This mode is enabled on a per-agent basis if the following conditions are met:

An agent that runs a test batch reports .NET CLI (SDK or runtime) 6.0 or newer.
A test batch has 1000 or more test classes. You can change this threshold value via the teamcity.internal.dotnet.test.suppression.test.classes.threshold configuration parameter.

You can prevent TeamCity from switching to this mode and force it to always run parallel .NET tests using the regular filtering mechanism in any individual project or build configuration. To do so, add the teamcity.internal.dotnet.test.suppression=false parameter to the required configuration or project.

Publish Artifacts Produced By Batch Builds

Since parallel tests run inside independent batch builds, artifacts are produced by these batch builds that perform actual building routines, not by a parent configuration's builds. To make them easily accessible, TeamCity aggregates artifacts from individual batches into the main configuration build.

When batch builds produce identical artifacts, only the latest batch build's artifacts are shown in the Artifacts tab of a parent configuration.

If all of these files are relevant and should be visible from the main build, enable the Artifacts setting of the Parallel Test feature.

object Build : BuildType({
    name = "Build"
    artifactRules = ".teamcity/Paralleltests/buildTypes => artifacts"

    // ...

    features {
        parallelTests {
            numberOfBatches = 2
            groupArtifactsByBuild = true
        }
    }
})

Doing so allows TeamCity to place batch outputs into "batchN" folders when aggregating them in a main configuration build.

You can implement a custom grouping logic by adding parameters to artifact paths. A parameter should have a unique value for each batch. For example, adding the teamcity.build.parallelTests.currentBatch parameter produces the results similar to the aforementioned setting of the Parallel Tests feature.

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildFeatures.parallelTests

object Build : BuildType({
    // ...
    artifactRules = "GithubAssets/reports => Artifacts/%teamcity.build.parallelTests.currentBatch%"
    // ...
})

Parallel Tests in Upstream Chain Builds

The Always run new build behavior (the snapshot dependency Do not run new build if there is a suitable one setting disabled) affects only the main configuration build. Virtual build configurations that spawn dynamically when the Parallel Tests feature is used might still reuse their previous results. If no new repository commits were detected, only previously failed test batches run new builds, while successful batches are reused.

In the figure below, the "Composite Conf" configuration depends on "Maven App" configuration. The latter runs its tests in two parallel batches. Note that the main "Maven app" build #18 is triggered anew, whereas the dynamically spawned "Maven app 1" configuration reuses its previous successful build (#12).

You can force TeamCity to re-run all virtual configuration builds. In this case, even if no new repository commits were found, every individual test batch will run anew.

To do so, add the teamcity.internal.splitBuild.dependency.takeStartedBuildWithSameRevisions=false parameter to the configuration with the parallel tests feature.

Known limitations

The Code coverage statistics will be inaccurate for builds with parallel tests because it will be collected for a fraction of tests executed by the current batch.
A newly added test which is not yet known to TeamCity will run in each batch during the first run. Related YouTrack ticket: TW-75913.
When TeamCity divides tests into batches, it only takes into account the duration of the test itself. The duration of setUp/tearDown or any other preparation methods is not know to TeamCity, therefore the duration of batches may not be equal.
An agent selected in the custom build dialog for a build with parallel tests will be ignored because the build will be transformed into a composite one after triggering. Related YouTrack ticket: TW-74905.
Parameters published by the build steps via the setParameter service message, as well as runner specific parameters, such as maven.project.version, won't be available in a composite build with parallel tests. Related YouTrack ticket: TW-75249.
When it comes to the build configurations limit in the TeamCity Professional version, the automatically generated build configurations are counted as normal build configurations.

Known bugs

The Enforce Clean Checkout action does not work for build configurations with parallel tests configured. Related YouTrack ticket: TW-75337.
In Gradle, batch builds spawned to run TestNG tests from an XML suite run all tests instead of a specified subset of tests. Related YouTrack ticket: TW-75849.
In Maven with TestNG, XML suite files are ignored. Related YouTrack ticket: TW-95644.

27 August 2026