Writing a New Test

This document describe how to write a new test, or start on a new test suite.

For this example, we will use Gearman, which is a framework for distributing and scheduling jobs.

Software Under Testing: Gearman

This example will be based on Gearman source code living in ~/devel/gearmand, and Gearman Java client living in ~/devel/gearmanij.

Downloading Gearman

You need Bazaar if you want to check out the source code of Gearman.

To install Bazaar on Ubuntu, you can run:

 $ sudo apt-get install bzr

When you have Bazaar installed, it is easy to check out Gearman:

 $ cd ~/devel 
 $ bzr branch lp:gearmand

Building Gearman

To build gearman, you need lots of tools, like automake, autoconf, libtoolize, autoheader, libevent, uuid, perl and a C++-compiler.

If you don't have these installed, you can do the following on Ubuntu:

 $ sudo apt-get install libtool autotools-dev automake g++ libevent-dev uuid uuid-dev

When these are installed, you can build Gearman like this:

 $ cd ~/devel/gearmand
 $ ./config/autorun.sh
 $ ./configure --prefix=`pwd`/install
 $ make
 $ make test
 $ make install

On OS-X I needed to:

 $ sudo ports install libedit
 $ ./configure --with-libevent-prefix=/opt/local --prefix=`pwd`/install

You should now be able to start gearmand by hand:

 $ ./gearmand/gearmand -V

Downloading Gearman Java Client

 $ bzr branch lp:gearman-java

Building Gearman Java Client

You might need the JUnit 4 test driver to build the tests of the Gearman Java Client, you can install it like this on Ubuntu:

 $ sudo apt-get install junit4

To build the Gearman Java Client, run Ant:

 $ cd gearman-java
 $ ant dist -Djunit.jar=/usr/share/java/junit4.jar

This should give this output:

 dist:
      [jar] Building jar: ~/devel/gearmanij/dist/lib/gearmanij.jar

The Gearman Java client must be installed in the maven repository, like this:

  mvn install:install-file -Dfile=~/devel/gearmanij/dist/lib/gearmanij.jar \
                           -DgroupId=org.gearman \
                           -DartifactId=gearman-java \
                           -Dversion=0.4 \
                           -Dpackaging=jar

Writing the Tests

For this test, we will write different reusable components, to showcase different features of the JET Framework.

We will write three tests, the first is an easy test that runs the Gearman unit tests, the second test uses the Gearman Java Client to test Gearman directly from Java. The third test will use the load framework to stress the Gearman server.

Running the Gearman Unit tests

This is an easy test that just wraps the Gearman unit tests. It lets us collect test run information from them for centralized reporting and running of tests on different platforms.

Test XML File

The test XML file that runs the unit tests is src/main/java/com/sun/jet/examples/gearman/test/gearmanUnitTests.xml. It uses GearmandServerSetup to start the server, and then UnitTestsTestCase to run the unit tests against Gearman.

Test Case

The UnitTestsTestCase runs the unit test executables that come bundled with Gearman, and parses their result. This is a simple example on how to run external test suites from JET when big parts of your test suite are written in JET and you just want to start other parts of it from JET to, e.g. to get result reporting combined.

Testing using the Java Client

Instead of running external programs to run the tests, you can write the tests in Java, and have JET run them.

Test XML File

The src/main/java/com/sun/jet/examples/gearman/test/gearmanJava.xml file contains a simple test of Gearman. It uses GearmanServerSetup so start Gearman, and then runs the EchoTestCase.testEcho().

Test SetUp

GearmanServerSetup starts gearmand in setUp(), and stops it in tearDown(). It uses JETPorts go get port numbers for gearmand and gearmand-http, the test cases will also use JETPorts to get the same port numbers later. GearmanServerSetup uses ExecuteClient to start gearmand on the host which should run the servers.

Test Case

The EchoTestCase is a simple test of the Gearman Java client library, which first adds a Gearman worker to the server and then gives this worker the jet-echo task, which simply returns the parameters which it has been given.

Running the Test

The make_ts_dir.sh script will make a test suite directory with all the executables you need. When you have run this script, you can run the run.sh script to run the test case.