Testcontainer timeout with CPT

Camunda 8 Topics
1

I am using the brand new Camunda Process Test library (with the CamundaSpringProcessTest annotation). And I wrote a simple test, just to check a process instance is running. It works perfectly when running locally (through Maven). But it fails (mostly, but sporadically it succeeds) in my deploy pipeline.

My project is a simple SpringBoot (3.5.7) using Maven and Camunda 8.8. And I have the pipeline in question running om Gitlab (a self-managed instance beyound my direct control). The pipeline is set up to just run all the test before aloving any MerrgeRequest. And the Gitlab runner is generously sized in memory (32GB ram).

As I understand the CPT is using Testcontainers “under the hood”. And I also see that in the logs. And my theory is that the Camunda testcontainer is so big it causes timeouts. Because I see in my logs (from the pipeline) that the testcontainer seems to fail starting due to timeout exceptions. But when I rerun the same pipeline it will work like 1 of 10 times.

Anyone else experienced a similiar problem?

2

Hi @hakanostrom!

You’re absolutely right about your theory - this is a known issue with the Camunda Process Test (CPT) library when using Testcontainers in CI/CD environments like GitLab. Several users have reported similar timeout and performance issues, particularly in pipeline environments.

Root Cause

CPT uses Testcontainers by default, which spins up the full Camunda Docker image for each test run. In CI environments, this can be problematic due to:

  • Container startup/pull being slow (network, Docker-in-Docker overhead)
  • Resource contention even with generous memory allocation
  • Testcontainer startup timeouts in constrained CI environments

Recommended Solution: Switch to Remote Runtime

The most effective solution is to configure CPT to use remote runtime instead of Testcontainers. This way, you start Camunda as a separate service in your pipeline and CPT just connects to it.

Step 1: Configure your GitLab CI pipeline

Add a Camunda service to your .gitlab-ci.yml:

test:
  services:
    - name: camunda/camunda:8.8.0
      alias: camunda
  variables:
    CAMUNDA_ZEEBE_GATEWAY_NETWORK_HOST: "0.0.0.0"
  script:
    - mvn test

Step 2: Configure CPT for remote runtime

In your application-test.yml (or test properties):

camunda:
  process-test:
    runtime-mode: remote
    zeebe:
      gateway-address: camunda:26500
    # Add other connection details as needed

Your test class stays the same:

@SpringBootTest
@CamundaSpringProcessTest
public class MyProcessTest {
    // Your existing test code
}

Alternative: Optimize Testcontainers (if you must keep it)

If switching to remote runtime isn’t feasible, you can optimize the Testcontainers setup:

camunda:
  process-test:
    camunda-docker-image-name: camunda/camunda
    camunda-docker-image-version: 8.8.0
    connectors-enabled: false  # Reduces startup time

You can also adjust assertion timeouts for slower CI environments:

CamundaAssert.setAssertionTimeout(Duration.ofMinutes(1));

Why This Happens

The CPT with Testcontainers is significantly slower than the old Zeebe Process Test library, and many users have reported longer pipeline times after migration. The remote runtime approach eliminates the container startup overhead entirely.

References:

Let me know if you need help with the specific GitLab CI configuration or if you run into any issues with the remote runtime setup!