 | Level: Intermediate David J.N. Artus (artusd@uk.ibm.com), Consulting IT Specialist, IBM
23 Aug 2006 Automated testing provides a repeatable and efficient means of verifying the quality of solution components. This article applies automated testing methods to Service Component Architecture (SCA) modules to further enhance the integrity of SOA applications in WebSphere® Process Server and WebSphere ESB environments.
From the IBM WebSphere Developer Technical Journal.
Introduction
If you are the author of a Service Component Architecture (SCA) module, your primary responsibility is to provide a reliable implementation of the service interfaces that you export from your SCA module. Automated testing of the module interfaces enables the SCA component developer to use a repeatable and efficient means of verifying the quality of the delivered components.
This article looks at the implementation of sets of tests of module interfaces; testing that for some specified input data, a particular response is obtained. A follow-on article will discuss testing more complex components, such as BPEL processes, where you also need to consider the testing of side effects.
Sample scenario
We will be testing a very simple component that validates a UK postcode and returns details of the addresses that correspond to that postcode. The files that are applicable to this example are included in a downloadable zip file for your convenience.
This postcode component has its interface defined in library L_MailService and the component is delivered in module MP_MailService in the download file. Figures 1 through 3, below, show the IBM WebSphere Integration Developer assembly diagram, component interface, and the definition of the PostCodeDetails data object returned by the service operation we want to test.
Figure 1. Assembly diagram: Component and Export
Figure 2. getDetailsForPostCode operation
Figure 3. PostCodeDetails business object
If we were developing such a component for actual use, we would likely write quite a few different tests that provide many combinations of input data. For the purpose of this article, though, we will write just two:
- A test that invokes the service with a valid postcode and checks that a known set of data is returned.
- A test that supplies an invalid postcode and checks that a fault occurs.
Test preparation
Before we can actually begin to write our tests, there are some preparatory steps you must perform. At a high level, these are:
- Install JDK update
- Import test utilities
- Create test module
- Set module dependencies
- Add the Cactus framework to the test project
- Assemble module
A. Install JDK update
Using the Cactus framework exposes a defect in the version of the JDK for Windows® platforms delivered with WebSphere Integration Developer V6.0.1, which is fixed in J2RE 1.4.2 IBM Windows 32 build cn142-20050929 (SR3) and later versions of the J2RE. You can either apply this fix to your WebSphere Process Server test environment using the appropriate IBM SDK installer or upgrade your test environment to WebSphere Process Server V6.0.1.2, which includes J2RE 1.4.2 IBM Windows 32 build cn142ifx-20060209 (SR4-1)
You will need to apply this to your WPS test environment using the appropriate .
B. Import test utilities
Utilities for working with Service Data Objects (SDO) have been included with this article. These utilities must be imported into the WebSphere Integration Developer workspace. The Project Interchange File (PIF) included in the download zip file contains these three libraries (among others):
- J_ScaUtiltiies
- LT_ScaJUnitTest
- LT_ScaTest.
If you plan to work through this article then you will also need to import the module we are testing: MP_MailService and its interface library L_MailService. As you will see, this contains only a trivial implementation of the interface, just sufficient enough to enable our tests to execute.
To import these modules into your workspace using WebSphere Integration Developer, select File => Import. In the Import dialogue, select Project Interchange, and then Next. Browse to the download zip file. Select the modules to import and click Finish. In the Business Integration view of the Business Integration perspective, you should now see something similar to Figure 4.
Figure 4. MailService with PostCode implementation
C. Create test module
Our tests will be created in a module that will then be deployed to a server. We must create this test module.
In the Business Integration perspective, go to the Business Integration view. Right-click then select New => Module. In the New Module dialogue, enter a name such as MT_TestMailService and click Finish. We are going to create our tests in a dynamic Web application in the MT_TestMailService module. However, we should note that the standard J2EE projects associated with a SCA module are generated by the tooling and are effectively transient artifacts. Therefore, we will create a new dynamic Web application that will hold our tests.
Switch to a Web perspective. In the Project Explorer view, expand Enterprise Applications. Right-click on MT_TestMailService, then select New Dynamic Web Project. In the New Dynamic Web Project dialogue, enter a name such as MT_TestMailServiceJUnitWeb and click Finish.
D. Set module dependencies
We need to ensure that the association between this new Web project and the test module is recorded, and that the correct libraries dependencies are created.
Switch back to the Business Integration perspective, Business Integration view. Select MT_TestMailService and double-click to open the Dependency editor. Expand Libraries and use the Add function to make the following libraries available to our tests:
- L_MailService (this giving access to the module we are testing)
- J_ScaUtilities
- LT_ScaJUnitTest
- LT_ScaTest
Expand J2EE and use the Add function to add MT_TestMailServiceJUnitWeb to the SCA module. Your dependency editor should now look like Figure 5.
Figure 5. Test module dependencies
Save your changes. We now need to explicitly add the libraries to the Web project build and runtime classpaths. Return to the Web perspective. In the Project Explorer, right-click on the MT_TestMailServiceJUnitWeb project, then select Properties. Select Java JAR Dependencies, and then check each of the four libraries we just added (Figure 6).
Figure 6. JUnit Web project, dependent JARs
Click OK to save these changes.
We have now completed setting up our module and library dependencies. Next, we need to make the Cactus test framework available to our tests.
E. Add the Cactus framework to the test project
Our example exploits the JUnit and Cactus frameworks, and so we need to make these framework libraries available to our test module. JUnit is a widely adopted open source testing framework. There is explicit support for JUnit version 3.8 in the Eclipse environment delivered with WebSphere Integration Developer. You will find the JUnit libraries junit-3.8.1.jar in the eclipse/plugins/org.junit_3.8.1 directory in your WebSphere Integration Developer installation.
The Apache Jakarta open source Cactus framework enables the use of JUnit in a server environment. You will need these libraries delivered with the Cactus download (listed here are the versions we used):
- aspectjrt-1.2.1.jar
- cactus-1.7.1.jar
- commons-httpclient-2.0.2.jar
- commons-logging-1.0.4.jar
We need to make these JAR files available to our test module, and also configure two servlets that are used by the Cactus runtime:
The Cactus libraries can be packaged with our test Web application by adding them to the WEB-INF/lib directory. To do this, switch to the Web perspective, Project Explorer view, and expand Dynamic Web Projects => MT_TestMailServiceJUnitWeb => WebContent => WEB-INF, revealing the lib directory. You can now drag the five JAR files to the lib directory, as shown in Figure 7.
Figure 7. Cactus and JUnit JARs
It is easiest to enter the Cactus servlet definitions by cutting and pasting directly into the Web application deployment descriptor. In the same expanded view of MT_TestMailServiceJUnitWeb right-click the entry DeploymentDescriptor: MT_TestMailServiceJUnitWeb, then select Open with => Text Editor, which will open a text editor view. Paste the servlet and servlet mapping entries shown below into the text editor, between the existing description and welcome file elements:
<display-name>MT_TestMailServiceJUnitWeb</display-name>
<servlet>
<servlet-name>ServletRedirector</servlet-name>
<servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
<init-param>
<param-name>param1</param-name>
<param-value>value1 used for testing</param-value>
</init-param>
</servlet>
<servlet>
<servlet-name>ServletTestRunner</servlet-name>
<servlet-class>org.apache.cactus.server.runner.ServletTestRunner
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ServletRedirector</servlet-name>
<url-pattern>/ServletRedirector</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ServletTestRunner</servlet-name>
<url-pattern>/ServletTestRunner</url-pattern>
</servlet-mapping>
<welcome file list>
|
Save and close the text editor. You could now re-open the deployment descriptor using the more typical Deployment Descriptor editor. If you do, you should see the two servlets you added in the Servlets tab (Figure 8).
Figure 8. Cactus servlets
F. Assemble module
Finally, our test module will need access to the interface library of the module we are testing. We also need our test module to invoke the components we are testing, which we will do by importing suitable interfaces to our test module and wiring them properly.
Switch back to the Business Integration perspective, Business Integration view, expand the MT_TestMailService project, and open the Assembly editor. Add an import to the assembly diagram, rename it to PostCode, and then add an the I_PostCode interface to the import. Generate an SCA binding for the import. Your diagram should now look like Figure 9.
Figure 9. Import with interface to test, SCA binding
In the Binding tab of the Properties pane browse and select PostCodeExport from the MailService module, hence binding this import to the specific module we are testing (Figure 10).
Figure 10. Import bound to module under test
You need to make this import available to your test Web application, which is a non-SCA project, so you will need a standalone reference. Add a standalone references icon to your diagram and wire it to your import. You may be asked two questions:
- First, whether you want to make a matching reference: click OK.
- Second, whether you want to convert the WSDL interface to a Java™ interface. It is important that you accept this option by selecting OK. Doing this simplifies the code needed to inspect the results of the service invocation.
Your assembly diagram should now look like this Figure 11.
Figure 11. Standalone reference to PostCode service, with Partner Name
Take a note of the Partner Reference name; you will need this when your test invokes the service. Save the Assembly diagram.
 |
