8.2. Session creation

To create a session, it is required to first create a RuntimeManager and RuntimeEngine from which you will get the session. The following methods can be used to create RuntimeManager:
  • createRuntimeManager(String... process) creates default configuration of the RuntimeManager with singleton strategy and all processes added to the kie base. There will only be one RuntimeManager created during single test and the processes shall be added to the kie base.
  • createRuntimeManager(Strategy strategy, String identifier, String... process) creates default configuration of RuntimeManager with given strategy and all processes being added to the kie base. Strategy selects the strategies that are supported, and identifier identifies the RuntimeManager.
  • createRuntimeManager(Map<String, ResourceType> resources) creates default configuration of RuntimeManager with singleton strategy and all resources being added to kie base. The resources code identifies the processes, rules, etc that shall be added to the kie base.
  • createRuntimeManager(Map<String, ResourceType> resources, String identifier) creates default configuration of RuntimeManager with singleton strategy and all resources added to kie base. Like the method above but with an identifier that identifies the RuntimeManager.
  • createRuntimeManager(Strategy strategy, Map<String, ResourceType> resources) creates default configuration of RuntimeManager with given strategy and all resources being added to the kie base. There will be only one RuntimeManager created during single test. The strategy code is the selected strategy of those that are supported. The resources code are all the resources that shall be added to the kie base.
  • createRuntimeManager(Strategy strategy, Map<String, ResourceType> resources, String identifier) creates default configuration of RuntimeManager with given strategy and all resources being added to kie base. There will be only one RuntimeManager created during single test. The strategy code selects the supported strategies. The resources code identifies the resources that shall be added to the kie base. The identifier code identifies the RuntimeManger.
  • createRuntimeManager(Strategy strategy, Map<String, ResourceType< resources, RuntimeEnvironment environment, String identifier) is the lowest level of creation of RuntimeManager that expects to get RuntimeEnvironment to be given as an argument. It does not assume any particular configuration; that is, it allows you to configure every single piece of RuntimeManager manually. The strategy code selects the strategies of those that are supported. The resources code identifies the resources added to the kie base. The environment code is the runtime environment used for RuntimeManager creation. The identifier code identifies the RuntimeManager.
The following methods can be used to get RuntimeEngine:
  • getRuntimeEngine() returns a new RuntimeEngline built from the manager of the test case. It uses EmptyContext that is suitable for the following strategies: singleton and request.
  • getRuntimeEngine(Context<?> context) returns a new RuntimeEngine built from the manager of the test case. Common use case would be to maintain the same session for the process instance and thus a ProcessInstanceIdContext shall be used. The context code is the instance of the context that shall be used to create RuntimeManager.

8.2.1. Assertions

The following assertions are available for testing the current state of a process instance:
  • assertProcessInstanceActive(long processInstanceId, KieSession ksession): checks whether the Process instance with the given id is active.
  • assertProcessInstanceCompleted(long processInstanceId, KieSession ksession): checks whether the Process instance with the given id has completed. successfully
  • assertProcessInstanceAborted(long processInstanceId, KieSession ksession): checks whether the Process instance with the given id was aborted.
  • assertNodeActive(long processInstanceId, KieSession ksession, String... name): checks whether the process instance with the given id contains at least one active node with the given node names.
  • assertNodeTriggered(long processInstanceId, String... nodeNames): checks for each given node name whether a node instance was triggered during the execution of the Process instance.
  • getVariableValue(String name, long processInstanceId, KieSession ksession): retrieves the value of the variable with the given name from the given Process instance.

8.2.2. Integration with external services

To test possible scenarios connected to collaboration of Process Tasks with external services, you can use TestWorkItemHandler. TestWorkItemHandler is provided by default can be registered to collect all Work Items of a given type, for example sending an email or invoking a service, and contains all the data related to that task).
This test handler can be queried during unit testing to check whether specific work was requested during the execution of the Process and that the data associated with the work was correct.

Example 8.2. Testing an Email Task

Let's assume we want to test the Process depicted in Figure 8.1, “Process with a custom Email Service Task”. The test should in particular check if an exception is raised when the email sending fails. The failure is simulated by notifying the engine that the sending the email could not be completed: 
import org.kie.api.runtime.manager.RuntimeManager;
import org.kie.api.runtime.manager.RuntimeEngine;
import org.kie.api.runtime.KieSesssion;
import org.kie.api.runtime.process.WorkItem;
import org.kie.api.runtime.process.WorkItemHandler;
import org.kie.api.runtime.process.ProcessInstance;
import org.kie,api.runtime.process.WorkItemManger;

  public void testProcess2() {

  // create runtime manager with single process - hello.bpmn
  createRuntimeManager("sample-process.bpmn"); 

  // take RuntimeManager to work with process engine
  RuntimeEngine runtimeEngine = getRuntimeEngine();

  // get access to KieSession instance
  KieSession ksession = runtimeEngine.getKieSession();

  // register a test handler for "Email"
  TestWorkItemHandler testHandler = getTestWorkItemHandler();
  ksession.getWorkItemManager().registerWorkItemHandler("Email", testHandler);

  // start the process
  ProcessInstance processInstance = ksession.startProcess("com.sample.bpmn.hello2");
  assertProcessInstanceActive(processInstance.getId(), ksession);
  assertNodeTriggered(processInstance.getId(), "StartProcess", "Email");

  // check whether the email has been requested
  WorkItem workItem = testHandler.getWorkItem();
  assertNotNull(workItem);
  assertEquals("Email", workItem.getName());
  assertEquals("me@mail.com", workItem.getParameter("From"));
  assertEquals("you@mail.com", workItem.getParameter("To"));

  // notify the engine the email has been sent
  ksession.getWorkItemManager().abortWorkItem(workItem.getId());
  assertProcessInstanceAborted(processInstance.getId(), ksession);
  assertNodeTriggered(processInstance.getId(), "Gateway", "Failed", "Error");

}
The test case uses a test handler that registers when an email is requested and allows you to test the data related to the email. Once the engine has been notified the email could not be sent by the abortWorkItem(..) method call, the unit test verifies that the Process handles this case by logging the fact and terminating with an error.
Process with a custom Email Service Task

Figure 8.1. Process with a custom Email Service Task

8.2.3. Persistence

To simplify unit testing, jBPM includes a helper class called JbpmJUnitBaseTestCase in the jbpm-test module that greatly simplifies your junit testing. This helper class provides methods to create a new RuntimeManager and RuntimeEngine for a given process or set of processes. By default, persistence is not used, and it is controlled by the super constructor. The helper method allows you to select whether or not you wish to use persistence. The example below shows a helper class to allow persistence:

Example 8.3. 

public class ProcessHumanTaskTest extends JbpmJUnitBaseTestCase {

    public ProcessPersistenceTest() {

        // setup data source, enable persistence

        super(true, true);

    }
    	....