Selecting Process Instances By Tags In Camunda

This article discusses the proposal to enhance the Camunda Process Test DSL by introducing a new selector that allows users to uniquely identify process instances using tags. Currently, the DSL only allows identification by process definition ID, which becomes insufficient when multiple instances of the same process exist. This enhancement aims to provide a more granular way to interact with specific process instances within tests.

Motivation: The Need for Tag-Based Selection

In Camunda, process instances are the running executions of a process definition. In many real-world scenarios, multiple instances of the same process definition might be active concurrently. For example, consider an order processing system where each order is handled by a separate process instance. When testing such systems, it's crucial to be able to target specific process instances for assertions and actions. The current DSL limitation of identifying instances only by process definition ID makes this challenging.

To illustrate, imagine you have two order processing instances running, both initiated from the same process definition. If you want to assert the state of a specific order (e.g., check if a particular task is active), you need a way to differentiate between these instances. This is where tags come into play. Tags are user-defined labels that can be attached to process instances, providing a mechanism for categorization and identification. By allowing the DSL to select instances based on tags, we gain the ability to precisely target the instances we want to interact with during testing. This enhancement significantly improves the flexibility and accuracy of Camunda process tests.

Using tags, you could tag one instance with "orderId:123" and another with "orderId:456". Then, in your tests, you can use the DSL to select the instance with "orderId:123" and assert its state. This level of precision is essential for robust and reliable testing of complex processes. Furthermore, the tag-based selection mechanism aligns with the best practices of software testing, which emphasize the importance of isolating and verifying individual components or instances.

Proposed Solution: Extending the DSL with Tag Selectors

The proposed solution involves extending the Camunda Process Test DSL to include a new selector that can filter process instances based on their tags. This extension will allow developers to write test scenarios that:

1. Create process instances and assign tags to them.
2. Select process instances based on specific tag values.
3. Assert the state of process instances selected by tags.
4. Complete jobs or perform other actions on process instances selected by tags.

Key Components of the Proposed Extension

To achieve this, the following components need to be added to the DSL:

• Process Instance Creation with Tags: The existing DSL instruction for creating process instances needs to be extended to allow specifying tags. This could be achieved by adding a new parameter to the creation instruction that accepts a map of tag names and values. For example, a test scenario might include a step like `createProcessInstance(processDefinitionKey, Map.of(