Create tests for SCA components
With our preparations completed, we can now begin to write unit tests. We're going to begin by creating a test invoking the getDetailsForPostCode() service operation with what we expect to be a valid PostCode and then check the response data. We will use standard SCA and SDO programming techniques. As you will see, these are quite verbose and writing tests like this would be relatively time-consuming. However, we want to exercise the preparatory work we've carried out before we consider other, simpler ways of writing these tests.
We will first create a JUnit test class, add a single test to the class, and then, finally, execute the test.
The test class
The usual programming model with JUnit version 3.8 is to create a test class that extends one of the TestCase classes provided by JUnit. In our case, we are using the Cactus framework to execute our tests on the server, and so we must extend the Cactus test class org.apache.cactus.ServletTestCase.
Go to the Web perspective, Project Explorer view, and expand Dynamic Web Projects => MT_TestMailServiceJUnitWeb => Java Resources => JavaSource. Right-click on Java Source and select New => Package to create a suitable package. Right-click the package and select New => Class to create the class, entering code as follows:
package org.djna.mailservice.test;
import org.apache.cactus.ServletTestCase;
public class PostCodeTest extends ServletTestCase {
}
|
We can then add one or more test methods to this class. Because we have added the class to the Web application, when we add our module to the server our test class will be available for execution in the server environment. The test class represents the usual unit of test execution that occurs while you are developing, and so we should consider carefully how many tests to include in any one class. Too few, and the management of the classes becomes onerous. Too many, and the time to execute a class becomes wearisome. As rule of thumb, five to ten test cases per class seems about right.
The test methods
The JUnit 3.8 naming convention states that all test method names should begin with word test. The methods take no parameters and are void. Test failures are indicated by throwing unchecked exceptions, typically by using JUnit-provided assertion and failure methods. Test success is indicated by completion of a test method.
Our test method, then, looks like this:
import java.util.List;
import org.apache.cactus.ServletTestCase;
import com.ibm.websphere.sca.Service;
import com.ibm.websphere.sca.ServiceManager;
import commonj.sdo.DataObject;
import com.ibm.swservices.sca.test.junit.ScaTestExecutor;
public void testGoodPostCode() {
Service service = (Service) ServiceManager.INSTANCE
.locateService("I_PostcodePartner");
DataObject postCodeDetails
= (DataObject)service.invoke(
"getDetailsForPostCode", "BR1 0AB");
assertEquals("Bradford", postCodeDetails.getString("city"));
assertEquals("Yorkshire", postCodeDetails.getString("county"));
List addressList = postCodeDetails.getList("addressList");
assertEquals(2, addressList.size());
assertEquals("12, Haworth Terrace",
postCodeDetails.getString("addressList[1]/address"));
assertEquals("13, Haworth Terrace",
postCodeDetails.getString("addressList[2]/address"));
} |
The code shows:
- Use of the service manager to access the service via the Partner Reference name:
I_PostcodePartner.
- Invocation of the service operation with postcode
BR1 0AB.
- A succession of assertions about the data returned by the operation. Note in particular the XPath expressions used to navigate the DataObject. We use expressions such as
addressList[1]/address to access the individual address strings within the addressList; the first element in the array having an index of 1.
Paste this code into your test class and save it. With this code in place, we are now ready to execute the test.
Executing the tests
First, we need to add the test module to the server. We will assume that you already have a suitable WebSphere Process Server test environment in your WebSphere Integration Developer installation. Make sure that this server is started, then in the Web perspective, Servers view, right-click on the server then select Add Remove Projects. And add both MP_MailServiceApp and MT_TestMailServiceApp applications to the server.
We now we have our test class available for execution in two contexts:
It is a class deployed to a server and running in an SCA environment.
The class is available to a Cactus servlet and so can be executed when suitable requests are delivered to that servlet.
It is a Java class that can be executed standalone as a JUnit Test.
When executed standalone, the Cactus framework will use the test class as a proxy for the class deployed in the server and invoke the Cactus servlet.
The Eclipse JUnit facilities enable us to execute a standalone JUnit test class by right-clicking and selecting Junit Test. However, our test uses Cactus to communicate with the server and so we must provide a command line argument to specify where the server is running.
In the Web perspective, Project Explorer view, select the PostCodeTest class and then from the Run menu, select Run... to display the Run dialogue. Select JUnit in the list of possible Configurations and click New. Observe in the Test pane that the project and test class values are filled in. Also observe that you can use this dialogue to initiate a family of tests; all classes in a chosen directory. Select the Arguments pane. Under VM arguments enter the following code(Figure 12):
-Dcactus.contextURL=http://localhost:9080/MT_TestMailServiceJUnitWeb
Figure 12. Run configuration for Cactus test
Note that this specifies the localhost and port 9080; if your server or port for HTTP requests are different, you will need to adjust this string to match your choices.
Select Run to initiate the test.
Now that you have established this launch configuration, in future you will be able repeatedly execute this class simply by selecting it and clicking Run => JUnit Test. The JUnit view then shows the result of running the test (Figure 13).
Figure 13. Results of test exceution
You can re-execute the tests selectively from the JUnit view; right-click the class or test, then select Run.
Externalising the test data
We mentioned earlier that the creation of the details of the test case is somewhat laborious, requiring extensive use of the SDO programming APIs. In our simple example, the degree of difficulty may not seem excessive, but for realistic applications with data objects that may well be very much larger and involve many layers of nesting, the work of creating input data for a service and then validating the results promises to be very significant. It seems wise, then, to drive the tests away from external configuration files holding XML representations of the data objects. When creating families of tests, it then becomes a simple matter of copying and modifying XML files; in practice, this proves to be very much simpler and less error prone than writing SDO code.
We have created a framework that enables the rapid development of such test cases. In our setup instructions above, we made the framework libraries available for use. The process for creating a test using the framework is:
- Modify the test code to use a set of utility classes
- Create a directory hierarchy for the configuration files
- Create a configuration file defining the test to be executed
- Create configuration files to describe the payload and the expected result
- Create data object XML files.
A. Modify the test code to use a set of utility classes
The SCA framework provides an ScaTestExecutor utility class that manages the loading of test data and executes the corresponding test. The code for test methods, then, becomes very simple:
public void testGoodPostCodeExternal() {
ScaTestExecutor executor = new ScaTestExecutor(getClass(), getName());
executor.executeServiceTest();
}
public void testBadPostCodeExternal() {
ScaTestExecutor executor = new ScaTestExecutor(getClass(), getName());
executor.executeServiceTest();
}
import com.ibm.swservices.sca.test.junit.ScaTestExecutor;
// ...
|
The ScaTestExecutor constructor takes the test class and the name of the test as parameters. (The JUnit framework provides the getName() method to enable programmatic access to the test method name.] The ScaTestExecutor then applies naming conventions to determine the location of the configuration files; we will describe that convention next.
You might feel that the very repetitive nature of the test methods indicates that some refactoring should be possible. Indeed, the JUnit framework would let us create a test suite dynamically at run time, the suite being derived from the available test data. However, we found that the Eclipse-JUnit integration did not work as well with such suites; we were not able to quickly re-run single failed tests. We therefore prefer to create the explicit test methods as shown.
B. Create a directory hierarchy for the configuration files
We anticipate that when testing a realistic module, with many service operations - and especially when testing BPEL processes - we will have many tests to manage. So, if we are to have many corresponding XML files, it is important to organise these in some manner. The ScaTestExecutor class implements a simple naming convention, specifying a directory hierarchy for organising the XML files. To construct this directory hierarchy, right-click then select New => Other => Simple => Folder
(Figure 14).
Figure 14. Test data hierarchy
The elements of the hierarchy are:
The test data directory hierarchy is rooted in the test class package directory, in our case: org.djna.mailservice.test. This enables the XML files to be loaded as resources by the test class classloader. There is one directory per test class, whose name is derived from the test class name by appending the suffix -Data. Within that directory, we have one directory per test method, whose name exactly matches the method name. Within the method directory we have test definitions. These are the XML files defining the tests to be executed, and they have the extension .tspec (described next). You may have several .tspec files for each test method; they will be executed in alphabetic order.
C. Create a configuration file defining the test to be executed
The Test definitions are serialised instances of a business object. The ScaTestSpecification data type is delivered in the library LT_ScaTest, which you added to your workspace at the beginning of this exercise. Its structure is shown in Figure 15.
Figure 15. Test specfication data type
You can specify the service partner and method to be invoked, the payload, and the expected outcome. Both the payload and expected outcome may be simple integers or strings, or can reference further XML files containing serialised data types. If your test specification needs are more sophisticated, perhaps you need additional primitive types, or perhaps invoke services with multiple parameters; then, the ScaTestExecutor class can be extended (its source is included with this article).
The .tspec files contain XML to the ScaTestSpecification. The specification corresponding to the PostCode test we wrote earlier is:
<?xml version="1.0" encoding="UTF-8" ?>
<ScaTest:TestDefinition
xsi:type="ScaTestFramework:ScaTestSpecification"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ScaTestFramework="http://LT_Utilities"
xmlns:ScaTest="http://scatest/issw/ibm/com">
<service>I_PostcodePartner</service>
<method>getDetailsForPostCode</method>
<payloadString>BR1 0AB</payloadString>
<description>Get details for good postcode</description>
<expectedResultFile>GoodPostCodeDetails.xml</expectedResultFile>
</ScaTest:TestDefinition>
|
You see here the service partner and method, I_PostcodePartner and getDetailsForPostCode, and the input string BR1 0AB. You can also see that the expected result, a data object with many fields, is specified in a separate file (discussed in the next section). Also notice that the test has a textual description; this will be written to the logs when the test executes, which can be helpful in the event of errors occurring to correlate between errors and a specific test.
Our testBadPostCodeExternal can be specified in a similar way, we specify a non-existent PostCode and a specific fault should result:
<?xml version="1.0" encoding="UTF-8" ?>
<ScaTest:TestDefinition
xsi:type="ScaTestFramework:ScaTestSpecification"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ScaTestFramework="http://LT_Utilities"
xmlns:ScaTest="http://scatest/issw/ibm/com">
<service>I_PostcodePartner</service>
<method>getDetailsForPostCode</method>
<payloadString>Bad Post Code</payloadString>
<description>Bad postcode - should fault</description>
<expectedFaultName>notFound</expectedFaultName>
</ScaTest:TestDefinition>
|
To create the tspec files in the test data folders, right-click on the folder, then select New => Other => Simple=> File and paste the contents shown. You may notice that the creation of this test required only a simple copy and modification of the previous test.
D. Create configuration files to describe the payload and the expected result
The testGoodPostCodeExternal test requires the specification of the expected return data, a PostCodeDetails data type. The test specification includes the line:
<expectedResultFile>GoodPostCodeDetails.xml</expectedResultFile>
referencing the file GoodPostCodeDetails.xml, which needs to be placed in the same location as the test specification.
The contents of the file would be:
<?xml version="1.0" encoding="UTF-8"?>
<_:TestDefinition xsi:type="l:PostCodeDetails"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:l="http://L_MailService"
xmlns:_="http://scatest/issw/ibm/com">
<postCode>BR1 0AB</postCode>
<city>Bradford</city>
<county>Yorkshire</county>
<street>Haworth Terrace</street>
<addressList>
<address>12, Haworth Terrace</address>
</addressList>
<addressList>
<address>13, Haworth Terrace</address>
</addressList>
</_:TestDefinition> |
Create the expected result file by right-clicking on the folder, then select New => Other => Simple => File, and paste in the contents shown. A technique for creating such files is described in the next section. However, with this file in place our tests, we are now ready to execute. When we changed our test code earlier, you will notice that the Web application restarted on the server, and the console would show a message such as:
[22/05/06 12:40:35:533 BST] 00000051 ApplicationMg A WSVR0221I: Application
started: MT_TestMailServiceApp
and hence the new version of the application -- and its associated test data -- is automatically deployed to the server.
There are several ways in which you can now launch the test:
E. Create data object XML files
Data types for realistic business applications are often both large and complex, having many properties and many levels of nesting. Creating XML representations of these is tedious and error-prone. A utility that will write a sample XML files for any given data type is included with this article: com.ibm.issw.archive.ut.data.TestDataCreator.
The utility is packaged as a test class andis invoked as a JUnit/Cactus test. You will find it in our example Project Interchange File in the MT_TestMailJUnitWeb project. To use this class with your own application, you will need to include your own data types on its classpath. That is most easily achieved by copying it your own test project, as we have.
If you want experiment with the TestDataCreator, you can import our version of the MT_TestMailJUnitWeb from the interchange file supplied in the download file, and replace your own version. However, this will replace all of your work in this project, so backup anything you want to keep.
To create a sample XML file, you need to modify the code to reference the namespace and data type you want to use (Figure 18).
Figure 18. Data type name and namespace
In our case, these are http://L_MailService and PostCodeDetails. We modify the TestDataCreator to reference these values:
public void testCreateAnyData() {
try {
m_logger.finest("testCreateAnyData entry");
String schema = "PostCodeDetails";
DataObject test = m_bof.create("http://L_MailService", schema);
|
Next, execute this class as a JUnit test, remembering to set the Cactus argument on the run configuration. When TestDataCreator executes successfully, it will write a message to the application server console, indicating the path of the sample file that was created:
[22/05/06 10:21:50:343 BST] 00000055 TestDataCreat I Written C:\IBM\WID601\pf\wps\PostCodeDetails.xml
The contents of the file will be in this form:
<?xml version="1.0" encoding="UTF-8"?>
<_:TestDefinition xsi:type="l:PostCodeDetails"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:l="http://L_MailService"
xmlns:_="http://scatest/issw/ibm/com">
<postCode>postCode value</postCode>
<city>city value</city>
<county>county value</county>
<street>street value</street>
<addressList>
<address>address value</address>
</addressList>
<addressList>
<address>address value</address>
</addressList>
</_:TestDefinition> |
We can use this as the basis for our expected test data, and indeed this is how we created the sample in the previous section.
Conclusion
This article demonstrated how a set of tests for an SCA module can be defined and executed as simple XML definitions using a simple framework. That framework and the ideas it represents are open to adaptation for more complex scenarios.
Perhaps because we spelled out the specifics of test construction, the resulting exercise might seem rather lengthy, but in practice the amount of work to build and execute the tests is far from excessive. The tests described here were created in under 30 minutes, taking screen shots as we progressed.
Automated testing in this style is an important technique for developing high quality reusable components and I would strongly recommend that all serious development environments with WebSphere Integration Developer define and adopt an approach of this kind.
In a future article, I plan to explain how to apply these ideas to the testing of long-running business processes and other components with side-effects.
More in this series
Download | Description | Name | Size | Download method |
|---|
| Sample components | ScaJunit-PIF-v1.1.zip | 1.4 MB | HTTP |
|---|
Resources
About the author | 
| | David Artus is member of the IBM Software Services for WebSphere team working out of the
IBM Hursley Lab in the UK. He has provided WebSphere consultancy and mentoring since he joined
IBM in 1999. Prior to joining IBM David worked in a variety of industries including
Investment Banking, Travel and IT Consultancy. His interests include design of distributed
systems, object technologies, and service-oriented architectures. |
Rate this page
| |
