Unit-testing your BPM processes by bending time.

One of the core drivers behind modern application architecture, development and delivery methodologies like micro-services, agile and CI/CD is the ability to automatically test any software artifact, from application code to server configuration. Automated testing gives us the reliable, repeatable, assurance that our software meets the required quality with respect to aspects like functionality, performance, and scalability and is ready to be deployed in production. Why should testing of a business-process defined in BPMN2, a deployable software artifact, be any different?

One of the unique features of Red Hat JBoss BPMSuite is that, due to it's adoption of Maven as de-facto build platform, it allows to utilize standard Java testing practices and methodologies in the business process space. In fact, jBPM (the upstream community project thatforms the base of Red Hat JBoss BPMSuite), provides out-of-the-box JUnit test classes that allow one to easily unit-test business processes defined in BPMN2 (see the jBPM User Guide for more detail).

An interesting challenge when automatically testing business processes is testing constructs that provide behaviour based on time, e.g. Timer Intermediate Catching Events, Timer Boundary Events, etc. When unit-testing a software artifact, we want to complete the test as soon as possible, providing the ability to quickly determine whether our latest change breaks the build and thus the deployment pipeline or not. In other words, we want a quick feedback-loop. Having to wait minutes, hours or even a days for a timer to trigger when automatically testing business processes is therefore a non-feasible solution.

The answer to this problem is provided by the Drools PseudoClock. The PseudoClock is a simple, yet sophisticated, component that allows us to manipulate time from within Java code. When configured on the business process engine's session (KieSession), it provides an API to programatically advance time. This allows us to, in our automatic tests, manipulate time in such a way that causes our process timers to fire (or not, depending on the test-case).

A sample process and JUnit test-case is provided here.

Note the configuration of the PseudoClock in the @Before annotated method. Setting the Drools property configures the PseudoClock on all sessions:

@Before
public void init() {
    //Enable the PseudoClock using the following system property.
    System.setProperty("drools.clockType", "pseudo");
    runtimeManager = createRuntimeManager("sample-process.bpmn");
    runtimeEngine = getRuntimeEngine(null);
    kieSession = runtimeEngine.getKieSession();
}

Our business process contains 2 script nodes and a timer intermediate catch events that waits 60 seconds:

In both testcase we advance the clock programatically. In the first testcase, we advance the clock with 70 seconds, causing the timer to fire and thus the process to complete:

@Test
public void testTimerActivated() {
    ProcessInstance pInstance = kieSession.startProcess("sample-process");
    long pInstanceId = pInstance.getId();

    PseudoClockScheduler sessionClock = kieSession.getSessionClock();
    // Timer is set to 60 seconds, so advancing with 70.
    sessionClock.advanceTime(70, TimeUnit.SECONDS);

    // Test that the timer has triggered.
    assertNodeTriggered(pInstanceId, "Goodbye Process");
    assertProcessInstanceCompleted(pInstanceId);
}

In the second case, we advance the clock with 10 seconds, which does not cause the timer to complete. Therefore, we test that the process is still active:

@Test
public void testTimerNotActivated() {
    ProcessInstance pInstance = kieSession.startProcess("sample-process");
    long pInstanceId = pInstance.getId();</code>

    PseudoClockScheduler sessionClock = kieSession.getSessionClock();
    // Only advancing time by 10 seconds, so process should still be waiting.
    sessionClock.advanceTime(10, TimeUnit.SECONDS);

    // Test that the process is still active.
    assertProcessInstanceActive(pInstanceId);
}

This simple piece of configuration and code allows us to test processes and timers that span hours, days or even years in a number of milliseconds. This provides us with both the ability to automatically test our business process definition, as well as provide a quick feedback-loop from our CI/CD deployment pipeline.

To run this simple unit-test demonstration:

• Clone the Git repository from: https://github.com/DuncanDoyle/jbpm-unit-test-timers-example
• cd into the "jbpm-unit-test-timers-example" directory
• run "mvn clean test"

Conclusion:
Testing of BPMN2 process definitions tends to be a manual task in many platforms. Red Hat JBoss BPMSuite provides the unique capability of writing (unit-) tests in Java using de-facto test technologies like JUnit and Maven. In combination with the Drools PseudoClock, this allows for testing of complex business processes, which can include timer-based BPMN2 constructs like Timer Intermediate Catching Events and Timer Boundary Events, while at the same time providing a quick feedback-loop from our CI/CD deployment pipeline.

Thanks to Donato Marrazzo and Anton Giertli for the inspiration for this blog-post and initial code.