Skip to main content
This revision made March 05, 2013 20:23, by Olivier LeDiouris

Oracle SOA Testing utilities Wiki

This project provides snippets of code to - ideally - test whatever comes with a WSDL. It uses the utilities of the project ConsolidatedTestEnv (part of this workspace you are looking in).

To be able to write JUnit tests more efficiently, we've provided some base classes. Those classes are:


They implement the same interface:


This interface contains the following methods:

        public void firstOfAll();
        public String beforeInvoke(String payload);
        public void afterInvoke();
        public void beforeReceive();
        public String afterReceive(String payload);
        public void evaluate(String payload);
        public void onError(Exception ex);
        public XMLElement getResponsePayload();

Those methods have a default behavior, and the classes provided above do not have to be overriden if their standard behavior is good enough.

Standard Behavior

In the project ConsolidatedTestEnv, there is an Ant script that shows how to run tests based on those classes, it is named basic-test.xml. Here is an example of an Ant task implementing a test:

  <target name="unit.test.asynchronous.2.ways">
    Testing ASynchronous Two Ways Service
    outputfile: asynchronous.2.txt
    <junit printsummary="yes" fork="yes" showoutput="yes" failureproperty="">      
      <classpath refid="classpath"/>
      <formatter type="plain"/>
      <sysproperty key="verbose" value="${verbose}"/>
      <sysproperty key="" value="<font color='blue'></font>"/>
      <test name="" haltonfailure="no" outfile="asynchronous.2"/>
    <antcall target=""/>
  <target name="" if="">
    <exec dir="." executable="cat">
      <arg line="asynchronous.2.txt"/>
    <fail message="ASynchronous Two Ways Test stopped the process"/>

Several things to notice:

  • The name of the test, refering to one the classes mentioned above
  • The System property named "" containing the name of the properties file the test will refer to for execution

properties file

The properties file ( in the example, this file is part of the project), contains the following data:


Here is an explanation of the different items it contains:

wsdl.url The fully qualified URL to reach the WSDL of the service to test. Notice the variables ${} and ${soa.port.number}, thay are patched with the content of the properties found in This file is not mandatory anymore.
Also notice that you can write here a URL that does not need any patching. The name of the service to test. Must exist in the WSDL
service.port The name of the port to test. Must exist in the WSDL
service.operation The name of the operation to invoke. Must exist in the WSDL
service.ns.uri The namespace URI of the payload
service.input.payload.file The name of the file containing the input paylod to invoke the service with If the above does not exist, then the payload can be passed as a string. This property contains this string
service.output.payload.file In case the service returns a payload (ie non Asynchrounous-one-way), this property contains the name of the file containg the payload to compare the output to. If the above does not exist, the payload to compare the output to can be passed a a string using this property For asynchronous-two-ways services, the HTTP Port value used for the reply-to
service.response.timeout In case you want a timeout for the invocation, put it here in milliseconds. Your payload will be validated against the type definition coming with the WSDL. If the payload is invalid, the test will fail unless this property is set to true.
username If this property is set, then Policy Security will be set. A password will need to be provided.
password Same as above.
decrypt.async.response In case of an asynchronous two ways secured service, the response might come back encrypted. Setting this property to true will decrypt it before the afterReceive(), and as a result, before the evaluate().

The table above contains the variables supported by the base classes. If you are extending those classes, there is nothing preventing you from adding your own properties. This file would in fact be the right place to put them.

A note about the variable hierarchy

The file which has its name in "" can use metadata. You have seen that it can be patched with variable found in It will also be patched with the values of System.getProperties(), and finally with environment variables from the System level. For example, if you have in lines like this:

Java has been started with


and a the system level (shell)


then, in the file mentioned in "", a line like this:


It will be translated into:


Again, the order of the patches is:

  2. system properties
  3. environment variables

A note about SOAPFaultException

In case a SOAPFaultException is raised during invoke (for Synchronous and ASynchronous two ways services), the the SOAP Fault element is retreieved and returned as the expected payload.
This allows to do negative tests (i.e. when a Fault is thrown as expected, like on authentication failure, for example). Warning: In the case of ASynchronous-one-way services, the fault has to be managed using the onError() method, as no returning payload is expected.

A note about secured services

Secured services can be invoked easily. As we said before, you can set Policy Security by just adding the properties username and password in the properties file associated with the test.
One thing to notice though, is the system property named "". Notice in the service-test-samples.xml Ant script the target named "unit.test.synchronous.secured", which shows the test of a secured synchronous service.

  <target name="unit.test.synchronous.secured">
    Testing Synchronous Service, 
    with Security
    outputfile: synchronous.secured.txt
    <junit printsummary="yes" fork="yes" showoutput="yes" failureproperty="">      
      <classpath refid="classpath"/>
      <formatter type="plain"/>
      <sysproperty key="verbose" value="${verbose}"/>
      <sysproperty key="" value=""/>
      <sysproperty key="" value="./security/config/jps-config.xml"/>
      <test name="" haltonfailure="no" outfile="synchronous.secured"/>
    <antcall target=""/>

