= Using Boost.Test =

If you're developing with C++ [http://www.boost.org boost] is probably a familiar library. As it so happens, it's also a good match for being paired, quite easily, with bitten!

By roaming around the wiki (here: DataStorage) you can gather how bitten stores reports, and how ''test'' reports in particular are stored and used. For each test case a number of properties are stored, such as status and the fixture/test suite it belongs to.
This data is fed to bitten by the `<report>` recipe command (RecipeCommands). We just have to make sure it receives it in a format that it understands.

== Gathering the report ==

Fortunately for us, Boost.Test outputs test reports in XML format, if instructed to do so. Thus, the amount of work we have to carry out is reduced to specifying and applying a simple XSL transform!

But before we proceed to the needed transform we have to actually gather the XML data from boost. Suppose the program that runs your tests is called {{{run_tests}}}, then we can get an XML report by running that program as:

{{{
run_tests --report_format=xml --report_level=detailed
}}}

The detailed report level is needed for the XSL transform provided in the next section. Furthermore, you have to somehow store this in a file, ''test_results.xml'' below. There are several to do this, which I leave up to you to figure out (hint: redirect stderr/cerr or read the boost docs).

== Making it bitten-friendly ==

Now we need to apply the following transform on the report to make it understandable by bitten:

{{{
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml" indent="yes"/> 
 <xsl:template match="/">
    <unit_tests>
       <xsl:apply-templates/>
    </unit_tests>
 </xsl:template>
 <xsl:template match="TestSuite/TestCase">
     <test>
        <status>
	  <xsl:if test="@result = 'passed'">success</xsl:if>
	  <xsl:if test="@result != 'passed'">failure</xsl:if>
	</status>
        <fixture>
	  <xsl:value-of select="../@name" />
        </fixture>
        <type>test</type>
        <name>
	  <xsl:value-of select="@name" />
        </name>
     </test>
  </xsl:template>
</xsl:stylesheet>
}}}

Use the `<x:transform>` recipe command to do this. An example on how to use it is below. You will, of course, have to put this in your repository somewhere.

== Cooking up your build recipe ==

Here's a template for how to put all of this together in your build recipe:

{{{
<build xmlns:sh="http://bitten.cmlenz.net/tools/sh" xmlns:x="http://bitten.cmlenz.net/tools/xml">
  <step id="test" description="Test - run automated tests">
    <sh:exec executable="run_tests" output="test_results.xml" args="--log_level=nothing --report_format=xml --report_level=detailed" />
    <x:transform src="test_results.xml" dest="test_report.xml" stylesheet="test_results.xslt" />
    <report category="test" file="test_report.xml"/>
  </step>
</build>
}}}

Using this approach (using `<sh:exec>` to redirect the output to a file) your test log won't be very nice looking. You probably want to tweak this teample to generate the XML data by other means and instruct it to ouput nice log-message.