Configuration

By default, CPT uses a runtime based on Testcontainers. You can customize the runtime to your needs, or replace it with a Remote runtime, for example, if you can't install a Docker runtime.

Testcontainers runtime

The default runtime of CPT is based on Testcontainers. It uses the Camunda Docker image and includes the following components:

• Camunda
• Connectors

Prerequisites

• A Docker-API compatible container runtime, such as Docker on Linux or Docker Desktop on Mac and Windows. If you're experiencing issues with your Docker runtime, have a look at the Testcontainers documentation.

Usage

You can change the Docker images and other runtime properties in the following way.

Camunda Spring Boot SDK

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

io:
  camunda:
    process:
      test:
        # Change the version of the Camunda Docker image
        camunda-docker-image-version: 8.8.0
        # Change the Camunda Docker image
        camunda-docker-image-name: camunda/camunda
        # Set additional Camunda environment variables
        camunda-env-vars:
          env_1: value_1
        # Expose additional Camunda ports
        camunda-exposed-ports:
          - 4567
        # Enable Connectors
        connectors-enabled: true
        # Change the Connectors Docker image
        connectors-docker-image-name: camunda/connectors
        # Change version of the Connectors Docker image
        connectors-docker-image-version: 8.8.0
        # Set additional Connectors environment variables
        connectors-env-vars:
          env_1: value_1
        # Set Connectors secrets
        connectors-secrets:
          secret_1: value_1

Java client

In your /camunda-container-runtime.properties file:

camundaDockerImageVersion=8.8.0
camundaDockerImageName=camunda/camunda
camundaEnvVars.env_1=value_1
camundaEnvVars.env_2=value_2
camundaExposedPorts[0]=4567
camundaExposedPorts[1]=5678

connectorsEnabled=true
connectorsDockerImageVersion=8.8.0
connectorsDockerImageName=camunda/connectors
connectorsEnvVars.env_1=value_1
connectorsEnvVars.env_2=value_2
connectorsSecrets.secret_1=value_1
connectorsSecrets.secret_2=value_2

Alternatively, you can register the JUnit extension manually and use the fluent builder:

package com.example;

import io.camunda.process.test.api.CamundaProcessTestExtension;
import org.junit.jupiter.api.extension.RegisterExtension;

// No annotation: @CamundaProcessTest
public class MyProcessTest {

    @RegisterExtension
    private static final CamundaProcessTestExtension EXTENSION =
        new CamundaProcessTestExtension()
            // Change the version of the Camunda Docker image
            .withCamundaDockerImageVersion("8.8.0")
            // Change the Camunda Docker image
            .withCamundaDockerImageName("camunda/camunda")
            // Set additional Camunda environment variables
            .withCamundaEnv("env_1", "value_1")
            // Expose additional Camunda ports
            .withCamundaExposedPort(4567)
            // Enable Connectors
            .withConnectorsEnabled(true)
            // Change the Connectors Docker image
            .withConnectorsDockerImageName("camunda/connectors")
            // Change version of the Connectors Docker image
            .withConnectorsDockerImageVersion("8.8.0")
            // Set additional Connectors environment variables
            .withConnectorsEnv("env_1", "value_1")
            // Set Connectors secrets
            .withConnectorsSecret("secret_1", "value_1");
}

Remote runtime

Instead of using the managed Testcontainers runtime, you can configure CPT to connect to a remote runtime, for example, to a local Camunda 8 Run running on your machine.

When to use it:

• You can't install a Docker-API compatible container runtime

info

You are in charge of the remote runtime. Make sure to start the runtime before running tests.

Prerequisites

• Expose the management API port (9600) to delete the data between the test runs (default for a local Camunda 8 Run)
• Enable the management clock endpoint to manipulate the clock

You can configure Camunda 8 Run by defining a application.yaml file with:

zeebe.clock.controlled: true

By default, Camunda 8 Run loads the application.yaml from the distribution's root directory. If you use a different path, then you need to set the path when starting the application with the command line argument --config=application.yaml:

./start.sh --config=application.yaml

Usage

Set the configuration to use a remote runtime in the following way. Change the connection to the runtime, if needed.

Camunda Spring Boot SDK

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

io:
  camunda:
    process:
      test:
        # Switch from a managed to a remote runtime
        runtime-mode: remote
        # Change the connection (default: Camunda 8 Run)
        remote:
          camunda-monitoring-api-address: http://0.0.0.0:9600
          connectors-rest-api-address: http://0.0.0.0:8085
          client:
            rest-address: http://0.0.0.0:8080
            grpc-address: http://0.0.0.0:26500

Java client

In your /camunda-container-runtime.properties file:

runtimeMode=remote
remote.camundaMonitoringApiAddress=http://0.0.0.0:9600
remote.connectorsRestApiAddress=http://0.0.0.0:8085
remote.client.grpcAddress=http://0.0.0.0:26500
remote.client.restAddress=http://0.0.0.0:8080

Alternatively, you can register the JUnit extension manually and use the fluent builder:

package com.example;

import io.camunda.process.test.api.CamundaProcessTestExtension;
import org.junit.jupiter.api.extension.RegisterExtension;

// No annotation: @CamundaProcessTest
public class MyProcessTest {

    @RegisterExtension
    private static final CamundaProcessTestExtension EXTENSION =
        new CamundaProcessTestExtension()
            // Switch from a managed to a remote runtime
            .withRuntimeMode(CamundaProcessTestRuntimeMode.REMOTE)
            // Change the connection (default: Camunda 8 Run)
            .withRemoteCamundaClientBuilderFactory(() -> CamundaClient.newClientBuilder()
                .usePlaintext()
                .restAddress(URI.create("http://0.0.0.0:8080"))
                .grpcAddress(URI.create("http://0.0.0.0:26500"))
            )
            .withRemoteCamundaMonitoringApiAddress(URI.create("http://0.0.0.0:9600"))
            .withRemoteConnectorsRestApiAddress(URI.create("http://0.0.0.0:8085"));
}

Logging

The test runtime uses SLF4J as the logging framework. If needed, you can enable the logging for the following packages:

• io.camunda.process.test - The test runtime (recommended level info)
• tc.camunda - The Camunda Docker container (recommended level error)
• tc.connectors - The connectors Docker container (recommended level error)
• org.testcontainers - The Testcontainers framework (recommended level warn)