BPELUnit Tutorial - Unit Testing BPEL processes with Test Coverage- Part I

Author:	Buddhika Chamith
Version:	2009-07-22

This tutorial describes how the BPELUnit framework can be used to unit test a BPEL process and to calculate the achieved test coverage. Test coverage in this context is the number of activities that are executed along the execution path of a BPEL process for a particular test case. These statistics will be displayed at the end of the test run as a percentage of the total activities of the BPEL process. The ODE BPEL process engine will be used to deploy the process.

To proceed with the tutorial it is assumed that that you know how to develop and understand a rudimentary BPEL process.

Prerequisites

This tutorial assumes ...

that you can understand a simple BPEL process,
that you are familiar with SOAP messages,
that you have installed a ODE BPEL engine and it is currently running on the local machine,
and that you have installed BPELUnit in Eclipse.

Course of Action

Download and unzip the TranslatorProcess BPEL process: This process takes three strings for input.
- From language code
- To language code
- Text to be translated
If From and To language codes are the same, the process just echoes back the unmodified text to the client. If the language codes are different it invokes an external service named TranslatorService and channels the response of this service to the client.

In the first part of this two part tutorial a unit test will be created to test the branch which will just echo the output to the client. Therefore, no calls to the TranslatorService will be made in this test run.
To go ahead, download this process here. The version you can download is bundled with an Apache ODE deployment descriptor. However, the BPEL constructs used are so simple that you should be able to easily deploy this process on any server. If you are not familiar enough with BPEL, you can revisit the BPEL tutorials. Unzip the archive after downloading and make a note of this location.

Because we will replace the TranslatorService with a mock, we do not have to download and deploy the service. (We still require the TranslatorService up and running for the sake of completeness of the testing environment though no calls are going to be made to it in this test.)
Create a new Test Project: Create a new Eclipse project. The project does not need to have a special facade, therefore choose File/New/Project/General/Project and name the project Translator. Within this project, the BPELUnit test suite will be created.
Copy Process Artifacts in to Test Project: Create a directory named TranslatorProcess under the Translator project and copy all the artifacts of the process to it via Eclipse file import mechanism.
Create a new BPELUnit Test Suite: All test cases are defined in so-called Test Suites. Create a new test suite by choosing File / New / Other / BPELUnit / BPELUnit Test Suite. Save the suite file within the project. After you have successfully created the test suite, the Test Suite Editor should show up as illustrated in the following figure.

As you can see the suite editor consists of the following sections.
- Test Suite
- Process Under Test
- Partners
- Test Cases and Tracks
- Activities
The next steps deal with how each of these sections is to be filled in order to test this process.
Fill Suite Information: Leave default name for Suite Name and fill the Base URL as http://localhost:7777/ws. The Base URL is important for this tutorial since BPELUnit uses it as the base part of the URL of mock services.
Fill in Process Information: "Process Under Test" section deals with the general information about the process.
- As the PUT(process under test) name, give Translator.
- Since the process is going to be deployed in ODE select ODE Deployer as the PUT Type.
- Now it is time to select the process WSDL. Click the Browse... button and choose the TranslatorProcess/ TranslatorProcessArtifacts.wsdl. Please be aware that the WSDL file has to contain the correct endpoint address for your process. If you have deployed the BPEL process differently (not on Apache ODE or on another host), you will have to change the WSDL!
- Now we give the location of the process archive so that BPELUnit framework will be able to locate and then deploy this process to the ODE engine. For this click the hyper link "Configure Deployment Options... ". Following dialog comes up.
- Click Add... button to get the "Add an Option" dialog as show below.
- Click on Keys... button to get the set of deployment parameters associated with this deployment.
- Select DeploymentArchive from the list and click OK. Key value will be automatically filled in the "Add an Option" dialog. As the Value give the location of the deployment archive. BPELUnit can work with directory deployments as well as zip archive deployments. Relative paths will be resolved with the project root as the base directory. Since we have created a directory within our project and copied all the process artifacts to it we can use this directory. So give TranslatorProcess as the input for the Value field and click OK. Resultant dialog will be as follows.
- Click Finish to save the settings.
Specify partner service details: Because we want to mock the TranslatorService we have to specify partner service details. Therefore, click the Add... button in the partner section. Enter TranslatorPartner as the name and choose TranslatorProcess/ TranslatorService.wsdl for the WSDL file. Please note that we have given the same partner name as the partnerlink name of the service in the BPEL file. This is required since we will be using the option of automatically changing endpoint URL in the partner service's WSDL to the mock service URL. The way to set this option is described in later steps in this tutorial. Now the editor should look like this:
Create a new Test Case: Choose Add... in the Test Cases and Tracks section. Name the new Test Case Greet and do not alter the other settings. This time the test case has two partners: The already known client and a TranslatorPartner. The latter one will define the behavior of the mock.
Fill in activities of the partner tracks: This consists of defining a send/receive synchronous activity for client.
- Send a message to the Process:Select the client and choose the Add... button in the activities section. Choose the Send/Receive Synchronous activity and confirm. Choose for:
  
  Service: Translator
  
  Port: TranslatorPort
  
  Operation: process
