The JUnit Sensor is an Ant task that sends the results of unit testing using JUnit to the Hackystat server. The JUnit sensor represents this metric data using the UnitTest sensor data type, documented in Section 25.16, “UnitTest”
JUnit is a framework for simplifying the construction and invocation of unit tests in Java. Ant includes a JUnit target that simplifies the invocation of JUnit tests during the build of a system. The Ant task for JUnit includes an option that allows data regarding the results of the unit tests to be stored into a file in XML format. The Hackystat JUnit sensor is an Ant task that reads in the XML file produced by the JUnit Ant task and sends the results to Hackystat. The data includes the elapsed time required for the test, the Java class associated with the test, the method that was invoked to run the test, and the JUnit error or failure string (if present). If the test succeeded, then no error or failure string is sent.
The JUnit sensor requires Java 1.5.0 or later, Ant 1.6.5 or later, and JUnit 3.7 or later.
Download and install JUnit from its home page. Section 4.7, “Measurement: Unit testing results with JUnit” provides a recommended approach to JUnit installation for use with Hackystat.
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 JUnit sensor and press "Configure Selected Sensor". Figure 26.37, “ JUnit sensor installer configuration window ” shows what the configuration window should look like after the path to Ant 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 JUnit 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.
Ant home directory: This path specifies the top-level directory for Ant. The JUnit sensor requires the placement of a sensor executable into Ant's lib/ directory.
Define a target in your build.xml file to invoke JUnit and write out its results in XML format. To do this, use the formatter="xml" option in the JUnit task. The target should then invoke the JUnit sensor to send the results to Hackystat. Example 26.52, “An example JUnit target” illustrates one possible definition of such a target.
Example 26.52. An example JUnit target
<target name="junit" depends="compile"
description="Run JUnit tests (all classes whose name starts with Test) and generate a report.">
<taskdef name="junitreport" classname="org.apache.tools.ant.taskdefs.optional.junit.XMLResultAggregator"/>
<property name="test.dir" location="${build.dir}/junit"/>
<mkdir dir="${test.dir}"/>
<!-- Run the tests, which are all classes whose name starts with 'Test'. -->
<junit printsummary="withOutAndErr" fork="yes"> 
<classpath path="${java.class.path};${build.dir}/classes" />
<formatter type="xml" /> 
<batchtest todir="${test.dir}">
<fileset dir="${src.dir}">
<include name="**/Test*.java" />
</fileset>
</batchtest>
</junit>
<!-- Generate an HTML report on the results and tell the user. -->
<junitreport todir="${test.dir}"> 
<fileset dir="${test.dir}">
<include name="TEST-*.xml"/>
</fileset>
<report format="frames" todir="${test.dir}" />
</junitreport>
<!-- Send the results to Hackystat -->
<taskdef name="hacky-junit" classname="org.hackystat.sensor.junit.JUnitSensor" />
<hacky-junit verbose="on" sourcePath="${src.dir}"> 
<fileset dir="${test.dir}"> 
<include name="TEST-*.xml"/>
</fileset>
</hacky-junit>
</target>
Please note the following regarding Example 26.52, “An example JUnit target”:
| | Before running the JUnit sensor, we need to first invoke JUnit to generate test case results. |
| | The formatter="xml" attribute is required, since the JUnit sensor needs to read the JUnit results in XML format. |
| | Running the junitreport target is not required, but is helpful for obtaining the JUnit results in easily readable HTML format. |
| | The "verbose" attribute provides a trace of the execution of the JUnit sensor. Leave it on initially to help verify the installation. |
| | The "sourcePath" attribute specifies the directory where the files containing the source code for the JUnit tests are located. |
| | The fileset target enables you to tell the sensor where to look for the XML files generated by JUnit. |
To verify your JUnit sensor installation, invoke the target and check to see that data is sent to the server. Example 26.53, “Example JUnit output” shows the shell output from an example run with verbose= "on".
Example 26.53. Example JUnit output
C:\cvs413\Stack>ant junit
Buildfile: build.xml
init:
checkstyle:
compile:
junit:
[junit] Running edu.hawaii.stack.TestClearStack
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.234 sec
[junit] Running edu.hawaii.stack.TestStack
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.235 sec
[junitreport] Transform time: 547ms
[echo] JUnit results in C:\cvs413\Stack\build\junit/index.html
[hacky-junit] Sensor enabled?: true
[hacky-junit] Processing file: C:\cvs413\Stack\build\junit\TEST-edu.hawaii.stack.TestClearStack.xml
[hacky-junit] Processing file: C:\cvs413\Stack\build\junit\TEST-edu.hawaii.stack.TestStack.xml
[hacky-junit] Hackystat data on 3 JUnit tests sent to http://hackystat.ics.hawaii.edu/ (0 secs.)
BUILD SUCCESSFUL
Total time: 4 seconds
The JUnit sensor will output a different message if the data was not sent successfully. The data was sent in less than a second, hence the "0 secs." output value.
Once you verify that JUnit 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 FileMetric data for today's date was received by the server for the JUnit tool, as illustrated in Figure 26.38, “ List Sensor Data with JUnit data ”.
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 JUnit sensor writes out a file called junit.0.log to the .hackystat/logs directory that can be useful in debugging your installation. Under normal conditions, this file should look similar to Example 26.54, “Log file for JUnit sensor”.
Example 26.54. Log file for JUnit sensor
Hackystat Version: 6.3.1119 (November 19 2004 15:22:57)
SensorShell started at: 11/29/2004 12:10:51
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Activity
Defined shell command: Coverage
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Perf
Defined shell command: Build
Defined shell command: FileMetric
#> AutoSend [10]
AutoSend OK (set to 10 minutes)
AutoSend enabled every 10 minutes.
Checking for offline data to recover.
No offline data found.
#> UnitTest [setTool, JUnit]
setTool OK
#> UnitTest [add, edu.hawaii.stack.TestClearStack, testNormalOperation, 16]
UnitTest add OK (1 total)
#> UnitTest [add, edu.hawaii.stack.TestStack, testNormalOperation, 0]
UnitTest add OK (2 total)
#> UnitTest [add, edu.hawaii.stack.TestStack, testIllegalPop, 0]
UnitTest add OK (3 total)
#> send
Sending sensor data (11/29 12:10:52)
Activity: Send OK (No entries to send.)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
Coverage: Send OK (No entries to send.)
AutoSend: AutoSend OK ('send' command ignored)
BuffTrans: Send OK (No entries to send.)
UnitTest: Send OK (3 entries)
Build: Send OK (No entries to send.)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (No entries to send.)
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 junit.0.log file.
A description of the problem you are having.
To disable JUnit data collection temporarily, invoke HackyInstaller, bring up the JUnit configuration window, and uncheck the "Enable JUnit sensor" property, and apply the setting. To permanently uninstall the JUnit sensor, press the "Uninstall" button and remove the Build targets from your Ant build.xml files.