Setting up TUnit

Minimum Requirements

The minimum requirements are:

• Install the latest tinyos-2.x, or get it from the repository.
• Check out a copy of the latest tinyos-2.x-contrib repository (instructions here).
• Ant is completely optional, but may be used to generate nicer looking HTML reports.

Simplistic TinyOS Directory Structure

Your projects and directories may differ. On the automated unit testing server, the tinyos-2.x and tinyos-2.x-contrib directories are located in a simplistic structure:

 opt
 |-- tinyos-2.x
 |-- tinyos-2.x-contrib

Complex TinyOS Directory Structure

In my own private projects, I prefer a more complex structure:

 opt
 |-- myProject
 |   |-- tinyos-2.x    <-- A snapshot of TinyOS my project is compatible with
 |   |-- tests
 |   |   |-- ... bunch of sub-test directories...
 |   |-- tinyos-2.x-myProject    <-- Project's files that override the TinyOS baseline
 |   
 |-- tinyos-2.x-contrib

For the remainder of this setup guide, I will assume your TinyOS is setup in the simplistic structure, with directories located at /opt/tinyos-2.x and /opt/tinyos-2.x-contrib.

Environment Variables

TOSCONTRIB

TUnit needs to know where the tinyos-2.x-contrib is located so it may find the tinyos-2.x-contrib/tunit directory. Because TUnit is driven by a Java application, the TOSCONTRIB path must be absolute so Java can find it.

 Linux
   export TOSCONTRIB=/opt/tinyos-2.x-contrib

 Windows/Cygwin
   export TOSCONTRIB="`cygpath -w /opt/tinyos-2.x-contrib`"

CLASSPATH

Your classpath must be updated to include tunit.jar and all of its dependencies.

 Linux
   export LOG4J=$TOSCONTRIB/tunit/support/sdk/tunit/depends/log4j.jar
   export TUNIT=$TOSCONTRIB/tunit/support/sdk/tunit/tunit.jar
   export XERCES=$TOSCONTRIB/tunit/support/sdk/tunit/depends/xerces.jar
   export JFREECHART=$TOSCONTRIB/tunit/support/sdk/tunit/depends/jfreechart-1.0.5.jar
   export JCOMMON=$TOSCONTRIB/tunit/support/sdk/tunit/depends/jcommon-1.0.9.jar
 
   export CLASSPATH="${CLASSPATH}:${LOG4J}:${TUNIT}:${XERCES}:${JFREECHART}:${JCOMMON}:."

 Windows/Cygwin
   export LOG4J="`cygpath -w $TOSCONTRIB/tunit/support/sdk/tunit/depends/log4j.jar`"
   export TUNIT="`cygpath -w $TOSCONTRIB/tunit/support/sdk/tunit/tunit.jar`"
   export XERCES="`cygpath -w $TOSCONTRIB/tunit/support/sdk/tunit/depends/xerces.jar`"
   export JFREECHART="`cygpath -w $TOSCONTRIB/tunit/support/sdk/tunit/depends/jfreechart-1.0.5.jar`"
   export JCOMMON="`cygpath -w $TOSCONTRIB/tunit/support/sdk/tunit/depends/jcommon-1.0.9.jar`"
 
   export CLASSPATH="${CLASSPATH};${LOG4J};${TUNIT};${XERCES};${JFREECHART};${JCOMMON};."

First Run

After setting up the TOSCONTRIB and CLASSPATH environment variables, you should able to execute the TUnit Java application. The initial errors are ok, we'll fix those next. I'm running TUnit from cygwin, hence the windows paths indicated below.

 $ java com.rincon.tunit.TUnit
 0 [main] INFO com.rincon.tunit.TUnit  - Base package directory located: C:\
 0 [main] INFO com.rincon.tunit.TUnit  - Found a TOSCONTRIB environment variable
 0 [main] DEBUG com.rincon.tunit.TUnit  - Found TUnit! C:\tinyos\cygwin\opt_svn\tinyos-2.x-contrib\tunit
 Running TUnit from C:\cygwin\opt\tinyos-2.x-contrib\tunit
 0 [main] FATAL com.rincon.tunit.TUnit  - Cannot locate C:\tinyos\cygwin\opt_svn\tinyos-2.x-contrib\tunit\tunit.xml
 0 [main] FATAL com.rincon.tunit.TUnit  - Does tinyos-2.x-contrib/tunit/tunit.xml exist?

XML Files

tunit.xml

TUnit requires the tunit.xml file to tell it what hardware you have connected to the computer and how to talk to it. There is an example tunit.xml file located at tinyos-2.x-contrib/tunit/tunit_example.xml, which you can use to start creating your own tunit.xml file:

 <tunit>
 
   <testrun name="1_telosb">
     <mote target="telosb" motecom="serial@COM18:tmote" installextras="bsl,17"/>
   </testrun> 
    
   <testrun name="2_telosb">
     <mote target="telosb" motecom="serial@COM22:tmote" installextras="bsl,21"/>
     <mote target="telosb" motecom="serial@COM18:tmote" installextras="bsl,17"/>
   </testrun>
 
 </tunit>

You need to create a tunit.xml file in the tinyos-2.x-contrib/tunit directory, and list the types of hardware you have connected to your computer. If you change that hardware, you must manually update the tunit.xml file.

build.xml

This file is not required to run TUnit. It is optional in the case that you want to use Ant to run TUnit. There is an example build.xml file located at tinyos-2.x-contrib/tunit/build_example.xml

When running TUnit standalone on your own computer, the build.xml file is mostly responsible for creating TUnit HTML reports. The build.xml file is also used for automated unit testing, which can be configured to check out the latest TinyOS CVS repositories, run tests, and generate reports.

Read the Ant documentation to find out more about the build.xml file.

You can use CruiseControl or a custom infinite-loop bash script to run the build.xml file in an automated unit testing fashion.

lava.xml

You can safely ignore and not create the lava.xml file, unless you really want to get lava lamps displaying the results of your automated unit testing system.

Verifying the Setup

To verify everything is setup correctly, create an empty directory and run TUnit. If everything is working, you'll see TUnit results displayed at the end.

 $ mkdir emptydir
 $ cd emptydir
 $ java com.rincon.tunit.TUnit
 
  ... [ lots of command-line output ] ...
 
 T-Unit Results
 -----------------------------------------------
 Total runtime: 4.448 [s]
 Total tests recorded: 0
 Total errors: 0
 Total failures: 0

Execute a test

There are lots of simple tests to try in the tinyos-2.x-contrib/tunit/tests directory. Assuming you have a test run containing a single node, I recommend trying the following:

 $ cd /opt/tinyos-2.x-contrib/tunit/tests/tinyos-2.x/tos/lib/tunit/TestAssertions
 $ java com.rincon.tunit.TUnit
 
   ... [ lots of command-line output ] ...
 
 T-Unit Results
 -----------------------------------------------
 Total runtime: 41.891 [s]
 Total tests recorded: 14
 Total errors: 0
 Total failures: 0