- Copy the following XML into the "Data to be sent" text area.
```
<TranslatorProcessRequest 
xmlns="http://www.se.uni-hannover.de/soa08/tutorial/TranslatorProcess">
	<From>EN</From>
	<To>EN</To>
	<Text>Greetings</Text>
</TranslatorProcessRequest>
			
```
  Your dialog should look like the one in the figure now:
- Choose Next for defining the assertions for the response message. Assertions consist of an XPath query and an expected value. Choose Add and enter //tran:TranslatorProcessResponse/tran:Text as the XPath query and 'Greetings' as the expected value. Please be aware of the quotes that are necessary to denote that Greetings is an XPath string. Your dialog should then look like in the following figure:
- Now choose Finish to create the new activity.
This finishes the test suite modifications required to unit test this process. However since we are going to measure test coverage as well few more settings have to be changed in the BPELUnit Preferences.
Set Test Coverage Preferences:Access the BPELUnit Preferences by selecting Window/ Preferences/BPELUnit in Eclipse. Select the Test Coverage page under BPELUnit and check the "Coverage Measurement" check box. This will enable a check box group below. Here one can select which activities should be traced during test runs. In this case we are going to monitor whether invoke and assign activities were properly covered during the execution. So check invoke and assign check boxes as shown in the screenshot below.
Set Endpoint modification Preference:Next select Deployment page and you will see the following.
- Check the option "Automatically modify endpoints to simulated URLs" below. For this to work partner track names must be the same as the names of the partner links in the BPEL process as noted in step 7.
- Click OK to save the preference settings.
Set Deployer Preferences:This step is required if you are not running ODE on the local machine. If this is the case you have to give the URL of where the actual ODE deployment web service is running. To give it follow these steps.
- In the above page select ODE Deployer as the Deployer.
- Click Add... button besides the table.
- Input ODEDeploymentServiceURL as the Key and the web service endpoint of your ODE Deployment Service (e.g:http://192.134.12.1:8080/ode/processes/DeploymentService) as the value.
- Click OK.
- Click OK to save the preferences. This step is not necessary if ODE is running in local machine since the BPELUnit framework uses http://localhost:8080/ode/processes/DeploymentService as the default parameter value if no value is specified.
Run the Test Suite:Now we are ready to run the test. Select the suite.bpts file in the Project Explorer and choose Run as/ BPELUnit Test Suite from its context menu. The BPELUnit view should appear, in which you can observe the progress of the test run. Like with the JUnit view, a green bar means that everything went fine and a red bar means that a test failed. If you have done everything correctly, you should see a green bar like in the picture:
- In the bottom part of the BPELUnit view is an area for technical details. You can browse through the test run structure to inspect the SOAP messages, which were sent, and the assertions and their results.
- Also the Test Coverage view would come up showing you the test coverage results. If it does not come up automatically, open it by using Window/Show View/Other.../BPEL Category/Test Coverage. In this case it shows one assignment activity out of three was executed while the single invoke in the process (invoke to TranslatorService) was not executed in this test's execution path. This is because we have only triggered the if branch in the BPEL process. The else branch will be tested in the second part of this tutorial.