The file mentioned in this property must of course exist in your testing environment. In case security if required, the existence of this system property will be verified by the test class, and the test will fail if it is not set.

A note about the classpath

That's part of the beauty of Java, if something fails, there is a 50% chance that it's because of the classpath...
In the sample build files you will find in this workspace, the are quite substancial classpathes. They are based on a property named build.home, that is usually one level above the $JDEV_HOME.
There is also a a custom Ant task that will check if all the entries of the classpath exist. You will see for yourself the source of this task, as well as its definition, but here is the way to use it:

    <resolve.classpath verbose="false" 
      <path refid="classpath"/>                       

If an entry is missing, it will be reported.
If the haltonfailure property is set to "yes", the build will stop if an entry is missing.
In the provided samples, this task is part of the "init" target, which is the first one to run.

A note about parallel tasks

There is apparently a need for such things.
Let us take an example:
You have a Composite that will interact with a Human Task. This Composite has TestSuites implemented, and these are the ones you want to run.
The interaction with the HumanTask will be done with the TaskList API, it will poll the Human Task repository to see if the expected task(s) have shown up in the right lists, and simulate a user's behavior.
This will have to be done as the <ant-sca-test> target is running, i.e. in parallel.
We provide a high level mechanism to implement this kind of feature easily. We are using HTTP as the event and notification delivery mechanism.
All you have to do is to implement the process you want to run in parallel (the polling in the example above) using a testing.util.http.Worker interface.
An example of such a task is given in service-test-samples.xml, see the target named "parallel.task".

  <target name="parallel.tasks">
    <echo message="1. Start worker"/>
    <java classpathref="classpath" classname="testing.util.http.SampleMain">
      <arg line="-verbose on"/>
      <arg line="-port 3456"/>
      <arg line="-nbloop 100"/>
    <echo message="2. Wait... (Simulate parallel work)"/>
    <!-- The ant-sca-test would go here instead -->
    <java classpathref="classpath" fork="yes" classname="testing.util.http.WasteTime">
      <arg line="-wait 15000"/>
    <echo message="3. Kill them all"/>
    <java classpathref="classpath" fork="yes" classname="testing.util.http.Terminator">
      <arg line="-port 3456"/>
      <arg line="-verbose off"/>
    <echo message="4. Done"/>

What the tests do, by default

Based on the information contained in the file named by the "", the default tests will:

  • Get the EndPoint URL from the WSDL (this test will fail if the service is not found)
  • Check if the service is up and running
  • Validate the input payload against the type definition (found in the WSDL)
  • Check if the service name is valid
  • Check if the port name is valid
  • Invoke the service (possibly with a timeout, when appropriate)
  • Get the response payload (when appropriate)
  • When appropriate (non async-one-way), compare (using XMLDiff) the Body (or Fault) of the returned payload against the one provided in the properties service.output.payload.file or
  • the onError method fails, with the exception as a string (toString() method)

If anything else or more should be performed, then the base class of the test has to be overriden, as described in the next section.

Specific behavior

The methods contained in the ServiceUnitTestInterface interface should provide enough flexibility to who want to implement a specific behavior. Overriding those methods should be sufficient. But nothing is preventing anyone from implementing his own test classes if needed.
The methods of the interface are called in the following sequence:

Order Name Default behavior Comment
1 firstOfAll() None

Properties files are read, endPointURL is found, inputPayload is read.

2 beforeInvoke(payload) returns payload, unchanged

Payload is validated, service name, port name are validated, service is invoked as required.

3 afterInvoke() None Except for Asynchronous one way services
4 beforeReceive() None For Asynchronous two ways services only
5 afterReceive(payload) returns payload, unchanged Except for Asynchronous one way services
6 evaluate(returnedPayload) implements the validation on the output payload against the data passed through service.output.payload.file or Except for Asynchronous one way services
everywhere onError(exception) fail

If you look at the source of the base classes, you will notice that the properties read from the properties file are available from all the methods you would override or add, as a global protected java.util.Propeties Object named props.
This also mean that you are free to add your own properties in as well as in the properties file associated with the test.
There is in the same workspace a project named ServiceUnitTestSamples_level2 that contains examples of Unit test classes overriding the base ones, to implement a behavior different than the default one.
Among other things, they show how to patch the skeleton of a default input payload read from a file.

