Using BPELUnit for testing processes in Riftsaw - Part 1

BPELUnit (http://www.bpelunit.net) is a testing framework intended for testing BPEL processes on a request-response basis. It comes with a plug-in for Eclipse for creating and running BPEL test suites as well as a possibility to run automated tests via Ant tasks. This makes it possible for including BPELunit tests in the Riftsaw integration tests. In this post I'll try to give you some tips and instructions on how to test a process deployed on Riftsaw using the BPELUnit Eclipse plug-in.

Preparation:

If you start from the scratch you will need:

• JBoss Application Server 5.1.0 GA
• JBoss ESB 4.7 GA
• Eclipse 3.5 SR1 (Galileo)
• Riftsaw 2.0-CR1
  

1. Unzip JBossAS, JBossESB and Riftsaw to appropriate directories.
2. Set the environment variable JBOSS_HOME to point to JBossAS directory.
3. Edit ESB_HOME/install/deployment.properties to modify org.jboss.esb.server.home to point to JBOSS_HOME directory
4. Edit RIFTSAW/install/deployment.properties to modify AS and ESB home directories.
5. From ESB_HOME/install run “ant deploy” - this deploys ESB to the application server.
6. From RIFTSAW/install run “ant deploy” - this deploys Riftsaw to the application server

• BPELUnit 1.1.0 Eclipse plug-in

1. Run Eclipse and choose a workspace directory.
2. Go to the URL above and follow instructions on how to install BPELUnit into Eclipse.

Last thing remaining is to verify that Riftsaw has been deployed, start the server and deploy the sample project that we are going to test:

1. In Eclipse, select to add a server and choose your installation of JBoss AS
2. Start the server
3. After the start-up navigate to http://localhost:8080/bpel-console.
4. If a login dialog comes up, Riftsaw was installed successfully.
5. Log in with “admin”/”password” credentials, you will see that no processes are deployed.
6. From RIFTSAW/samples/quickstart/hello_world directory run “ant eploy”.
7. Refresh the Process Definitions window. A Hello World process should appear.

Creating a test:

Now that everything is ready it's time to finally do some testing. On the BPELUnit website there is a Hello World tutorial which I strongly recommend to go through as the following example will be very similar. The only difference will be that we're going to use a Hello World sample that we have just deployed on the server. With BPELUnit we can create and run a test that will verify that the sample is working correctly. Here are the steps for setting up this project in Eclipse:

1. Create a new project in you workspace using File -> New -> Other -> General -> Project
2. Name it “bpelunit_test”
3. Copy RIFTSAW/samples/quickstart/hello_world/bpelContent/HelloWorld.wsdl to the “bpelunit_test” directory in your Eclipse workspace
4. Refresh the project to see the WSDL file has been added
5. Add a test suite into the project via File -> New -> Other -> BPELUnit -> BPELUnit Test Suite

The test suite we've just created is an xml file that defines which process is going to be tested and how. This Hello World process functionality is that it takes a string input, connects it with “ World” and sends it back. So if the input is “HELLLO” the output should be “HELLO World”. And this is what we're going to test. Now fill the details as following:

• Base URL: http://localhost:7777/ws (prefix for mock service url, unimportant for now)
• PUT Name: HelloWorld
• PUT Type: Fixed deployer
• WSDL: Click “Browse” and select the HelloWorld.wsdl file

Now save (Ctrl+S). Change the view under the form to “Source” and verify that it looks like the code below. If not, you can modify it so it does.

<?xml version="1.0" encoding="UTF-8"?>
<tes:testSuite xmlns:tes="http://www.bpelunit.org/schema/testSuite">
<tes:name>suite.bpts</tes:name>
<tes:baseURL>http://localhost:7777/ws</tes:baseURL>
<tes:deployment>
   <tes:put name="HelloWorld" type="fixed">
       <tes:wsdl>HelloWorld.wsdl</tes:wsdl>
   </tes:put>
</tes:deployment>
<tes:testCases/>
</tes:testSuite>

This is in fact how the test suite file really looks like. Now let's switch back to the “Test Suite” view and finally add a test case that will let us test the functionality of the process. In the section “Test Cases and Tracks” click “Add”, fill “SayHello” as a name and confirm. The SayHello test case is created which you can see in the list. Under this test case is a “client” node. This represents a client partner that will invoke the process. Now we will specify what message is going to be sent and what we are expecting to get. To do this follow these steps:

1. Select the “client” node under the SayHello test case.
2. In the “Activities” panel on the right click the “Add” button.
3. Select “Send/Receive Synchronous” - this is the most basic a request-response activity.
4. Notice that service, port and operation are already filled as there's only one operation - “hello”.
5. Check the box “Enter XML literal” and switch to “XML to be sent” tab.

We've done this because we want to specify what data will be sent to the process in the XML format. Now to the windows that appeared paste this code:

<TestPart>HELLO</TestPart>

This means the input string will be “HELLO”. Now click “Next” so we can specify what outcome we are expecting. Let's add a condition to check by clicking on the appropriate button. The “Expression” here is an expression in XPath format that will select the proper response XML node, in our case the outgoing message. Fill in these:

• Expression: //TestPart
• Value: 'HELLO World' (including the apostrophes)

Now click “Finish” and save the test suite (Ctrl + S). Switch back to the “Source” view and inspect the code that has been created. It should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<tes:testSuite xmlns:tes="http://www.bpelunit.org/schema/testSuite">
<tes:name>suite.bpts</tes:name>
<tes:baseURL>http://localhost:7777/ws</tes:baseURL>
<tes:deployment>
  <tes:put name="HelloWorld" type="fixed">
      <tes:wsdl>HelloWorld.wsdl</tes:wsdl>
  </tes:put>
</tes:deployment>
<tes:testCases>
  <tes:testCase name="SayHello" basedOn="" abstract="false" vary="false">
      <tes:clientTrack>
          <tes:sendReceive service="wsdl:HelloService" port="HelloPort" operation="hello" xmlns:wsdl="http://www.jboss.org/bpel/examples/wsdl">
              <tes:send service="wsdl:HelloService" port="HelloPort" operation="hello" fault="false" delaySequence="">
                  <tes:data>
                      <TestPart>HELLO</TestPart>
                  </tes:data>
              </tes:send>
              <tes:receive service="wsdl:HelloService" port="HelloPort" operation="hello" fault="false">
                  <tes:condition>
                      <tes:expression>//TestPart</tes:expression>
                      <tes:value>'HELLO World'</tes:value>
                  </tes:condition>
              </tes:receive>
          </tes:sendReceive>
      </tes:clientTrack>
  </tes:testCase>
</tes:testCases>
</tes:testSuite>

That's it, we've just created a test case that will call the “hello” operation with the “HELLO” string as input and then it will check that the return value is “HELLO World”. The process itself is already deployed so the only thing that's left is to launch this test on it.

Running the test suite:

In the Project Explorer window right click on the “suite.bpts” file and choose “Run As” -> “BPELUnit TestSuite”. Now a new left tab should appear that will show the test results. If everything works correctly, the bars are going to be filled with green color. You can expand the nodes to see the SOAP messages that have been sent and received.

This tutorial presented how can be processes that are deployed on Riftsaw simply tested thanks to the BPELUnit framework. In the next blog post we will use the other way of using this tool – Ant build script. We are going to include BPELUnit testing into the present integration tests which will give us the opportunity to automate testing via this framework.

So have fun testing BPEL and please share your thoughts in comments :-)

-- Petr