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:

• Testcontainers runtime (default) - A managed runtime based on Testcontainers and Docker.
• Remote runtime - Your own runtime, such as, Camunda 8 Run

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.

Prerequisites

• Java 8+ / 17+ (for Camunda Spring Boot SDK)
• 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

We have two variations of CPT: for the Camunda Spring Boot 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:

Camunda Spring Boot 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:

Camunda Spring Boot 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.

Next steps

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

• CamundaAssert and assertions
• CamundaProcessTestContext and utilities
• How to configure the runtime

Examples

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