XmlMessageTest 1.1

XmlMessageTest is a fully declarative unit testing framework for XML-based message servers. It allows developers or testers to create tests by specifying XML messages to send to the server and expected results, without the need to develop additional code. These tests can be integrated into a build process and run without user interaction.

Developed by Gene Mitelman (gene@smartedgellc.com).
Web site: www.smartedgellc.com.

Installation:

1. Ensure you have JDK 1.4 or above installed (by running "java -version")
2. Make sure java executable is in the path
3. Unzip xmlmessagetest.zip (or xmlmessagetest.tgz) file into a separate directory
4. Switch to the directory where you unzipped the contents of the archive
5. Run sample tests:
java -jar xmlmessagetest.jar http://www.smartedgellc.com/xmlmessagetest/xmlmessage tests
6. Assuming you can access http://www.smartedgellc.com, you should see test results

Writing Tests:

As mentioned above, tests are written by simply stating messages to send and to expect back, without writing code.
You should put all your test files in a separate directory, ending each file with ".test" extension.
Multipe tests can exist in a single file. You should create separate files for logical test suites for manageability, though.
The format of a test file is:



Any comments... (no special characters are needed to start the lines)



#MESSAGEIN: Add two numbers

<Add>
   
<param1>5</param1>
   
<param2>10</param2>

</Add>



#MESSAGEOUT

<Result>
   
	<value>15</value>

</Result>

Requests to be sent to the server must start with #MESSAGEIN on a line above the actual XML message to be sent. It should be followed with ":" and a description of the request, so that you can quickly zero in on failed tests.
The message to be sent must be on the next line. Any parameters returned by prior responses, can be used in follow up requests by enclosing that parameter name in <%= and %>. The name of the parameter must reflect the whole hierarchy. For example, if a prior response returned a parameter named <sessionid> as part of <Session> message, it can be sent in a follow up request as <%=Session.sessionid%> instead of a hard-coded value.
Request must be followed by a blank line.

Expected responses must start with #MESSAGEOUT on a line above the actual XML message expected back.
The expected response must be on the next line. For simplicity, you do not need to list the whole expected response, just the parameters you'd like to test. For example, if the response will include ten parameters, but you only care about "sessionid", you only list "sessionid" in the message. To test for specific value, you can either include the actual value, such as <sessionid>1000</sessionid> or a parameter from prior response, such as <sessionid><%=Session.sessionid%></sessionid>, or a combination thereof.
Expected values must be expressed as regular expressions. Some examples:

	`Test`	will match the word "Test"
	`30`	will match number "30"
	`Echo <%=value%>`	will match "Echo " followed by value parameter from a prior response
	`Test\.`	will match the sentence "Test." (notice the period)
	`Test.*`	will match any value starting with "Test"
	`.*Test`	will match any value ending with "Test"
	`.test.`	will match any value containing "test"
	`.*`	will match any value
	`\d`	will match a single digit
	`\d*`	will match any number of digits
	`[a-zA-Z]`	will match a single letter
	`[a-zA-Z]*`	will match a single word

There are plenty of resources on the Internet, describing the use of regular expressions.
If more tests are included in the test file, response must be followed by a blank line.

Please refer to sample tests in the "tests" directory for actual working examples with attributes, hierarchical messages, etc.

Running:

Execute xmlmessagetest.jar, passing in URL of the xml server to test and the directory where ".test" files are located:
java -jar xmlmessagetest.jar "url-to-run-against" "test-directory"

To run automatically, include the run command in your build process, redirecting output to a file:
java -jar xmlmessagetest.jar "url-to-run-against" "test-directory" > "output-file"

Limitations in this version

1. This version cannot reliably test responses where multiple elements with the same name are returned.
An example of such a response would be:


	<Values>
   
	<value>2</value>
   
	<value>3</value>

	</Value>

2. When attempting to test very complex responses, you may want to intentionaly set up a test to fail, in order to verify that the framework tests such responses reliably. If you encounter problems with complex responses, please contact me.

Enhancements/Bugs

If you would like to request enchancements/bug fixes or find documentation errors, please contact me at gene@smartedgellc.com. Based on feedback and time constraints, I will try my best to accomodate your needs.
If you make any improvements or bug fixes, please send me the code, if possible.