Compass Version 1.3

Adding Unit Test Parsers

In Compass, Unit Test Parsers are a special type of script that are run after a build step completes it's execution of a regular Compass script. The Unit Test Parser then parses the output and returns the number of unit tests run and the number that have failed. This subsection describes how to create your own unit test parser.

The Python Unit Test Parser File

To create your own Unit Test Parser we first need to write a parser script. A Compass Unit Test Parser is a python script that contains a function definition with the following signature:

def parseUnitTestOutput( output, resultCode, argument)

The function takes as input three parameters:

output - The Output parameter is the output from the build step that this unit test parser is attached to.
resultCode - The resultCode is the integer code value for the result of the script that the unit test parser is attached to.
argument - The argument parameter is the arguments that are provided in the Build Editor when setting up the parser for a build step.

The function should return a list with 2 values. Index 0 should contain an integer for the total number of tests run. Index 1 should contain an integer for the total number of tests that failed.

Compass provides the helper module: master.helpers.regexpunittest Importing this module in your script file will give you access to the function master.helpers.regexpunittest.parseUnitTestOutput.

This function takes two parameters. Output, which is the same output parameter defined above, and argument which is a regular expression containing the groups 'run' and 'failed'. The function will scan the output and take all matches to the regular expression, convert the groups 'run' and 'failed' to integers, sum them, and output them as a tuple (ie: [totalRun, totalFailed]). The function will return None in the case of any exceptions. As an example of how to use this functionality we have included the JUnit test parser that is included in the Compass distribution here:

import master.helpers.regexpunittest as regexpunittest

def parseUnitTestOutput( output, resultCode, argument ):
return regexpunittest.parseUnitTestOutput( output, "Tests run:\s*(?P<run>[0-9]+),\s*Failures:\s*(?P<failed>[0-9]+)" )

As you can see, the regular expression matches values for the groups <run> and <failed>. It is always a good idea to have some example output files for the unit test library you are using and then test the regular expression using your example output to make sure it works as expected. Once you are satisfied that your parser functions as expected then we create the Compass unit test parser in Compass and upload our script.

Adding the Python Unit Test parser script to Compass

Now that we have a working script, let's creat the Compass Unit Test Script on the Script List page. Click on the 'Create New Unit Test Parser' button and the following dialog will appear:

The 'New Unit Test Parser' dialog has 3 parameters to fill out. A Name must be given to the unit test parser to identify it throughout Compass. The second parameter is the script file, which we just created and can now upload. And finally, the Script Keywords to identify this unit test parser with. Once all three of these things are specified, click the 'Create' button and the new Unit Test Parser will be added to the script list and can be viewed and updated on the Script List page.