Concepts

Unit testing of TIB enabled components is a very important feature on a daily basis for anyone working with TIB/Integration Manager, TIB/Message Broker, and so forth. So we decided we'll finally put onto Sourceforge what we've been using to test our own work.

In a general fashion, what Raccoon provides is an application that sends messages to a specific subscriber (TIB/IM in the picture) and checks for each message sent that this application generates the right message. If this isn't the case, the test fails.

The Raccoon Framework is also capable of testing other TIB enabled components such as the TIB/Adapter for File, the main reason for this is that integration testing is also an important factor for a project.

Therefore the Raccoon Framework has to offer the capability to test a complete chain.

UiTest

An UiTest is the smallest test structure available and is composed of:

• A single message to publish. This message is defined in an XML file that Raccoon takes and converts into a TIB/Rendezvous message. The supported messages types are the plain Rv and extended version AE.
• A set of messages to be received, also referred to as the expected messages list. It is therefore possible to define for a single published message, a group of messages that the application (TIB/IM for example) is supposed to publish.
  
  Note: An expected message is unique per subject, therefore if the set of expected messages contains two messages, than those two messages have to be expected on two different subjects.
  
  However Raccoon will persist all messages received, but the success or failure of a test will be based on the first message received for each subject.
• A TimeOut value, in seconds, indicating how long Raccoon is to wait to receive all expected messages. Of course, if all the messages are received before the timeout value than Raccoon goes on to the next UiTest.
• Once the test is executed, within the contexte of a UiCase, a set of received messages. These messages are persisted in a specific directory so that the operator may view at his leisure the messages received.
• A list of errors, if any, that occured. An error is a single message indicating the reason of the failure of the test. An error can be, for example, a received message that differs from the expected message. This list of errors is very precis in the sense that it will indicate the invalid field, object type so that the user can locate the error quickly.
• Once the UiTest is executed it will also contain the execution time as an indication: i.e. not to be used for performance mesuring, although the execution time is exact.

UiCase

An UiCase is in fact a test case scenario containing several UiTests. A test case scenario main objectif is to test a specific workflow within TIB/IM, TIB/MB, ... with messages that differ in content but not from a functional standpoint.

Putting it otherwise, an UiCase contains:

• A unique Publisher that sends messages on one or more subjects, although it isn't recommended to put into a UiCase a publisher that sends messages on different subjects. We would recommend creating two UiCases.
• A unique Subscriber that has several listeners on various subjects. A unique Subscriber means a unique set for the UDP Port, NIC, Daemon port.
• A set of UiTests and their corresponding messages. The UiCase will contain the result of run of all the UiTests.

Suggested conventions - Guidelines

Within the contexte of TIB/Integration Manager, a UiCase tests a single Process diagram. Each UiTest corresponds to the messages that a Process diagram may receive.

However a UiCase is slightly more than a Process diagram because the Publisher of the UiCase corresponds to the initiating channel of the job creator that invokes the Process diagram.

Unit

A Unit is a set of UiCases for a given functional domain. The results of the test are put into an xml file that is converted in an HTML file using the "site:doc" target of Maven. An example of such a report can be seen here.

Example

In our case we use Raccoon as follows, any ideas are welcome :o)

For example, we use Raccoon to test the SWIFT Parser from TIBCO and our workflows related to the interpretation of SWIFT Messages.

What we have is this:

• Unit: name is SWIFT_In and contains the elements provided hereafter.
• UiCase: each case is related to a specific swift type, say MT541. This case contains several MT541 with different values/sequences or the tanker provided by SWIFT.
• UiTest: Each test contains a specific MT, which is defined by the UiCase it belongs to, each UiTest contains a single SWIFT message and differs from the UiTest of the same UiCase by the values it bears.
  
  A specific MT will generate several messages, depending on the values and we check that we get those values.
  
  We also do negative testing by injecting incorrect SWIFT messages and check that we get the errors.

The classpath

The following elements have to be added to the classpath (already done in the file run_uitools.bat):

• castor-0.9.3.19-xml.jar: Castor XML tool
• log4j-1.1.3.jar: Log4j tool
• raccoon-0.5.2.jar: the Raccoon library
• tibrvj.jar: The TIB/Rendezvous library
• xerces-1.2.3.jar: The xerces parser, used by the Castor XML library and Raccoon
• commons-collections-2.1.0.jar: The commons collections jakarta library
• conf: the configuration directory that contains the configuration files.

