I am really happy to announce the Maven Central Release of the new Camunda BPM community extension project Camunda BPM Assert Scenario. I also showed it on Camunda’s awesome Community Day at their headquarters two days ago. And today I pushed a Getting Started project to GitHub.

A first little project to get you started

Here’s what was needed to be done for the getting started project:

Step 1: Create a Camunda Maven Project, I e.g. use here the Camunda Maven Archetype to create one:

mvn archetype:generate -DinteractiveMode=false -DarchetypeRepository=https://app.camunda.com/nexus/content/repositories/camunda-bpm -DarchetypeGroupId=org.camunda.bpm.archetype -DarchetypeArtifactId=camunda-archetype-servlet-war -DarchetypeVersion=7.5.0 -DgroupId=org.example.camunda.bpm -DartifactId=camunda-bpm-scenario-testing -Dversion=0.1-SNAPSHOT -Dpackage=org.example.camunda.bpm.scenario

Step 2: Set the language level in your pom to Java 1.8. Note that this is not “necessary” to use “Assert Scenario”, but it’s definitely more fun with lambda expressions.

<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>

Step 3: Add the Maven Dependency for “Assert Scenario” to your projects pom.xml

<dependency>
    <groupId>org.camunda.bpm.extension</groupId>
    <artifactId>camunda-bpm-assert-scenario</artifactId>
    <version>0.1</version>
    <scope>test</scope>
</dependency>

Furthermore, add Mockito to your project dependencies. If you prefer another mocking framework, feel free to use it instead, but the example shown below will make use of Mockito.

<dependency>
  <groupId>org.mockito</groupId>
  <artifactId>mockito-core</artifactId>
  <version>1.10.19</version>
  <scope>test</scope>
</dependency>

Step 4: Open the process.bpmn in the src/main/resources folder by means of Camunda Modeler and add a few User Tasks in between the start and the end event. I did e.g. the following:

Alternatively, you may want to download my process.bpmn shown here.

Step 5: Open the InMemoryH2Test.java in the src/test/java folder. Adapt the testHappyPath() method:

@Test
@Deployment(resources = "process.bpmn")
public void testHappyPath() {

  // GIVEN a process scenario... (this one just completes all user tasks)
  ProcessScenario process = Mockito.mock(ProcessScenario.class);
  Mockito.when(process.waitsAtUserTask(Mockito.anyString())).thenReturn((task) -> task.complete());

  // WHEN we run the scenario
  Scenario scenario = Scenario.run(process).startByKey("camunda-bpm-scenario-testing").execute();

  // THEN we assume to reach the end event
  Mockito.verify(process).hasFinished("EndEventProcessEnded");

  // AND we want to visualise the process instance's history
  ProcessTestCoverage.calculate(scenario.instance(process), rule.getProcessEngine());

}

While I would not see it as a “best practice” to simply “complete” all open user tasks as shown in this code snippet, it can be a helpful technique to get started quickly with your process model tests. So let’s execute this test now!

mvn clean test

It will run the process instance from start event to end event and produce an HTML in the project’s target/process-test-coverage folder named camunda-bpm-scenario-testing.html. Open it and see yourself that our test covered all flow nodes:

Congratulations, you already reached 100% flow node coverage!? Well, we see here that all measuring techniques have their limits, in particular if people adapt to them! All jokes aside, I will soon continue to post more on the topic, focusing on particular aspects of process testing by means of “Assert Scenario”.

The motivations behind “Assert Scenario”

Camunda BPM Assert Scenario enables much faster process development, removing the need to adapt unit test suites for large executable models over and over again. When using it I experience that just those tests break that I want to break: when I change the “business relevant” aspect under test or what the process achieves. However, the test suites do not break at all when I just refactor a model’s inner logic or how I achieve the desired business semantics.

Furthermore, Camunda BPM Assert Scenario enables realistic unit testing for time-related process behaviour: by deferring actions and “fast-forwarding” test scenarios into their “process future”, one can check how several processes and call activities behave together. One however always remains in the driver’s seat: Camunda BPM Assert Scenario works in a single-treaded, easily mockable and controllable unit test environment.

Happy scenario testing!