<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
JUnit test support for jBPM5
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/swiderski.maciej">Maciej Swiderski</a> in <i>jBPM</i> - <a href="http://community.jboss.org/docs/DOC-17345">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>There are number of issues that people are facing while working with jBPM and to get help the most useful elements are:</p><ul><li style="text-align: start;">process definition (BPMN2 file)</li><li style="text-align: start;">test case that illustrates mentioned issue</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>As process definition is concerned that is rather straight forward (since we already working with it when encountering the problem),</p><p>but with test case it can be bit more complex to give directly to others the driver we use for our case.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>So, after struggling for some time with exactly the same issue, I decided to start with small but yet powerful support for test cases for jBPM.</p><p>There is already a test case class that we could extend and that already brings some useful elements but that is not all we need...</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>I tried to build up a small library that is dedicated to test cases based on JUnit and that aligns with latest releases of JUnit, meaning it is </p><p>based on annotations. So to move directly what I am referring to, lets take a look at very simple test case:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">@RunWith(JbpmJUnitRunner.class)
@KnowledgeBase(source=<font color="navy">{</font><font color="red">"script.bpmn2"</font><font color="navy">}</font>)
@KnowledgeSession()
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> JbpmJUnitTestCase <font color="navy">{</font>
 
    <font color="navy"><b>protected</b></font> org.drools.KnowledgeBase knowledgeBase;
    <font color="navy"><b>protected</b></font> StatefulKnowledgeSession session;
 
    @Test
    <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> testScriptTask() <font color="navy">{</font>
        ProcessInstance instance = session.startProcess(<font color="red">"ScriptTask"</font>);
        assertProcessInstanceComplete(instance);
    <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>What you can see here is the most basic test case that allows to execute and assert process instance completion. I think the code is self explanatory so </p><p>I jump directly to the annotations that were introduced with this library:</p><p><em><strong>@RunWith</strong></em> - this one is standard JUnit annotation that instructs what runner should be used to execute tests</p><p><em><strong>@KnowledgeBase</strong></em> - annotation that defines what artifacts should be loaded into knowledge base </p><p>    Annotation attributes:</p><ul><li style="text-align: start;">    source - list of resources to be loaded (currently only BPMN2 resources are supported)</li><li style="text-align: start;">    sharedKey - name of the key that will be used to cache knowledge based between test cases, so if you have set of resources that are used across various</li></ul><p>                test cases and you want to avoid building knowledge base for each of the test cases sharedKey attribute should be set to load knowledge base only one time</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><em><strong>@KnowledgeSession</strong></em> - annotation that defines how stateful sessions should be created and maintained</p><p>    Annotation attributes:</p><ul><li style="text-align: start;">    disposePerTest - defines if session should be disposed after each test within test case, default set to true</li><li style="text-align: start;">    logger - defines what working memory logger should be configured for the session, available options NONE (default), CONSOLE, JPA</li><li style="text-align: start;">    handlers - set of work item handlers that will be registered for each session (WorkItemHandler annotation)</li><li style="text-align: start;">    persistence - defines persistence for the session (Persistence annotation)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>        <em><strong>@Persistence</strong></em> annotation attributes:</p><ul><li style="text-align: start;">    persistenceUnit - name of the persistence unit that should be used while configuring JPA entity manager factory</li><li style="text-align: start;">    reloadSession - defines if session should be reloaded (with the same id) between test invocation within test case, default false</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>        <em><strong>@WorkItemHandler</strong></em> annotation attributes:</p><ul><li style="text-align: start;">     taskName - name of the task the handler is registered for</li><li style="text-align: start;">     handles - class of the handler</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><em><strong>@HumanTaskSupport</strong></em> - annotation that instructs runner that test case requires Human Task interactions so it will initialize Task Server accessible via MINA transport</p><p>            it will be started on test case scope, meaning that all tests will have access to the same instance of the server within test case.</p><p>            Annotation attributes:</p><ul><li style="text-align: start;">            users - list of user ids that should be added to the task server on startup</li><li style="text-align: start;">            groups - list of groups that should be added to the task server on startup</li><li style="text-align: start;">            persistanceUnit - name of the persistence unit that should be used while building entity manager factory</li><li style="text-align: start;">            host - interface on which task server should be started, defaults to localhost</li><li style="text-align: start;">            port - port on which task server should be started, defaults to 9123</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><em><strong>@LifeCycle </strong></em>- annotation that lets developer to configure what operation should be executed for particulat human task.</p><p>     Annotation attributes:</p><ul><li>     phases - list of human task life cycle phases (claim, start, complete, fail, skip, etc) defined as enumeration LifeCyclePhase</li></ul><p>This annotation is intended to simplify work with human tasks while writing unit tests - very experimental!!!</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In addition to annotation there are two property files required when configuring session persistence or human task server:</p><ul><li style="text-align: start;">datasource.properties - defines parameters of connection pool</li><li style="text-align: start;">jndi.properties - defines JNDI provider for bitronix</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>NOTE: Connection pool will be created for entire test phase once datasource.properties file was discovered.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Obviously following files are required as well, since they are required by jbpm and task server artifacts:</p><ul><li style="text-align: start;">META-INF/persistence.xml that defines both (jbpm and human task persistence units)</li><li style="text-align: start;">META-INF/JBPMorm.xml </li><li style="text-align: start;">META-INF/Taskorm.xml</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Main concept is around injecting dependencies into your test case class. As dependencies I mean following items:</p><ul><li style="text-align: start;">Knowledge base</li><li style="text-align: start;">Stateful session</li><li style="text-align: start;">Task client</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Methods from JUnit life cycle are still available, such as these annotated with @Before, @After, @BeforeClass, @AfterClass. Instance methods (@Before @After) will</p><p>have access to session and knowledge base, for instance if some facts should be inserted before running the test.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>There is one more item that is worth to mention, an assert class dedicated to jbpm - JbpmAssert, which defines (at the moment):</p><ul><li style="text-align: start;">assertProcessInstanceComplete</li><li style="text-align: start;">assertProcessInstanceActive</li><li style="text-align: start;">assertProcessInstanceAborted</li><li style="text-align: start;">assertProcessInstancePending</li><li style="text-align: start;">assertProcessInstanceSuspended</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>and most likely more to come...</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong>And now, its time to show some examples of it</strong></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Simple test case with session persistence:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">@RunWith(JbpmJUnitRunner.class)
@KnowledgeBase(source=<font color="navy">{</font><font color="red">"script.bpmn2"</font><font color="navy">}</font>)
@KnowledgeSession(persistence=@Persistence(persistenceUnit=<font color="red">"org.jbpm.persistence.jpa"</font>))
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> JbpmJUnitTestCase <font color="navy">{</font>
 
    <font color="navy"><b>protected</b></font> org.drools.KnowledgeBase knowledgeBase;
    <font color="navy"><b>protected</b></font> StatefulKnowledgeSession session;
 
    @Test
    <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> testScriptTask() <font color="navy">{</font>
        ProcessInstance instance = session.startProcess(<font color="red">"ScriptTask"</font>);
        assertProcessInstanceComplete(instance);
    <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If session reload is desired between tests test case should be defined as follows:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">@RunWith(JbpmJUnitRunner.class)
@KnowledgeBase(source=<font color="navy">{</font><font color="red">"script.bpmn2"</font><font color="navy">}</font>)
@KnowledgeSession(persistence=@Persistence(persistenceUnit=<font color="red">"org.jbpm.persistence.jpa"</font>, reloadSession=<font color="navy"><b>true</b></font>))
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> JbpmJUnitTestCase <font color="navy">{</font>
 
    <font color="navy"><b>protected</b></font> org.drools.KnowledgeBase knowledgeBase;
    <font color="navy"><b>protected</b></font> StatefulKnowledgeSession session;
 
    @Test
    <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> testScriptTask() <font color="navy">{</font>
        ProcessInstance instance = session.startProcess(<font color="red">"ScriptTask"</font>);
        assertProcessInstanceComplete(instance);
    <font color="navy">}</font>
    @Test
    <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> testScriptTask2() <font color="navy">{</font>
        ProcessInstance instance = session.startProcess(<font color="red">"ScriptTask"</font>);
        assertProcessInstanceComplete(instance);
    <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Both tests will use same session.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Last but not least, human interaction test case:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">@RunWith(JbpmJUnitRunner.class)
@KnowledgeBase(source=<font color="navy">{</font><font color="red">"script.bpmn2"</font>,<font color="red">"usertask.bpmn2"</font><font color="navy">}</font>, sharedKey=<font color="red">"common"</font>)
@KnowledgeSession(handlers=<font color="navy">{</font>@WorkItemHandler(taskName=<font color="red">"Human Task"</font>, handler=WSHumanTaskHandler.class)<font color="navy">}</font>, logger=Logger.CONSOLE)
@HumanTaskSupport(persistenceUnit=<font color="red">"org.jbpm.task"</font>, users=<font color="navy">{</font><font color="red">"john"</font>, <font color="red">"Administrator"</font><font color="navy">}</font>)
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> JbpmJUnitRunnerTest <font color="navy">{</font>
 
    <font color="navy"><b>protected</b></font> org.drools.KnowledgeBase knowledgeBase;
    <font color="navy"><b>protected</b></font> StatefulKnowledgeSession session;
    <font color="navy"><b>protected</b></font> TaskClient taskClient;
 
    @Test
    <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> testHumanTask() <font color="navy"><b>throws</b></font> Exception <font color="navy">{</font>
        ProcessInstance instance = session.startProcess(<font color="red">"UserTask"</font>);
        Thread.sleep(1000);
        BlockingTaskSummaryResponseHandler taskSummaryHandler = <font color="navy"><b>new</b></font> BlockingTaskSummaryResponseHandler();
        taskClient.getTasksAssignedAsPotentialOwner(<font color="red">"john"</font>, <font color="red">"en-UK"</font>, taskSummaryHandler);
 
        assertEquals(1, taskSummaryHandler.getResults().size());
        TaskSummary task1 = taskSummaryHandler.getResults().get(0);
 
        BlockingTaskOperationResponseHandler taskOperationHandler = <font color="navy"><b>new</b></font> BlockingTaskOperationResponseHandler();
        taskClient.claim(task1.getId(), <font color="red">"john"</font>, taskOperationHandler);
 
        taskOperationHandler = <font color="navy"><b>new</b></font> BlockingTaskOperationResponseHandler();
        taskClient.start(task1.getId(), <font color="red">"john"</font>, taskOperationHandler);
        taskOperationHandler.waitTillDone(1000);
 
        taskOperationHandler = <font color="navy"><b>new</b></font> BlockingTaskOperationResponseHandler();
        taskClient.complete(task1.getId(), <font color="red">"john"</font>, null, taskOperationHandler);
        taskOperationHandler.waitTillDone(1000);
 
        Thread.sleep(1000);
 
        assertProcessInstanceComplete(instance);
    <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In the example we can notice several configurations elements:</p><ul><li style="text-align: start;">knowledge base is configured to be shared between test cases under 'common' shared key</li><li style="text-align: start;">knowledge session will have registered handler for 'Human Task' work items</li><li style="text-align: start;">knowledge session will have a console logger configured</li><li style="text-align: start;">human task server will be configured with 'org.jbpm.task' persistence unit and will add two users once it's started (john, Administrator)</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>As mentioned on the comments, working with human tasks is still quite complex so an alternative approach is introduced:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">@RunWith(JbpmJUnitRunner.class)
@KnowledgeBase(source=<font color="navy">{</font><font color="red">"script.bpmn2"</font>,<font color="red">"service.bpmn2"</font>,<font color="red">"usertask.bpmn2"</font><font color="navy">}</font>, sharedKey=<font color="red">"common"</font>)
@KnowledgeSession(handlers=<font color="navy">{</font>@WorkItemHandler(taskName=<font color="red">"Service Task"</font>, handler=ServiceTaskHandler.class),
                    @WorkItemHandler(taskName=<font color="red">"Human Task"</font>, handler=WSHumanTaskHandler.class)<font color="navy">}</font>, logger=Logger.CONSOLE)
@HumanTaskSupport(persistenceUnit=<font color="red">"org.jbpm.task"</font>, users=<font color="navy">{</font><font color="red">"john"</font>, <font color="red">"Administrator"</font><font color="navy">}</font>)
<font color="navy"><b>public</b></font> <font color="navy"><b>class</b></font> JbpmJUnitRunnerTest <font color="navy">{</font>
 
          <font color="navy"><b>protected</b></font> org.drools.KnowledgeBase knowledgeBase;
          <font color="navy"><b>protected</b></font> StatefulKnowledgeSession session;
          <font color="navy"><b>protected</b></font> TestTaskClient taskClient;
 
        @Test
          @LifeCycle(phases=<font color="navy">{</font>LifeCyclePhase.CLAIM, LifeCyclePhase.START, LifeCyclePhase.COMPLETE<font color="navy">}</font>)
          <font color="navy"><b>public</b></font> <font color="navy"><b>void</b></font> testHumanTask() <font color="navy"><b>throws</b></font> Exception <font color="navy">{</font>
                    ProcessInstance instance = session.startProcess(<font color="red">"UserTask"</font>);
 
                    taskClient.performLifeCycle(<font color="red">"john"</font>, <font color="red">"en-UK"</font>, <font color="navy"><b>null</b></font>);
 
                    assertProcessInstanceComplete(instance);
          <font color="navy">}</font>
<font color="navy">}</font>
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>So, here you can see a quite substantial change in code lines to achieve exactly the same result as previous example. So at the method level you can define what life cycle operation of human task you would like to invoke, using @LifeCycle annotation. That of course is interesting if you would like to invoke exactly the same life cycle phases for all your human tasks within test case, for instance testing positive path for the entire process.</p><p>But if you would like to have it on task instance level you can specify the phases on execution of performLifeCycel method of testTaskClient.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>An extension of regular TaskClient was introduced (TestTaskClient) that was equiped with two methods:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code jive-java">performLifeCycle(String user, String locale, HashMap input)
performLifeCycle(String user, String locale, HashMap input, LifeCyclePhase[] phases)
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>obviously it does not cover all possible use cases but as it was said it is experimental and will be enhanced hopefully soon (if you find it useful).</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Ok, so that is it! I hope you can provide some feedback about it and hopefully we can get a valuable discussion around it and what's even more important</p><p>maybe we start using it on daily basis so everybody could benefit from it.</p><p>Attached draft version of the library.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Looking forward to your comments</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>P.S.</p><p>If you are interested in the complete module you can find it at: <a class="jive-link-external-small" href="https://github.com/mswiderski/jbpm/tree/master/jbpm-test-support">https://github.com/mswiderski/jbpm/tree/master/jbpm-test-support</a> It is now merged with the jBPM code base as additional module</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-17345">going to Community</a></p>
<p style="margin: 0;">Create a new document in jBPM at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2034">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>