ADFbc Specific Test Classes

Using the above, we have implemented a couple of classes dedicated to the ADFbc services.
In some cases - specially when the job of the ADFbc operation is not a query - some ID might be returned by the service response, which makes it difficult to compare with a static document. Some value(s) will obviously be different, and that would be a problem.
The first idea would be to override the method afterReceive() or the method evaluate() to do the appropriate distinctions, but this implies an extension of the base class, to do everytime something very similar in every cases.
That is why we provide some base classes, extending the above, ready for ADFbc services testing.
They already override the afterReceive() method. They use additional parameters, living in the associated properties file, here is an example:{}createWorkerResponse//{}WorkerId{}Age

Notice the radical, and the numeric suffix. Those properties go by pair.
Their goal is to give the XPath expression to a text element, and the value to patch it with.
As the point of truth of an XPath expression in the namespace uri, and not the namespace prefix, the expanded syntax has to be used. It is a bit painful, but it is legal and standard.
In short: you must replace the namespace prefix + ":" with the namespace uri between curly braces.
Once patched, the response document can be compared to a static one.
In addition, in case you want to replace a full node (and not only the text element it contains), you can use:{}Age<ns:NewAge xmlns:ns="" extra-attr="value">As deep as you like</ns:NewAge>

Notice that in this case, the expanded syntax is not mandatory, as you provide the xmlns attribute if necessary.
But the value of this property MUST be a valid snippet of XML, with all required namespace URIs and possible prefixes.
Note that you can patch attributes as well:{}result/@{}type      

The available test classes (taking those properties in account) for this purpose are:

  • unittests.patterns.adfbc.ADFbcSynchronousServiceUnitTest
  • unittests.patterns.adfbc.ADFbcAsyncTwoWaysUnitTest

They are part of ServiceUnitTest.jpr, and as such part of jarServiceUnitTest.jar.

Services with Attachments

