Blog- Main Page - Books - Links - Resources - About - Contact Me

Read Jared's best selling book, Ship It! A Practical Guide to Successful Software Projects at PragmaticProgrammers.com

So what should a JUnit test look like and how do I start using it?

by Jared Richardson
http://www.jaredrichardson.net


Goals:

This is an extremely brief  tutorial on JUnit. The goal is to introduce a new user to basics the JUnit framework.

Prerequisites:

In order to use this tutorial you will need to have a Java compiler (http://java.sun.com/), Ant (http://ant.apache.org/), and JUnit (http://junit.org/) installed.
You will also need JUnit.jar in your Ant's library folder (ANT_HOME/lib).

I've also included a link to the code and Ant scripts needed to run this example.

Let's Test Some Code

First, you need a Java class to test. :) Here's a short example.

public class Math {
        static public int add(int a, int b) {  
                return a + b;
        }
}


My apologies for the lack of JavaDocs and comments, but it's a pretty simple bit of code. This class will add two numbers.  

To test this code, you need a second Java class that will

    1) import junit.framework.*
    2) extend TestCase.

That's it!

Here's an example.

import junit.framework.*;

public class TestMath extends TestCase {

  public void testAdd() {
        int num1 = 3;
        int num2 = 2;
        int total = 5;
        int sum = 0;
        sum = Math.add(num1, num2);
        assertEquals(sum, total);
  }
} 


There are two important points to note in the sample. First, the routine is named testAddNumbers. This convention tells you that the routine is supposed to be a test and that it's targetting the "add" functionality.

The last step is how to run your JUnit tests. You can do this several ways, including your command line, Eclipse or the JUnit Test Runner, but I like plain Ant. To run a Junit test with an Ant script, add this to your Ant script:

<junit printsummary="yes" haltonfailure="yes" showoutput="yes" >
        <classpath>
                <pathelement path="${build}"/>
        </classpath>                   

        <batchtest fork="yes" todir="${reports}/raw/">
                <formatter type="xml"/>
                <fileset dir="${src}">
                        <include name="**/*Test*.java"/>
                </fileset>
        </batchtest>
</junit> 
     

Ant will also do nice things like create nice HTML reports for you! I've linked to a simple Ant script that will compile all the code in your "src" folder, run all the tests named "test*" and then create an HTML report in your "reports\html" folder. Just type "ant test".

I've linked to a zip file (junit-sample.zip) that contains the build.xml file, the source code and the test class. (If you try to run it and get errors about JUnit not being found, remember to add that junit.jar to your Ant lib folder.)

Summary

That's it! This should be all you need to understand the basics of Junit.

It a lightweight enough framework that this short introduction should let you do quite a bit. By taking this example you can create a number of basic, automated tests that can be run from your IDE or in a build verification system.

For more information, see the JUnit articles page or pick up a copy of Pragmatic Unit Testing in Java.