new snippet: external-task-client-testing

snippets/external-task-client-testing/README.md

@@ -0,0 +1,9 @@
+# External Task Worker Testing
+
+This example shows 3 ways to test external tasks:
+
+1. Test the worker: Mock an `ExternalTask` and `ExternalTaskService` and verify the interaction with these mocked objects.
+2. Test the process: Run the engine, but disable the worker and complete external tasks with the java api.
+3. Test everything together: Run the engine and the worker and test everything together.
+
+For all tests, we have the java apis at hand.

snippets/external-task-client-testing/pom.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>io.camunda</groupId>
+  <artifactId>external-task-client-testing</artifactId>
+  <version>1.0-SNAPSHOT</version>
+
+  <properties>
+    <maven.compiler.source>21</maven.compiler.source>
+    <maven.compiler.target>21</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+
+    <version.process-test-coverage-extension>2.7.0</version.process-test-coverage-extension>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.camunda.bpm</groupId>
+        <artifactId>camunda-bom</artifactId>
+        <version>7.22.0</version>
+        <scope>import</scope>
+        <type>pom</type>
+      </dependency>
+      <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-dependencies</artifactId>
+        <version>3.3.4</version>
+        <scope>import</scope>
+        <type>pom</type>
+      </dependency>
+      <dependency>
+        <groupId>org.camunda.community.process_test_coverage</groupId>
+        <artifactId>camunda-process-test-coverage-starter-platform-7</artifactId>
+        <version>${version.process-test-coverage-extension}</version>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.camunda.bpm.springboot</groupId>
+      <artifactId>camunda-bpm-spring-boot-starter-external-task-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.camunda.bpm.springboot</groupId>
+      <artifactId>camunda-bpm-spring-boot-starter-rest</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.camunda.bpm</groupId>
+      <artifactId>camunda-bpm-junit5</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.camunda.bpm</groupId>
+      <artifactId>camunda-bpm-assert</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-jdbc</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.h2database</groupId>
+      <artifactId>h2</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.awaitility</groupId>
+      <artifactId>awaitility</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.camunda.community.process_test_coverage</groupId>
+      <artifactId>camunda-process-test-coverage-starter-platform-7</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+</project>

snippets/external-task-client-testing/src/main/java/com/camunda/consulting/example/App.java

@@ -0,0 +1,11 @@
+package com.camunda.consulting.example;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class App {
+  public static void main(String[] args) {
+    SpringApplication.run(App.class, args);
+  }
+}

snippets/external-task-client-testing/src/main/java/com/camunda/consulting/example/ExampleWorker.java

@@ -0,0 +1,23 @@
+package com.camunda.consulting.example;
+
+import org.camunda.bpm.client.spring.annotation.ExternalTaskSubscription;
+import org.camunda.bpm.client.task.ExternalTask;
+import org.camunda.bpm.client.task.ExternalTaskHandler;
+import org.camunda.bpm.client.task.ExternalTaskService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Component;
+
+@Component
+@Profile("!unitTest")
+@ExternalTaskSubscription(topicName = "exampleWork")
+public class ExampleWorker implements ExternalTaskHandler {
+  private static final Logger LOG = LoggerFactory.getLogger(ExampleWorker.class);
+
+  @Override
+  public void execute(ExternalTask externalTask, ExternalTaskService externalTaskService) {
+    LOG.info("Executing exampleWork");
+    externalTaskService.complete(externalTask);
+  }
+}

snippets/external-task-client-testing/src/main/resources/example-process.bpmn

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:camunda="http://camunda.org/schema/1.0/bpmn" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_1maxch8" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.28.0" modeler:executionPlatform="Camunda Platform" modeler:executionPlatformVersion="7.22.0">
+  <bpmn:process id="ExampleProcess" name="Example" isExecutable="true" camunda:historyTimeToLive="1">
+    <bpmn:startEvent id="ExampleRequiredStartEvent" name="Example required">
+      <bpmn:outgoing>Flow_1ecdqtr</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="Flow_1ecdqtr" sourceRef="ExampleRequiredStartEvent" targetRef="ExampleWorkTask" />
+    <bpmn:serviceTask id="ExampleWorkTask" name="Example work" camunda:type="external" camunda:topic="exampleWork">
+      <bpmn:incoming>Flow_1ecdqtr</bpmn:incoming>
+      <bpmn:outgoing>Flow_180z8iz</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:endEvent id="ExampleProvidedEndEvent" name="Example provided">
+      <bpmn:incoming>Flow_180z8iz</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow_180z8iz" sourceRef="ExampleWorkTask" targetRef="ExampleProvidedEndEvent" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="ExampleProcess">
+      <bpmndi:BPMNShape id="_BPMNShape_StartEvent_2" bpmnElement="ExampleRequiredStartEvent">
+        <dc:Bounds x="179" y="99" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="154" y="142" width="87" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_1ttohuk_di" bpmnElement="ExampleWorkTask">
+        <dc:Bounds x="270" y="77" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Event_13xh2mk_di" bpmnElement="ExampleProvidedEndEvent">
+        <dc:Bounds x="432" y="99" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="406" y="142" width="89" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_1ecdqtr_di" bpmnElement="Flow_1ecdqtr">
+        <di:waypoint x="215" y="117" />
+        <di:waypoint x="270" y="117" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_180z8iz_di" bpmnElement="Flow_180z8iz">
+        <di:waypoint x="370" y="117" />
+        <di:waypoint x="432" y="117" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

