1. Help Center
  2. Parallel Test Execution

Parallelize your tests efficiently with Turbo mode

Testcontainers Cloud Turbo mode allows you to run tests in parallel so that each test process receives its own cloud environment making tests parallelization scalable.

Parallelizing tests is one of the ways to speed up the execution of your build. 

Depending on the composition of a test suite, and compute resources available parallel tests might not improve performance due to bottlenecking on local compute resources. Testcontainers Cloud Turbo mode enables one cloud environment per process running  Testcontainers tests.

This means that increasing the number of processes simultaneously running tests doesn't increase the load on local compute resources linearly and the scalability of the cloud environment helps to run you tests faster. 

Turbo mode will benefit users who struggle with massive test suites which run longer than is acceptable. Here's how you can enable Testcontainers Cloud Turbo mode and configure your tests to run in parallel. 

Note that Turbo mode is currently restricted for Trial accounts, please consult the following page to learn more: https://knowledge.testcontainers.cloud/how-are-trial-accounts-restricted

Start using Turbo Mode with Testcontainers Cloud on Desktop

In the Testcontainers Cloud Desktop application you can select the checkbox Turbo mode to enable the mode locally.

Turn on Turbo mode in CI:

When starting the agent in CI specify the --max-concurrency=N flag to enable a maximum of N concurrent Testcontainers Cloud environments available to processes using this agent. 

The default value for --max-concurrency is 4. 

You can also configure the concurrency option via an environment variable TC_CLOUD_CONCURRENCY, for example setting: 


Now you're ready to run tests in parallel using scalability of Testcontainers Cloud. If you're new to running tests in parallel here's a quick instruction on how to try it with common build tools. 

How to turn on Turbo mode with a Java project using Gradle

To run tests in parallel with Gradle add maxParallelForks to the test task in your gradle.build file: 

test.maxParallelForks = 4

This will instruct Gradle to use up to 4 forked processes to run tests and if you configured Turbo mode, containers created in each fork will not overload the same Docker environment. 

If you would like to try Turbo mode on a Java project, consider using the sample project by following the instructions in its GitHub repo.

How to turn on Turbo mode with a Java project using Maven

If you're using Maven as your build tool, you're probably using Surefire plugin for test execution. Surefire plugin supports parallel test execution and you can read the docs on how to enable it. In general to run tests in parallel with Maven you can add the parallel and forkCount properties to the configuration of Maven Surefire or Failsafe plugins in your pom.xml. Note that you need a modern version of the Surefire plugin, here's a sample configuration for it:  


If you would like to try Turbo mode on a Java project, consider using the sample project by following the instructions in its GitHub repo.

How to verify that Turbo mode is enabled?

When you enabled Turbo mode for Testcontainers Cloud and parallel tests in your build tool, you should see multiple lease allocations in the connection tab of the Testcontainers Cloud application once you run your tests.

How does Testcontainers Cloud decide which containers to run in the same cloud environment?

We use sessions to distinguish containers, so the same process will connecting to the same cloud environment for example if a test needs to start several containers.

But a parallel process runs will receive a new cloud environment if the maximum concurrency configuration for the currently running Testcontainers Cloud agent allows creating more cloud environments. 

So if you have configured Turbo mode,  but only one test process, then all the containers used in the tests will run in the same cloud environment, even if you are running tests in parallel within one process.

If you have multiple test processes (for example forked JVMs), then with Turbo Mode each  JVM will, if possible, receive to a dedicated cloud environment.