• raccoon.properties: the properties file for Raccoon. By default this contains:
  
  raccoon.service.manager.mapping = data.services.xml

raccoon.service.manager.service = uitester.xml
  
  You should never really change the first line, unless you really know how to handle Raccoon :o)
  
  However the second line points to the configuration file that the Service Manager is supposed to use. A sample file is provided in the folder /uitest/conf under the name uitester.xml You can use this file and customize if you wish or create a new one.

Configuring the endpoints

An endpoint can either be a publisher or a subscriber, both types of endpoints depend on a Session element. A Session element is mainly defined by a SessionConfig component, so the first thing to do is to define this component.

A sample SessionConfig component is provided in the file uitester.xml, it's name is iuSessionConfig and connects to the TIB/Rendezvous daemon using the default parameters (tcp:7500, 7500, default_NIC).

Additional configuration information is given for this component in the file uitester.xml in comments.

Configuring any endpoint consists in defining the component RvSession. All this component really needs is a SessionConfig element. The sample RvSession component provided is named iuRvSessionTest

The configuration file has only a single endpoint configuration, which means that the messages will be sent and received via the same daemon and the same UDP port.

Setting up the recorder

A sample recorder component is provided and is named UnitRecorder. This recorder will use the following elements:

• iuRvSessionTest assigned to the property tibSession. This defines the TIB/Rendezvous session on which the recorder will listen to. It is possible to define multiple TIB/Rendezvous sessions by putting assigning multiple values to the same property tibSession like this:
  
  

                  <depends name="iuRvSessionTest_1" property="tibSession" type="collection"/>
  
  
                  <depends name="iuRvSessionTest_2" property="tibSession" type="collection"/>
  
  
                  <depends name="iuRvSessionTest_3" property="tibSession" type="collection"/>
  
  
                  <depends name="iuRvSessionTest_4" property="tibSession" type="collection"/>
  
  
                

  The recorder will then record messages on all theses TIB/Rendezvous sessions for all the subjects defined hereafter.
• tibSubject is the subject on which the listeners will subscribe to. For example:
  
  

                <defaultValue name="tibSubject" type="string" value="SwiftMessage.in" colType="collection"/>
  
  
                <defaultValue name="tibSubject" type="string" value="MInstance.in" colType="collection"/>
  
  
                <defaultValue name="tibSubject" type="string" value="Swift.out" colType="collection"/>
  
  
                

  Will induce persistence of all messages on the subjects SwiftMessage.in, MInstance.in, Swift.out for all the TIB/Rendezvous subjects defined previously.
• msgDir: the directory where the recorded messages will be persisted, can be relative or absolute. If the destination directory doesn't exist it will be created, if possible. If possible means that it will be created only if the last folder doesn't exist, it won't create recursively N folders.
• stopSubject: the TIB/Rendezvous subject that will stop the recorder.

Using the recorder

Using the recorder is very simple:

1. Open two dos windows
2. Execute the following command: run_uitools.bat -record UnitRecorder. Once you get the string "Raccoon Recorder is ready to record messages." it means that the recorder is ready.
3. Publish all your messages.
4. Stop the recorder by executing in the second dos prompt: tibrvsend raccoon.recorder.stop ""
   
   You should then get in the first window: Raccoon Recorder has stopped recording messages.

Setting up the tests

This component requires a publisher and subscriber. The publisher will send all the necessary messages and the subscriber will receive all the expected messages (hopefully). In the case of the sample configuration file both elements point to the same RvSession component named iuRvSessionTest

Furthermore you have to define the file that contains the actual configuration information, defined by the property testConfigFile. The sample file provided is named test.xml and the contents are explained in the sample file.

The next element to provide is the radix of the files that will be created. It is important to bear in mind that the Raccoon UITester persists all messages received for operator comparaison to what was expected. These files will be stored in a special folder and the first characters of the files will be the value of fileRadix

Running the tests

You can run the tests by executing the following command: run_uitools.bat -unit UnitTest_1 raccoon_unit.xml

Once the tests are succesfully executed the tool generates a report file under the name raccoon_unit.xml. This file can then be converted into an HTML file using the maven:docs target or any equivalent XML Stylesheet program (Anakia for example).

Don't forget if you're using maven to generate the documentation to copy the directory msgRef and msg folder to the same level as the generated HTML file!