Skip to main content
Version: 8.8 (unreleased)

Getting started

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

CPT provides different runtimes to execute your process tests:

Public API

CPT is part of the Camunda 8 public API and is covered by our SemVer stability guarantees (except for alpha features). Breaking changes will not be introduced in minor or patch releases.

note

CPT is the successor of Zeebe Process Test. Our previous testing library is deprecated and will be removed with version 8.10. See the migration guide on how to migrate your process tests.

Prerequisites

  • Java:
    • For the Camunda Java client: 8+
    • For the Camunda Spring Boot Starter: 17+
  • JUnit 5

For the default Testcontainers runtime:

  • A Docker-API compatible container runtime, such as Docker on Linux or Docker Desktop on Mac and Windows.

Install

CPT has two variants:

Choose the one depending on which library you use in your process application.

Add the following dependency to your Maven project:

<dependency>
<groupId>io.camunda</groupId>
<artifactId>camunda-process-test-spring</artifactId>
<version>${camunda.version}</version>
<scope>test</scope>
</dependency>

Write a test

Create a new Java class with the following structure:

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 shouldCreateProcessInstance() {
// given process definition is deployed

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

// then
CamundaAssert.assertThat(processInstance).isActive();
}
}
  • @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.

The Spring test requires a Spring Boot process application in the same package. Usually, the process application deploys the process resources using the annotation @Deployment.

If you have no process application yet, you can add a minimal one inside the test class as follows:

@SpringBootApplication
@Deployment(resources = "classpath*:/bpmn/**/*.bpmn")
static class TestProcessApplication {}

Next steps

You can dive deeper into the library and read more about:

Examples

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

Process Test Coverage

After a test run, CPT prints the coverage of your BPMN processes to the log and generates a detailed HTML and JSON report. You can use the report to identify untested paths in your processes and to increase your test coverage.

A link to the HTML report is printed in the log:

Process coverage: io.camunda.InvoiceApprovalTest
========================
- Process_InvoiceApproval: 100%

Coverage report: file:///my/home/projects/my-process-application/target/coverage-report/report.html

An example process test coverage HTML report