snippets/external-task-client-testing/src/test/java/com/camunda/consulting/example/AppTest.java

@@ -0,0 +1,35 @@
+package com.camunda.consulting.example;
+
+import org.camunda.bpm.engine.ProcessEngines;
+import org.camunda.bpm.engine.RuntimeService;
+import org.camunda.bpm.engine.runtime.ProcessInstance;
+import org.camunda.community.process_test_coverage.core.engine.ExcludeFromProcessCoverage;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
+
+import java.time.Duration;
+
+import static org.awaitility.Awaitility.*;
+import static org.camunda.bpm.engine.test.assertions.bpmn.BpmnAwareTests.*;
+
+/**
+ * Here, the interaction between the (remote) engine and running workers is tested
+ */
+@SpringBootTest(webEnvironment = WebEnvironment.DEFINED_PORT)
+public class AppTest {
+
+  @Autowired
+  RuntimeService runtimeService;
+
+  @Test
+  public void shouldRun() {
+    ProcessInstance exampleProcess = runtimeService.startProcessInstanceByKey("ExampleProcess");
+    await()
+        .timeout(Duration.ofSeconds(60))
+        .untilAsserted(() -> assertThat(exampleProcess).isEnded());
+  }
+}

snippets/external-task-client-testing/src/test/java/com/camunda/consulting/example/ExampleWorkerTest.java

@@ -0,0 +1,26 @@
+package com.camunda.consulting.example;
+
+import org.camunda.bpm.client.task.ExternalTask;
+import org.camunda.bpm.client.task.ExternalTaskService;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+
+import static org.mockito.Mockito.*;
+
+@SpringBootTest(classes = ExampleWorker.class)
+public class ExampleWorkerTest {
+  @Autowired
+  ExampleWorker exampleWorker;
+
+  @Test
+  void shouldInvokeExampleWorker() {
+    // given
+    ExternalTask externalTask = mock(ExternalTask.class);
+    ExternalTaskService externalTaskService = mock(ExternalTaskService.class);
+    // when
+    exampleWorker.execute(externalTask, externalTaskService);
+    // then
+    verify(externalTaskService, times(1)).complete(externalTask);
+  }
+}

snippets/external-task-client-testing/src/test/java/com/camunda/consulting/example/ProcessUnitTest.java

@@ -0,0 +1,23 @@
+package com.camunda.consulting.example;
+
+import org.camunda.bpm.engine.ProcessEngines;
+import org.camunda.bpm.engine.runtime.ProcessInstance;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import static org.camunda.bpm.engine.test.assertions.bpmn.BpmnAwareTests.*;
+
+@SpringBootTest(properties = {"camunda.bpm.client.subscriptions.exampleWork.auto-open=false","camunda.bpm.job-execution.enabled=false"})
+@ActiveProfiles("unitTest")
+public class ProcessUnitTest {
+
+  @Test
+  public void shouldRunProcess()  {
+    ProcessInstance exampleProcess = runtimeService().startProcessInstanceByKey("ExampleProcess");
+    assertThat(exampleProcess).isWaitingAt(findId("Example work"));
+    complete(externalTask());
+    assertThat(exampleProcess).isEnded();
+  }
+}

snippets/external-task-client-testing/src/test/resources/application.yaml

@@ -0,0 +1,17 @@
+# This port is fixed, so it should not interfere with other ports
+server:
+  port: 18081
+spring:
+  datasource:
+    url: jdbc:h2:mem:camunda
+camunda:
+  bpm:
+    client:
+      base-url: http://localhost:${server.port}/engine-rest
+      disable-backoff-strategy: true
+logging:
+  level:
+    org:
+      camunda:
+        bpm:
+          client: debug