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
For Camunda 8.6, CPT is in an alpha version.
For a full-featured testing library, take a look at Zeebe Process Test.
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 Zeebe 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
- Java client
<dependency>
<groupId>io.camunda</groupId>
<artifactId>camunda-process-test-spring</artifactId>
<scope>test</scope>
</dependency>
<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
- Java client
package com.example;
import io.camunda.process.test.api.CamundaAssert;
import io.camunda.process.test.api.CamundaProcessTestContext;
import io.camunda.process.test.api.CamundaSpringProcessTest;
import io.camunda.zeebe.client.ZeebeClient;
import io.camunda.zeebe.client.api.response.ProcessInstanceEvent;
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 ZeebeClient 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
ZeebeClient
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.
package com.example;
import io.camunda.process.test.api.CamundaAssert;
import io.camunda.process.test.api.CamundaProcessTest;
import io.camunda.process.test.api.CamundaProcessTestContext;
import io.camunda.zeebe.client.ZeebeClient;
import io.camunda.zeebe.client.api.response.ProcessInstanceEvent;
import org.junit.jupiter.api.Test;
@CamundaProcessTest
public class MyProcessTest {
// to be injected
private ZeebeClient 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
ZeebeClient
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
- Java client
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
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 Zeebe Docker image
.withZeebeDockerImageName("camunda/zeebe")
// Set additional Zeebe environment variables
.withZeebeEnv("env_1", "value_1")
// Expose addition Zeebe ports
.withZeebeExposedPort(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 runtimetc.camunda
- The Camunda Docker containertc.connectors
- The Connectors Docker containertc.elasticsearch
- The Elasticsearch Docker containerorg.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.