No problem!
A method getAttachmentIterator() has been added to the ServiceUnitTestHelp class.
I need more input from the people interested in managing attachments, in order to know what they want to do and see if there is a possibility to build something generic.
Today, there is a in the package samples.main of ServiceUnitTest.jpr.
xop attachments There is currently a pending ER (#9770497) for the XOP attachments. By default, the xop tags are not visible in the payload (envelope, body, etc). We asked for a property like KEEP_XOP for those elements to remain visible, so we can relate an attachement an its surrounding element and compare it with the right document.
Here is an example of what we mean:
In a returned payload like this

 <env:Envelope xmlns:env="" 
   <ns0:getWorkerResponse xmlns:ns0="">
    <ns2:result xmlns:ns2=""
      <ns1:Age xsi:nil="true"/>
      <ns1:Birthday xsi:nil="true"/>
      <xop:Include xmlns:xop=""
      <xop:Include xmlns:xop=""
    <ns1:Salary xsi:nil="true"/>
    <ns1:Bonus xsi:nil="true"/>
    <ns1:LastUpdated xsi:nil="true"/>

what is actually returned by the getSOAPBody or getSOAPEnvelope is this

 <env:Envelope xmlns:env=""
     <ns0:getWorkerResponse xmlns:ns0="">
       <ns2:result xmlns:ns2=""
         <ns1:Age xsi:nil="true"/>
         <ns1:Birthday xsi:nil="true"/>
         <ns1:Salary xsi:nil="true"/>
         <ns1:Bonus xsi:nil="true"/>
         <ns1:LastUpdated xsi:nil="true"/>

The xop elements are removed on purpose by the JAX-WS stack...
We need to have them to know for example that the attachment with ID ebd45ab2b1b64b1d915c89d7f22dac6d is a Resume. This ID is in the mime-header of the corresponding attachement.

Business Events

Some composite can be triggered by a business event.
A generic abstract class is provided in order to test those artifacts. The base class is living in ServiceUnitTest.jpr, its name is
It contains an abstract method named afterRaisingEvent() that must be overriden in the extended class.
The reason for that is that after raising an event, something else might be performed (like checking if the right composite has been started, maybe...).
Attention! In order to use the standalone J2SE Business Event Raising facility provided by those helper classes, a property has to be set at the server level, in the file $MW_HOME/user_projects/domains/<your domain>/


WLS Servers (including SOA server) must be bounced after modifying that one.

This unit testing class uses a slightly different properties file, like this:

 # security.username=Oliv
 # security.password=Secret
 # Some room below, for user specific properties
 # ...

The provider.url property can be patched as the other ones already mentioned, using ${} and ${soa.port.number}.
In case security is required, just like before, a system property named "" must be set and represent the path to jps-config.xml. The properties security.username and security.password are used for authentication.
An example of such a class is given in ServiceUnitTest.jpr, it is This very class is used in service-test-samples.xml, in the target unit.test.event. It goes along with the

Running a suite of such tests a build system

There is in the project ServiceUnitTest.jpr a class named, that relies on some properties file to know what test to run, in a given order.
There is also in the same workspace a project named ServiceUnitTestSample.for.CruiseControl, illustrating the point.
To use it, you have to have a file named, located at the root of the project containing the tests to run (i.e. sibling of the jpr file).
In case you need more than one test suite to live in the same project, you can do it by overriding the suite() method.

 public class DiscovererSample
   extends TestDiscoverer
   public static TestSuite suite()
     return TestDiscoverer.suite("");

The parameter of the suite() method is the path to the properties file. It can be a fully qualified path.
If not parameter is provided to this method, then the file taken in account will be

Here is an example:

 # Test(s) definition(s) file sample
 # One
 # Two
 test.description.2=Asynchrnous two ways with security and timeout. Wow!
 # Three

Note: The properties and delete.generated.class are used if the property use.asm is set to true
This property is deprecated (its default value is false), as a result, the 3 first lines could be ignored (and not used).

If you relate this file to the Ant build-files we talked about before, containing junit tasks, you will see that the is semantically equivalent.
Three exception though, some properties are generic for all tests:

  • This is the name of the directory where the generated test cases will be compiled. This must be a directory accessible for writing.
  • delete.generated.class In case you want to keep the generated classes on the file system after they've been loaded by the ClassLoader, set that one to false; true is its default value.
  • use.asm ASM is a Java byte code engineering library that you can use instead of the regular Java compiler that comes with the JDK 1.6. It generates the corresponding byte code and injects it in the ClassLoader, without having to access the file system. If this property is set to true (its default being false), then the two propeties mentioned above are useless and meaningless.
    If it is set to true, then you need to include in your project the asm jar-files, located for your convenience in ServiceUnitTest, under lib/asm, next to the XMLUnit ones. Name your test (not used for now)
test.description.X Description of your test (not used for now)
test.class.X The name of the TestCase class to run. Semantically identical to the test@name attribute of the junit Ant task
verbose.X If this is not clear, you need to talk to me (or your shrink)
skip.X Allows you not to run a given test case, if set to "true".

Notice that the X in the properties name in the table above is an int, beginning with 1 for the first test, and incremented by one for the subsequent ones.
The test suite will contain all the tests between 1 and the last one of the sequence. The construction of the suite stops when the sequence is interrupted (i.e. last item, or not incremented by one.
A sequence like 1, 2, 3, 4, 5 will build a suite of 5 tests.
A sequence like 1, 2, 4, 5, 6 will build a sequence of 2 tests.
A sequence like 1, 2, 2, 5, 6 will build a sequence of 2 tests.
A sequence like 2, 3, 4, 5 will build nothing.
In addition, you have transitions. This allows you - to some extend - to use the output of a previous test for the input of the next one.

This transition happens between test 3 and test 4.
It will patch the file - on the file system - named transition.input.xml. You need to make sure this file can be written in (i.e not read only...)
It will do two patches in this case, defined by the properties transition.from.xpath.X.Y and Notice the expanded form of the XPath expressions.
Important: Those XPath expressions must return one and only one node.
A commodity has been introduced, to address the case where you have to propagate some values accross steps, for example from test1 to test2... You can use system variables instead of XPath expressions, like this:

The variable "" is first set, and then used.
Whatever begins with "${" and finishes with "}" is considered as a system variable.
You can also notice the transition.from.literal.3.2=INIT-VALUE. You can use literal values.
There is also a special type of transition that can be run before the first test, as an initialization. This would have the test index set to 0. It would look like this:


Only literal values are supported for the "from" part, for obvious reasons (System variables could work, but this is not supported - yet).

Caution! If you are intending to use those transitions, you need to make sure the files you manipulate are writable during the execution of your tests! That could mean that those files have been checked out of ADE. If you end up with a message talking about FileNotFoundException and Read-Only File System, then you are probably in this case we are talking about.

There is a possibility to visualize the SOAP Traffic in a GUI.

Difference compared to previous revision
<span><font color="red"><b>Caution!</b></font> If you are intending to use those transitions, you need to make sure the files you manipulate are <u>writable</u> during the execution of your tests! That could mean that those files have been checked out of ADE. If you end up with a message talking about FileNotFoundException and Read-Only File System, then you are probably in this case we are talking about.<span style="text-decoration:underline;color:green"> There is a possibility to visualize the SOAP Traffic in a GUI. </span><span>
Please Confirm