Assertions
The class CamundaAssert
is the entry point for all assertions. It is based on AssertJ and Awaitility.
The assertions follow the style: assertThat(object_to_test)
+ expected property.
Use the assertions by adding the following static imports in your test class:
import static io.camunda.process.test.api.CamundaAssert.assertThat;
// optional:
import static io.camunda.process.test.api.assertions.ElementSelectors.*;
import static io.camunda.process.test.api.assertions.ProcessInstanceSelectors.*;
Camunda executes BPMN processes asynchronously. For testing, this means that there might be a delay between creating a process instance and reaching the expected state.
The assertions handle the asynchronous behavior and wait until the expected property is fulfilled. Only if the property is not fulfilled within the given time, the assertion fails.
CPT provides the most common assertions. However, if you miss an assertion you can implement a custom assertion yourself.
Configuration
Assertions can be configured globally using CamundaAssert
.
Assertion timeout
By default, assertions wait 10 seconds for the expected property to be fulfilled. You can change the time globally in CamundaAssert
.
For example, the following sets the timeout to 1 minute:
CamundaAssert.setAssertionTimeout(Duration.ofMinutes(1));
Element selector
By default, the element instance assertions identify the BPMN elements by their ID. You can change the element selector globally in CamundaAssert
.
For example, the following identifies the BPMN elements by their name:
CamundaAssert.setElementSelector(ElementSelectors::byName);
Process instance assertions
You can verify the process instance state and other properties using CamundaAssert.assertThat()
. Use the process instance creation event or a ProcessInstanceSelector
to identify the process instance.
With process instance event
Use the creation event of the create instance command to identify the process instance:
// given/when
ProcessInstanceEvent processInstance =
client
.newCreateInstanceCommand()
.bpmnProcessId("my-process")
.latestVersion()
.send()
.join();
// then
assertThat(processInstance).isActive();
With process instance result
Use the result event of the create instance command to identify the process instance:
// given/when
ProcessInstanceResult processInstance =
client
.newCreateInstanceCommand()
.bpmnProcessId("my-process")
.latestVersion()
.withResult()
.send()
.join();
// then
assertThat(processInstance).isActive();
With process instance selector
Use a predefined ProcessInstanceSelector
from io.camunda.process.test.api.assertions.ProcessInstanceSelectors
or a custom implementation to identify the process instance:
// by process instance key
assertThat(byKey(processInstanceKey)).isActive();
// by process ID
assertThat(byProcessId("my-process")).isActive();
// custom selector implementation
assertThat(processInstance -> { .. }).isActive();
isActive
Assert that the process instance is active. The assertion fails if the process instance is completed, terminated, or not created.
assertThat(processInstance).isActive();
isCompleted
Assert that the process instance is completed. The assertion fails if the process instance is active, terminated, or not created.
assertThat(processInstance).isCompleted();
isTerminated
Assert that the process instance is terminated. The assertion fails if the process instance is active, completed, or not created.
assertThat(processInstance).isTerminated();
isCreated
Assert that the process instance is created and either active, completed, or terminated. The assertion fails if the process instance is not created.
assertThat(processInstance).isCreated();
hasActiveIncidents
Assert that the process instance has at least one active incident. The assertion fails if there is no active incident.
assertThat(processInstance).hasActiveIncidents();
hasNoActiveIncidents
Assert that the process instance has no active incidents. The assertion fails if there is any active incident.
assertThat(processInstance).hasNoActiveIncidents();
Element instance assertions
You can verify the element instance states and other properties using CamundaAssert.assertThat(processInstance)
. Use the BPMN element ID or a ElementSelector
to identify the elements.
With BPMN element ID
Use the BPMN element ID to identify the elements:
assertThat(processInstance).hasActiveElements("task_A");
You can customize how the elements are identified in the configuration.
With element selector
Use a predefined ElementSelector
from io.camunda.process.test.api.assertions.ElementSelectors
or a custom implementation to identify the elements:
// by BPMN element ID
assertThat(processInstance).hasActiveElements(byId("task_A"));
// by BPMN element name
assertThat(processInstance).hasActiveElements(byName("A"));
// custom selector implementation
assertThat(processInstance).hasActiveElements(element -> { .. });
hasActiveElements
Assert that the given BPMN elements of the process instance are active. The assertion fails if at least one element is completed, terminated, or not entered.
assertThat(processInstance).hasActiveElements("task_A", "task_B");
hasActiveElement
Assert that the BPMN element of the process instance is active the given amount of times. The assertion fails if the element is not active or not exactly the given amount of times.
assertThat(processInstance).hasActiveElement("task_A", 2);
hasActiveElementsExactly
Assert that only the given BPMN elements are active. The assertion fails if at least one element is not active, or other elements are active.
assertThat(processInstance).hasActiveElementsExactly("task_A", "task_B");
hasNoActiveElements
Assert that the given BPMN elements are not active. The assertion fails if at least one element is active.
assertThat(processInstance).hasNoActiveElements("task_A", "task_B");
hasNotActivatedElements
Assert that the given BPMN elements are not activated (i.e. not entered). The assertion fails if at least one element is active, completed, or terminated.
This assertion does not wait for the given activities.
assertThat(processInstance).hasNotActivatedElements("task_A", "task_B");
hasCompletedElements
Assert that the given BPMN elements of the process instance are completed. The assertion fails if at least one element is active, terminated, or not entered.
assertThat(processInstance).hasCompletedElements("task_A", "task_B");
hasCompletedElement
Assert that the BPMN element of the process instance is completed the given amount of times. The assertion fails if the element is not completed or not exactly the given amount of times.
assertThat(processInstance).hasCompletedElement("task_A", 2);
hasCompletedElementsInOrder
Assert that the given BPMN elements are completed in order. Elements that do not match any of the given element IDs are ignored. The assertion fails if at least one of the elements is not completed, or the order is not correct.
assertThat(processInstance).hasCompletedElementsInOrder("task_A", "task_B");
hasTerminatedElements
Assert that the given BPMN elements of the process instance are terminated. The assertion fails if at least one element is active, completed, or not entered.
assertThat(processInstance).hasTerminatedElements("task_A", "task_B");
hasTerminatedElement
Assert that the BPMN element of the process instance is terminated the given amount of times. The assertion fails if the element is not terminated or not exactly the given amount of times.
assertThat(processInstance).hasTerminatedElement("task_A", 2);
Variable assertions
You can verify the process instance variables using CamundaAssert.assertThat(processInstance)
. Local variables of BPMN elements are ignored.
hasVariableNames
Assert that the process instance has the given variables. The assertion fails if at least one variable doesn't exist.
assertThat(processInstance).hasVariableNames("var1", "var2");
hasVariable
Assert that the process instance has the variable with the given value. The assertion fails if the variable doesn't exist or has a different value.
assertThat(processInstance).hasVariable("var1", 100);
hasVariables
Assert that the process instance has the given variables. The assertion fails if at least one variable doesn't exist or has a different value.
Map<String, Object> expectedVariables = //
assertThat(processInstance).hasVariables(expectedVariables);
Custom assertions
You can build your own assertions similar to the assertions from CPT.
- Use the preconfigured Camunda client to retrieve the process data.
- Use AssertJ's assertions to verify the expected properties.
- Use Awaitility around verifications to compensate delays until the data is available.
@Test
void shouldCreateUserTask() {
// given: the process is deployed
// when: create a process instance
// then
Awaitility.await()
.ignoreException(ClientException.class)
.untilAsserted(
() -> {
final List<UserTask> userTasks = getUserTasks(processInstanceKey);
assertThat(userTasks).hasSize(1);
final UserTask userTask = userTasks.getFirst();
assertThat(userTask)
.returns("task", UserTask::getName)
.returns("me", UserTask::getAssignee);
});
}
// helper method
private List<UserTask> getUserTasks(final long processInstanceKey) {
return client
.newUserTaskSearchRequest()
.filter(filter -> filter.processInstanceKey(processInstanceKey).state(UserTaskState.CREATED))
.send()
.join()
.items();
}