The CPPUnit Sensor is a command line tool that sends unit test data produced using CPPUnit to the Hackystat server. The CPPUnit sensor represents this metric data using the UnitTest sensor data type, documented in Section 25.16, “UnitTest”.
CPPUnit is a framework for simplifying the construction and invocation of unit tests in C++. CppUnit provides an outputter for producing XML output that includes: the name of the C++ class implementing the unit test; the test method name; the test result (Pass, Fail, Error); and a error message if one occurred.
![[Note]](gfx/admonitions/note.gif) | Note |
|---|---|
Unlike other unit test sensors, the CppUnit sensor does not support metrics for elapsed time of each unit test. This is because the default XML outputter provided by CppUnit does not include timing information. In addition, the generic timing classes provided by the C++ standard library are accurate to seconds, not milliseconds, which is the grain size required by many unit tests. | |
The CPPUnit sensor requires Java 1.5.0 or later and CPPUnit 1.10.
Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.
In the HackyInstaller main window, select the CppUnit sensor and press "Configure Selected Sensor". Figure 26.13, “ CppUnit sensor installer configuration window ” shows what the configuration window should look like after the path to the CppUnit sensor directory is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable CppUnit Sensor: This property controls whether the sensor is active or not. If not checked, the sensor will not collect or send data even if installed.
CppUnit Sensor home directory: This path specifies a directory when the CppUnit sensor files will be located. This can be any directory.
Once you have created unit tests for your C++ project, you must configure the CppUnit test runner to output XML instead of on-screen text (which is the default). To accomplish this, you need to specify an XML output format in the main method of your test runner. Example 26.21, “Code for CPPUnit XML output” illustrates the code for specifying XML output.
Example 26.21. Code for CPPUnit XML output
#include <cppunit/TestCase.h>
#include <cppunit/XmlOutputter.h>
#include <cppunit/extensions/TestFactoryRegistry.h>
#include <cppunit/ui/text/TestRunner.h>
int main (int argc, char* argv[]) {
// Define the file that will store the XML output.
ofstream outputFile("outputFile.xml");
// Create a test runner to execute the test cases you have defined (in other source code).
CppUnit::TextUi::TestRunner runner;
// Specify XML output and inform the test runner of this format.
CppUnit::XmlOutputter* outputter =
new CppUnit::XmlOutputter(&runner.result(), outputFile);
runner.setOutputter(outputter);
// Add the test cases you defined previously in a test suite to the runner and execute them.
runner.addTest(CppUnit::TestFactoryRegistry::getRegistry().makeTest());
runner.run();
outputFile.close();
}
The simplest way to perform this task is by running the sensor directly from the command line. Assuming that the output.xml file, sensorshell.jar, and sensor.cppunit.jar files are all in the same directory, you can invoke the CPPUnit sensor as follows.
Under Unix/Linux environments, use the following command:
java -cp sensorshell.jar:sensor.cppunit.jar org.hackystat.sensor.cli.cppunit.CppUnitSensor -xmlFile outputFile.xml -verbose
Under Windows environments, use the following command:
java -cp "sensorshell.jar;sensor.cppunit.jar" org.hackystat.sensor.cli.cppunit.CppUnitSensor -xmlFile outputFile.xml -verbose
To verify your CPPUnit sensor installation, invoke the sensor with the "-verbose" parameter as illustrated above and check to the output. Example 26.22, “Example CPPUnit output” shows output from a successful invocation of the sensor.
Example 26.22. Example CPPUnit output
/home/testuser/.hackystat/cppunit>java -cp sensorshell.jar:sensor.cppunit.jar org.hackystat.stdext.sensor.cli.cppunit.CppUnitSensor -xmlFile /home/testuser/code/project/outputFile.xml -verbose Hackystat data on 1 CppUnit file sent to http://hackystat.ics.hawaii.edu/ /home/testuser/.hackystat/cppunit>
Once you verify that CPPUnit data is being sent from the client using verbose mode, login to your account on your Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that UnitTest data for today's date was received by the server for the CPPUnit tool.
The first step in troubleshooting your sensor installation is to verify that your Hackystat host and key settings are valid and that you can contact the Hackystat server, as described in Section 2.4, “HackyInstaller GUI: Setting and verifying the Hackystat host and user key”
The CPPUnit sensor writes out a file called cppunit.0.log to the .hackystat/logs directory that can be useful in debugging your installation.
If none of the above troubleshooting activities solves your problem, then you should send an email to your Hackystat Administrator to request help. Please include in your email the following information:
The output from 'java -version'.
The output from 'java -jar sensorshell.jar -verify'.
The contents of your sensor.properties file.
The contents of the cppunit.0.log file.
A description of the problem you are having.
To minimize output, you can stop using the "-verbose" parameter once things are working correctly.
Although manual invocation of the CPPUnit sensor is appropriate for initial installation and testing, it is time-consuming on a daily basis. A better approach is to automate the invocation of your unit tests using Make and automatically run the CPPUnit sensor after every invocation of the unit tests. This provides a historical record of the testing evolution that can be later used by Hackystat analyses.