Getting started

Camunda Process Test (CPT) is a Java library to test your BPMN processes and your process application.

CPT is based on JUnit 5 and Testcontainers. It provides a managed isolated runtime to execute your process tests on your local machine. The runtime uses the Camunda Docker images and includes the following components:

• Camunda (Zeebe, Operate, Tasklist)
• Connectors
• Elasticsearch

Disclaimer

CPT is in an alpha version.

For a mature testing library, take a look at Zeebe Process Test.

Limitations

CPT is in an early stage. It doesn't contain all features, and it is not optimized yet. Be aware of the following limitations:

• Slow test execution (~40 seconds per test case)
• Only basic assertions

Prerequisites

• Java 8+ / 17+ (for Spring SDK)
• JUnit 5
• A Docker-API compatible container runtime, such as Docker on Linux or Docker Desktop on Mac and Windows. If you have issues with your Docker runtime, have a look at the Testcontainers documentation.

Install

We have two variations of CPT: for the Spring SDK and the Camunda Java client. Choose the one depending on which library you use in your process application.

Add the following dependency to your Maven project:

Spring SDK

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-process-test-spring</artifactId>
  <scope>test</scope>
</dependency>

Java client

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-process-test-java</artifactId>
  <scope>test</scope>
</dependency>

Write a test

Create a new Java class with the following structure:

Spring SDK

package com.example;

import io.camunda.client.CamundaClient;
import io.camunda.client.api.response.ProcessInstanceEvent;
import io.camunda.process.test.api.CamundaAssert;
import io.camunda.process.test.api.CamundaProcessTestContext;
import io.camunda.process.test.api.CamundaSpringProcessTest;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
@CamundaSpringProcessTest
public class MyProcessTest {

    @Autowired private CamundaClient client;
    @Autowired private CamundaProcessTestContext processTestContext;

    @Test
    void shouldCompleteProcessInstance() {
        // given: the processes are deployed

        // when
        final ProcessInstanceEvent processInstance =
            client
                .newCreateInstanceCommand()
                .bpmnProcessId("my-process")
                .latestVersion()
                .send()
                .join();

        // then
        CamundaAssert.assertThat(processInstance).isCompleted();
    }
}

• @SpringBootTest is the standard Spring annotation for tests.
• @CamundaSpringProcessTest registers the Camunda test execution listener that starts and stops the test runtime.
• @Test is the standard JUnit 5 annotation for a test case.
• (optional) Inject a preconfigured CamundaClient to interact with the Camunda runtime.
• (optional) Inject a CamundaProcessTestContext to interact with the test runtime.
• (optional) Use CamundaAssert to verify the process instance state.

Java client

package com.example;

import io.camunda.client.CamundaClient;
import io.camunda.client.api.response.ProcessInstanceEvent;
import io.camunda.process.test.api.CamundaAssert;
import io.camunda.process.test.api.CamundaProcessTest;
import io.camunda.process.test.api.CamundaProcessTestContext;
import org.junit.jupiter.api.Test;

@CamundaProcessTest
public class MyProcessTest {

    // to be injected
    private CamundaClient client;
    private CamundaProcessTestContext processTestContext;

    @Test
    void shouldCompleteProcessInstance() {
        // given
        client
            .newDeployResourceCommand()
            .addResourceFromClasspath("my-process.bpmn")
            .send()
            .join();

        // when
        final ProcessInstanceEvent processInstance =
            client
                .newCreateInstanceCommand()
                .bpmnProcessId("my-process")
                .latestVersion()
                .send()
                .join();

        // then
        CamundaAssert.assertThat(processInstance).isCompleted();
    }
}

• @CamundaProcessTest registers the Camunda JUnit extension that starts and stops the test runtime.
• @Test is the standard JUnit 5 annotation for a test case.
• (optional) Get a preconfigured CamundaClient injected to interact with the Camunda runtime.
• (optional) Get a CamundaProcessTestContext injected to interact with the test runtime.
• (optional) Use CamundaAssert to verify the process instance state.

Read more about CamundaAssert and the available assertions here.

Configure the runtime

By default, the test runtime uses the Camunda Docker images in the same version as the test library. You can change the version or customize the runtime to your needs.

Spring SDK

Set the following properties in your application.yml (or application.properties) to override the defaults:

io:
  camunda:
    process:
      test:
        # Change the version of the Camunda Docker image
        camundaVersion: 8.6.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 addition Camunda ports
        camundaExposedPorts:
          - 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.6.0
        # Set additional Connectors environment variables
        connectors-env-vars:
          env_1: value_1
        # Set Connectors secrets
        connectors-secrets:
          secret_1: value_1

Java client

You can change the version by setting the following properties in a /camunda-container-runtime.properties file:

camunda.version=8.6.0
elasticsearch.version=8.13.4

For more configuration options, you can register the JUnit extension manually and use the fluent builder to override the default:

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 final CamundaProcessTestExtension extension =
        new CamundaProcessTestExtension()
            // Change the version of the Camunda Docker image
            .withCamundaVersion("8.6.0")
            // Change the Camunda Docker image
            .withCamundaDockerImageName("camunda/camunda")
            // Set additional Camunda environment variables
            .withCamundaEnv("env_1", "value_1")
            // Expose addition 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.6.0")
            // Set additional Connectors environment variables
            .withConnectorsEnv("env_1", "value_1")
            // Set Connectors secrets
            .withConnectorsSecret("secret_1", "value_1");
}

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
• tc.camunda - The Camunda Docker container
• tc.connectors - The Connectors Docker container
• tc.elasticsearch - The Elasticsearch Docker container
• org.testcontainers - The Testcontainers framework

For most cases, the log level warn (warning) is sufficient.

Examples

Take a look at the example project on GitHub. This demonstrates the usage of the library for a demo Spring Boot process application.