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
• Connectors

Disclaimer

CPT is in an alpha version.

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

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
        camunda-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

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

camunda.version=8.8.0

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

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
            .withCamundaVersion("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");
}

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)

Examples

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