@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-tasks-service-task-vs.-send-receive-task-combo.md

@@ -0,0 +1,42 @@
+# Service integration patterns with BPMN — Integrating services with BPMN tasks — Service task vs. send/receive task combo
+
+For asynchronous request/response calls, you can use a send task for the request, and a following receive task to wait for the response:
+
+![Send and receive task](service-integration-patterns-assets/send-and-receive-task.png)
+
+You can also use a service task, which is sometimes unknown even to advanced users. A service task can technically wait for a response that happens at any time, a process instance will wait in the service task, as it would in the receive task.
+
+![Service task](service-integration-patterns-assets/service-task.png)
+
+Deciding between these options is not completely straightforward. You can find a table listing the decision criteria below.
+
+As a general rule-of-thumb, we recommend using **the service task as the default option for synchronous _and_ asynchronous request/response** calls. The beauty of service tasks is that you remove visual clutter from the diagram, which makes it easier to read for most stakeholders.
+
+This is ideal if the business problem requires a logically synchronous service invocation. It allows you to ignore the technical details about the protocol on the process model level.
+
+The typical counter-argument is that asynchronous technical protocols might lead to different failure scenarios that you have to care about. For example, when using a separate receive task, readers of the diagram almost immediately start to think about what happens if the response will not be received. But this also has the drawback that now business people might start discussing technical concerns, which is not necessarily good.
+
+Furthermore, this is a questionable argument, as synchronous REST service calls could also timeout. This is exactly the same situation, just hidden deeper in network abstraction layers, as every form of remote communication uses asynchronous messaging somewhere down in the network stack. On a technical level, you should always think about these failure scenarios. The talk [3 common pitfalls in microservice integration and how to avoid them](https://blog.bernd-ruecker.com/3-common-pitfalls-in-microservice-integration-and-how-to-avoid-them-3f27a442cd07) goes into more detail on this.
+
+On a business level, you should be aware of the business implications of technical failures, but not discuss or model all the nuts and bolts around it.
+
+However, there are also technical implications of this design choice that need to be considered.
+
+**Technical implications of using service tasks**
+
+You can keep a service task open and just complete it later when the response arrives, but in **to complete the service task, you need the _job instance key_** from Zeebe. This is an internal ID from the workflow engine. You can either:
+
+- Pass it around to the third party service which sends it back as part of the response message.
+- Build some kind of lookup table, where you map your own correlation information to the right job key.
+
+**Note**
+Later versions of Zeebe might provide query possibilities for this job key based on user controlled data, which might open up more possibilities.
+
+Using workflow engine internal IDs can lead to problems. For example, you might cancel and restart a process instance because of operational failures, which can lead to a new ID. Outstanding responses cannot be correlated anymore in such instances.
+
+Or, you might run multiple workflow engines which can lead to internal IDs only being unique within one workflow engine. All of this might not happen, but the nature of an internal ID is that it is internal and you have no control over it — which bears some risk.
+
+In practice, however, using the internal job instance key is not a big problem if you get responses in very short time frames (milliseconds). Whenever you have more long-running interactions, you should consider using send and receive tasks, or build your own lookup table that can also address the problems mentioned above.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-tasks-service-task.md

@@ -0,0 +1,8 @@
+# Service integration patterns with BPMN — Integrating services with BPMN tasks — Service task
+
+The [service task](https://docs.camunda.io/docs/next/components/modeler/bpmn/service-tasks/service-tasks) is the typical element to implement synchronous request/response calls, such as REST, gRPC or SOAP. You should **always use service tasks for synchronous request/response**.
+
+![Service task](service-integration-patterns-assets/service-task.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.integrating-services-with-bpmn-tasks.md

@@ -0,0 +1,6 @@
+# Service integration patterns with BPMN — Integrating services with BPMN tasks
+
+Let’s look at using BPMN tasks to handle these communication patterns before diving into BPMN events later.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.service-integration-patterns.md

@@ -0,0 +1,29 @@
+# Service integration patterns with BPMN
+
+When integrating systems and services, you can choose between various modeling possibilities in BPMN.
+
+When integrating systems and services, you can choose between various modeling possibilities in BPMN. This practice will give you an overview and advice on how to decide between alternatives.
+
+You will note that service tasks in general are a good choice, but there are also situations where you might want to switch to send and receive tasks or events.
+
+
+## Understanding communication patterns
+
+Let's briefly examine the three typical communication patterns to integrate systems:
+
+- **Request/response using synchronous communication styles**: You use a synchronous protocol, like HTTP, and block for the result.
+- **Request/response using asynchronous communication styles**: You use asynchronous communication, for example, by sending messages via a message broker, but wait for a response message right after. Technically, these are two independent asynchronous messages, but the sender blocks until the response is received, hence logically making it a request/response.
+- **Asynchronous messages or events:** If a peer service needs a long time to process a request, the response is much later than the request, say hours instead of milliseconds. In this case, the response is typically handled as a separate message. Additionally, some of your services might also wait for messages or events that are not connected to a concrete request, especially in event-driven architectures.
+
+The following table gives a summary of the three options:
+
+|                                   | Synchronous request/response | Asynchronous request/response | Asynchronous messages or events |
+| --------------------------------- | :--------------------------- | :---------------------------- | :------------------------------ |
+| **Business level**                | Synchronous                  | Synchronous                   | Asynchronous                    |
+| **Technical communication style** | Synchronous                  | Asynchronous                  | Asynchronous                    |
+| **Example**                       | HTTP                         | AMQP, JMS                     | AMQP, Apache Kafka              |
+
+You can dive more into communication styles in the webinar [Communication Between Loosely Coupled Microservices](https://page.camunda.com/wb-communication-between-microservices) ([slides](https://www.slideshare.net/BerndRuecker/webinar-communication-between-loosely-coupled-microservices), [recording](https://page.camunda.com/wb-communication-between-microservices) and [FAQ](https://blog.bernd-ruecker.com/communication-between-loosely-coupled-microservices-webinar-faq-a02708b3c8b5)).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/service-integration-patterns

package/.llms/chunks/components.best-practices.development.testing-process-definitions.md

@@ -0,0 +1,35 @@
+# Testing process definitions
+
+Test your executable BPMN processes as they are software. If possible, do automated unit tests with a fast in-memory workflow engine.
+
+Test your executable BPMN processes as you would any software. When possible, write fast automated unit tests using a localized and isolated workflow engine. Before releasing, verify your implementation with integration tests in an environment that closely mirrors your production setup, which may include human-driven, exploratory integration tests.
+
+This best practice uses the following process example for incoming invoices that need to be approved:
+
+Diagram (BPMN):
+  start "Invoice received" → user task "Approve invoice" → exclusive gateway "Approved?"
+    — [yes] service task "Archive invoice" → service task "Add invoice to accounting system" → end "Invoice approved"
+    — [no] service task "Send invoice rejection" → end "Invoice rejected"
+
+**(1)**
+
+Invoices need to be approved.
+
+**(2)**
+
+The invoice sender is notified about a rejection.
+
+**(3)**
+
+Approved invoices get processed.
+
+**(4)**
+
+If the approval task takes too long, the process takes an alternative path—in this case, the invoice is automatically approved.
+
+**(5)**
+
+If an error occurs while communicating with the archive system (assume you have an unreliable legacy system), the process takes a detour to handle this situation manually.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.testing-scopes.md

@@ -0,0 +1,14 @@
+# Testing process definitions — Testing scopes
+
+There are three typical test scopes used when building process solutions:
+
+1. **Unit tests**: Testing glue code or programming code you developed for your process solution. How to unit test your software itself is not discussed here, as this is a common practice for software development.
+
+2. **Process tests**: Testing the expected behavior of the process model, including glue code and specifically the data flowing through the process model. These tests should run frequently, so they should behave like unit tests (quick turnaround, no need for external resources).
+
+3. **Integration tests**: Testing the system in a close-to-production environment to ensure it works correctly. This is typically done before releasing a new version of your system. These tests include _human-driven_, _exploratory_ tests.
+
+![Scopes](testing-process-definitions-assets/scopes.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-polyglot-process-tests-mocking-rest-calls.md

@@ -0,0 +1,73 @@
+# Testing process definitions — Writing polyglot process tests — Mocking REST calls
+
+Especially when using the Connector framework, there might be relevant logic to test in configuration of a connector, especially the input and output data mapping. To test those, you typically want to mock the endpoint, rather than the job worker.
+
+In the invoice approval example, the `Send invoice rejection` task leverages an outbound REST connector. The service task might look like this in the BPMN XML:
+
+```xml
+<bpmn:serviceTask id="ServiceTask_SendRejection" name="Send invoice rejection" zeebe:modelerTemplate="io.camunda.connectors.HttpJson.v2">
+  <bpmn:extensionElements>
+    <zeebe:taskDefinition type="io.camunda:http-json:1" retries="3" />
+    <zeebe:ioMapping>
+      <zeebe:input target="method" source="POST" />
+      <zeebe:input target="url"    source="{{secrets.INVOICE_REJECTION_URL}}/reject" />
+      <zeebe:input target="body"   source="={ &#10;  &#34;invoiceId&#34; : invoice.id, &#10;  &#34;rejectionReason&#34;: rejectionReason&#10;}" />
+      <!--. .. -->
+  </bpmn:extensionElements>
+</bpmn:serviceTask>
+```
+
+You can mock the REST endpoint using the Spring Boot integration of [WireMock](http://wiremock.org/), allowing you to stub the endpoint in your JUnit test and make it accessible to the TestContainers runtime.
+
+1. Add the required [WireMock Spring Boot](https://wiremock.org/docs/spring-boot/) dependency to your project (`org.wiremock.integrations:wiremock-spring-boot`).
+2. Add the annotation `@EnableWireMock` to your test class to start the WireMock server.
+3. Use the secrets in Camunda to configure the endpoint of the REST call, which is best practice anyway to configure the URL in the environment. In the test you need to set it to the URL containing of the hostname `host.testcontainers.internal` and the WireMock server port.
+4. Make sure the connector runtime is enabled in the test case, so that the out-of-the-box REST connector is executed.
+5. Expose the WireMock server port to the TestContainers runtime before running the test case.
+
+Here is the relevant source code:
+
+```java
+import static com.github.tomakehurst.wiremock.client.WireMock.*;
+
+@EnableWireMock
+@SpringBootTest(
+    properties = {
+        "camunda.client.worker.defaults.enabled=false",
+        "camunda.process-test.connectors-enabled=true",
+        "camunda.process-test.connectors-secrets.INVOICE_REJECTION_URL="
+            + "http://host.testcontainers.internal:${wiremock.server.port}"
+    })
+@CamundaSpringProcessTest
+public class InvoiceApprovalIntegrationTest {
+
+  @Value("${wiremock.server.port}")
+  private int wireMockPort;
+
+  @BeforeEach
+  void setup() {
+    Testcontainers.exposeHostPorts(wireMockPort);
+  }
+
+  @Test
+  public void testRejectionPath() throws Exception {
+    // configure mock behavior
+    stubFor(post("/reject").willReturn(aResponse().withStatus(200).withBody("ok")));
+
+    // Now drive the test case as in a unit test shown above ...
+
+    // Verify the mock was called
+    verify(
+        postRequestedFor(urlEqualTo("/reject"))
+            .withRequestBody(
+                equalToJson(
+                    """
+                    {
+                      "invoiceId": "INV-1001",
+                      "rejectionReason": "it is a test case :-)"
+                    }""")));
+  }
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-polyglot-process-tests.md

@@ -0,0 +1,33 @@
+# Testing process definitions — Writing polyglot process tests
+
+TODO
+
+* How to provision / cleanup engine (API to create cluster)
+* Use the API / Language client to drive your process
+* No assertions available at the moment (probably use history API?)
+* Assert side effects / workers
+
+* Example in Node.js?
+-->
+
+
+## Integration tests
+
+Test the process in a close-to-real-life environment. This verifies that it really works before releasing a new version of your process definition, which includes _human-driven_, _exploratory_ tests.
+
+Clearly _define your goals_ for integration tests! Goals could be:
+
+- End user & acceptance tests
+- Complete end-to-end tests
+- Performance & load tests, etc.
+
+Carefully consider _automating_ tests on scope 3. You need to look at the overall effort spent on writing test automation code and maintaining it when compared with executing human-driven tests for your software project's lifespan. The best choice depends very much on the frequency of regression test runs.
+
+Most effort is typically invested in setting up proper test data in surrounding systems.
+
+Configure your tests to be dedicated integration tests, and separate them from unit or process tests.
+
+You can use typical industry standard tools for integration testing together with Camunda.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-process-tests-in-java-drive-the-process-and-assert-the-state.md

@@ -0,0 +1,56 @@
+# Testing process definitions — Writing process tests in Java — Drive the process and assert the state
+
+For tests, you drive the process from wait state to wait state and assert that you observe the expected process and variable states. For example, you might implement a test for the scenario when an invoice gets approved and processed without errors:
+
+```java
+@Test
+public void happyPath() throws Exception {
+    final HashMap<String, Object> variables = new HashMap<String, Object>();
+    variables.put("approver", "Zee");
+    variables.put("invoice", objectMapper.readTree(invoiceJson));
+
+    // Kick off the process instance // <1>
+    final var processInstance =
+        client
+            .newCreateInstanceCommand()
+            .bpmnProcessId("Process_InvoiceApproval")
+            .latestVersion()
+            .variables(variables)
+            .send()
+            .join();
+
+    // assert the User Task and simulate a human decision // <2>
+    assertThat(byElementId("UserTask_ApproveInvoice")).isCreated().hasAssignee("Zee");
+    processTestContext.completeUserTask(
+        byElementId("UserTask_ApproveInvoice"), Map.of("approved", true));
+
+    // This should make the process instance execute till the end // <3>
+    assertThat(processInstance)
+        .hasCompletedElementsInOrder(
+            byId("StartEvent_InvoiceReceived"),
+            byId("UserTask_ApproveInvoice"),
+            byId("ServiceTask_ArchiveInvoice"),
+            byId("ServiceTask_AddInvoiceAccounting"),
+            byId("EndEvent_InvoiceApproved"))
+        .isCompleted();
+
+    // verify that side effects have happened // <4>
+    verify(archiveService).archiveInvoice("INV-1001", objectMapper.readTree(invoiceJson));
+    verify(accountingService).addInvoiceToAccount("0815", "INV-1001");
+  }
+```
+
+1. Create a new process instance. You may want to use some glue code to start your process (e.g. the REST API facade), or also create helper methods within your test class.
+
+2. Drive the process through its wait states, e.g. by completing a waiting user task.
+
+3. Assert that your process is in the expected state.
+
+4. Verify with your mocking library that your business service methods were called as expected.
+
+Be careful not to "overspecify" your test method by asserting too much. Your process definition will likely evolve in the future and such changes should break as little test code as possible, but just as much as necessary!
+
+As a rule of thumb _always_ assert that the expected _external effects_ of your process really took place (e.g. that business services were called as expected). Additionally, carefully choose which aspects of _internal process state_ are important enough so that you want your test method to warn about any related change later on.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-process-tests-in-java-technical-setup-using-spring.md

@@ -0,0 +1,96 @@
+# Testing process definitions — Writing process tests in Java — Technical setup using Spring
+
+**Caution**
+
+- Camunda Process Test was introduced with **Camunda 8.8**.
+- You must use **JUnit 5** in every test class. The `@Test` annotation you import must be `org.junit.jupiter.api.Test`.
+
+1. Use [_JUnit 5_](http://junit.org) as your unit test framework.
+2. Use the [Camunda Spring Boot Starter](https://docs.camunda.io/docs/next/apis-tools/camunda-spring-boot-starter/getting-started).
+3. Use `@CamundaSpringProcessTest` to start a process engine.
+4. Ensure you have Docker installed locally to use [TestContainers](https://docs.camunda.io/docs/next/apis-tools/testing/getting-started#prerequisites), which is the easiest way to run tests.
+5. Use assertions from [Camunda Process Test](https://docs.camunda.io/docs/next/apis-tools/testing/assertions) to verify that your expectations about the process state are met.
+6. Use a mocking framework of your choice (such as [Mockito](http://mockito.org)) to mock service methods and verify that services are called as expected.
+7. Use utilities from [Camunda Process Test](https://docs.camunda.io/docs/next/apis-tools/testing/utilities) to mock job workers you don't want to run (for example, connectors).
+
+The following code shows an example test:
+
+```java
+@SpringBootTest(
+    properties = {
+      "camunda.client.worker.defaults.enabled=false", // disable job workers and enable them selectively
+      "camunda.client.worker.override.archive-invoice.enabled=true",
+    })
+@CamundaSpringProcessTest
+public class InvoiceApprovalTest {
+
+  @Autowired
+  private CamundaClient client;
+  @Autowired
+  private CamundaProcessTestContext processTestContext;
+  @Autowired
+  private ObjectMapper objectMapper;
+
+  // Mock services that are called from the job workers
+  @MockitoBean
+  private ArchiveService archiveService;
+  @MockitoBean
+  private AccountingService accountingService;
+
+  // Sample data used
+  private final String invoiceJson =
+      """
+      {
+        "id": "INV-1001",
+        "amount": 12000,
+        "currency": "EUR",
+        "supplier": {
+          "id": "0815",
+          "name": "Acme GmbH"
+        },
+        "contactEmail": "accounting@acme.com"
+      }""";
+
+  @Test
+  public void happyPath() throws Exception {
+    final HashMap<String, Object> variables = new HashMap<String, Object>();
+    variables.put("approver", "Zee");
+    variables.put("invoice", objectMapper.readTree(invoiceJson));
+
+    // After all preparations, start the process instance
+    final var processInstance =
+        client
+            .newCreateInstanceCommand()
+            .bpmnProcessId("Process_InvoiceApproval")
+            .latestVersion()
+            .variables(variables)
+            .send()
+            .join();
+
+    // assert the User Task was created
+    assertThat(byElementId("UserTask_ApproveInvoice")).isCreated().hasAssignee("Zee");
+    // and simulate the user completing it
+    processTestContext.completeUserTask(byElementId("UserTask_ApproveInvoice"),
+        Map.of("approved", true));
+
+    // This should make the process instance execute to completion
+    assertThat(processInstance)
+        .hasCompletedElementsInOrder(
+            byId("StartEvent_InvoiceReceived"),
+            byId("UserTask_ApproveInvoice"),
+            byId("ServiceTask_ArchiveInvoice"),
+            byId("ServiceTask_AddInvoiceAccounting"),
+            byId("EndEvent_InvoiceApproved"))
+        .isCompleted();
+
+    // verify that side effects have happened
+    Mockito.verify(archiveService).archiveInvoice("INV-1001", objectMapper.readTree(invoiceJson));
+    Mockito.verify(accountingService).addInvoiceToAccount("0815", "INV-1001");
+  }
+```
+
+**Note**
+The complete source code for this example test is available on [GitHub](https://github.com/camunda/camunda/tree/main/testing/camunda-process-test-example/src/test/java/io/camunda/InvoiceApprovalTest.java).
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-process-tests-in-java-test-scope-and-mocking.md

@@ -0,0 +1,103 @@
+# Testing process definitions — Writing process tests in Java — Test scope and mocking
+
+In a test case like this, you want to test the executable BPMN process definition, plus all the glue code that logically belongs to the process definition in a broader sense. Typical examples of glue code you want to include in a process test are:
+
+- Worker code, typically connected to a service task
+- Expressions (FEEL) used in your process model for gateway decisions or input/output mappings
+- Other glue code, for example, your own Client API (probably exposed via REST) that performs data mapping before calling the Camunda Client.
+
+The following illustration shows this for the invoice approval example:
+
+![Process test scope example](testing-process-definitions-assets/process-test-scope-example.png)
+
+Workflow engine-independent business code should _not_ be included in the tests. In the invoice approval example, the `ArchiveService` will be mocked, and the `ArchiveInvoiceWorker` will read and transform process variables and call this mock. This way, you can test the process model, the glue code, and the data flow in your process test without calling out to the real archive system.
+
+The following code examples highlight the important aspects around mocking.
+
+The `ArchiveInvoiceWorker` is executed as part of the test. It does input data mapping **(1)** and also translates a specific business exception into a BPMN error **(2)**:
+
+```java
+@Component
+public class ArchiveInvoiceWorker {
+
+  private final ArchiveService service;
+  public ArchiveInvoiceWorker(final ArchiveService service) {
+    this.service = service;
+  }
+
+  @JobWorker(type = "archive-invoice")
+  public void handleJob(
+      @Variable("invoiceId") final String invoiceId, // <1>
+      @Variable("invoice") final JsonNode invoiceJson) {
+    try {
+      service.archiveInvoice(invoiceId, invoiceJson);
+    } catch (WiredLegacyException e) { // <2>
+      throw new BpmnError(
+          "LEGACY_ERROR_ARCHIVE", "The archive system had a problem: " + e.getMessage());
+    }
+  }
+}
+```
+
+The `ArchiveService` is considered a business service (it could, for example, wrap the archive system client SDK to make the appropriate remote calls) and should _not_ be executed during the test. This is why this interface is mocked in the test case:
+
+```java
+@MockitoBean
+private ArchiveService archiveService;
+
+@Test
+public void happyPath() throws Exception {
+  // ...
+  // Using Mockito you can verify a business method was called with the expected parameters
+  Mockito.verify(archiveService).archiveInvoice("INV-1001", objectMapper.readTree(invoiceJson));
+}
+
+@Test
+void testArchiveSystemError() throws Exception {
+  // Using Mockito you can define what should happen when a method is called, in this case an exception is thrown to simulate a business error
+  doThrow(new WiredLegacyException()).when(archiveService).archiveInvoice(anyString(), any());
+  //...
+}
+```
+
+Some workers might not delegate to a proper service class, which you can easily mock. The prime example is connectors. The invoice process uses the REST connector to trigger the invoice rejection via some REST API. To avoid calling the REST endpoint, you can mock the job worker that would be provided by the connector runtime:
+
+```java
+@Test
+public void testRejectionPath() throws Exception {
+  processTestContext.mockJobWorker("io.camunda:http-json:1").thenComplete();
+  // ...
+}
+```
+
+You could also mock the REST endpoint, which we touch on later discussing integration tests. Some projects consider REST mocking part of the unit test scope, and this is generally also fine, even if we see it as integration test scope by default.
+
+You can use the same [utilities from Camunda Process Test](https://docs.camunda.io/docs/next/apis-tools/testing/utilities) to mock other workers, where you simply do not want to run the job worker itself. Maybe the implementation is not clean, but beyond your control. However, we advise to use a proper service interface whenever possible instead of job worker mocking.
+
+```java
+// Define the mock
+final JobWorkerMock addInvoiceJobWorkerMock =
+    processTestContext
+        .mockJobWorker("add-invoice-to-accounting")
+        .withHandler(
+            (jobClient, job) -> {
+                jobClient
+                    .newCompleteCommand(job)
+                    // .variables(null) //  We could now also simulate setting some response values
+                    .send()
+                    .join();
+            });
+
+// ... drive the process ...
+
+// and assert:
+assertThat(addInvoiceJobWorkerMock.getInvocations())
+    .as("add-invoice-to-accounting job worker called")
+    .isEqualTo(1);
+
+assertThat(addInvoiceJobWorkerMock.getActivatedJobs().get(0).getVariablesAsMap())
+    .containsEntry("invoiceId", "INV-1001");
+```
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions

package/.llms/chunks/components.best-practices.development.testing-process-definitions.writing-process-tests-in-java-testing-your-process-in-chunks-2.md

@@ -0,0 +1,53 @@
+# Testing process definitions — Writing process tests in Java — Testing your process in chunks (2)
+
+**(4)**
+
+An approved invoice can't get archived:
+
+```java
+@Test
+public void testArchiveSystemError() throws Exception {
+    final HashMap<String, Object> variables = new HashMap<String, Object>();
+    variables.put("approver", "Zee");
+    variables.put("invoice", objectMapper.readTree(invoiceJson));
+
+    doThrow(new WiredLegacyException()).when(archiveService).archiveInvoice(anyString(), any());
+
+    final var processInstance =
+        client
+            .newCreateInstanceCommand()
+            .bpmnProcessId("Process_InvoiceApproval")
+            .latestVersion()
+            .variables(variables)
+            .send()
+            .join();
+
+    // approve the request
+    assertThat(byElementId("UserTask_ApproveInvoice")).isCreated();
+    processTestContext.completeUserTask(byElementId("UserTask_ApproveInvoice"),
+      Map.of("approved", true));
+
+    // This should lead to the exception being thrown, causing the process to end up in the user task designed to handle the problem.
+    assertThat(byElementId("UserTask_ManuallyArchiveInvoice"))
+        .isCreated();
+        // The test for .hasCandidateGroup("archive-team") is probably not worth implementing
+        // as it limits flexibility in model changes.
+    processTestContext.completeUserTask(byElementId("UserTask_ManuallyArchiveInvoice"));
+
+    assertThat(processInstance)
+        .isCompleted()
+        .hasCompletedElementsInOrder(
+            byId("StartEvent_InvoiceReceived"),
+            byId("UserTask_ApproveInvoice"),
+            byId("UserTask_ManuallyArchiveInvoice"),
+            byId("ServiceTask_AddInvoiceAccounting"),
+            byId("EndEvent_InvoiceApproved"))
+        .hasTerminatedElements(byId("ServiceTask_ArchiveInvoice"));
+    verify(accountingService).addInvoiceToAccount("0815", "INV-1001");
+  }
+```
+
+<!--
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/development/testing-process-definitions