Section 13.4. Installing and Running JUnit

13.4. Installing and Running JUnit

It's rather simple to install a standalone version of JUnit. We download a ZIP file from the JUnit Web site, then unzip it into a directory. Adding the JUnit JAR file to your CLASSPATH is all that's needed to make JUnit available for you to run it.

Example 13.1. The bare bones of our Account class

 package net.multitool.core; import net.multitool.util.*; import java.util.*; /**  * The basic Account class for our budgeting example; this is the  * first-cut "implementation" where we have just transferred our  * design into Java code. We can use this much to generate Javadocs  * and also to begin our JUnit testing (design, test, code).  */ public class Account {    private String name;       // a name to identify this account    private User owner;        // the user assigned to this account    private SAMoney total;     // total amt allocated to this account    private HashMap children;  // the collection of subaccounts,                               //   by name    private Account parent;    // it has this account as a child    /**     * Create an account, with a pool of dollars to budget.     * Use this constructor to create the master account.     * Use "createSub" to create children of this account.     */    public    Account(String name, User owner, String total)    {    }    /**     * Create a new subaccount (i.e., child), given a name     * and an amount. The child is connected to the parent.     */    public Account    createSub(String name, String amt)    {       return null;        // so it compiles    } // createChild } // class Account 

13.4.1. Downloading and Unzipping

Point your browser at the site http://www.junit.org/ (Figure 13.1). From the main page, choose the Download heading.

Figure 13.1. The JUnit home page

That takes you to a SourceForge site (Figure 13.2); click on one of the sites near you, though any will do. The download is only a few hundred kilobytes, so it shouldn't take long.

Figure 13.2. The SourceForge download site

You'll be left with a file named junitX.Y.Z. zip, where the X, Y, Z characters are the digits that tell you what release of JUnit this is. Our examples show the 3.8.1 release.

Note

It's a good idea to inspect the ZIP files that you download before you actually unzip them. We like to know what files and especially what directories are going to get modified or cluttered up by the unzipping. Some ZIP files come with all their files inside of a single folder. Those are fine to unzip in place. Other ZIP files have been built from lots of pieces and unzipping them can make a mess of your current directory, or worse, of other directories that you may not even know about. Instead, play it safe and look before you leap. You can see the list of all the files in the JUnit ZIP file by typing this command:

 $ unzip -l junit3.8.1.zip 

The -l option will produce a listing of the contents of the ZIP file. That way you can see what subdirectories it will create, that is, if it is going to unpack into a single directory or make a mess. The JUnit ZIP file is very well behaved in this respect.

Create a directory and unpack the JUnit ZIP file in there:

 $ mkdir ~/junit $ mv junit3.8.1.zip !$ $ cd !$ $ unzip junit3.8.1.zip 

This warning from the installation instructions is worth noting:

Important

Don't install the junit.jar into the extention directory of your JDK installation. If you do so the test class on the filesystem will not be found.

The JDK installation directory has a subdirectory named jre/lib/ext. Don't put the JUnit JAR file in there. If you have followed our instructions, you're OK, since we had you create a new directory.

To use JUnit, the junit.jar file needs to be in your classpath. For example:

 $ export CLASSPATH="${CLASSPATH}:${HOME}/junit/junit3.8.1/junit.jar" 

That's all the installing there is. It doesn't feel like much, because you haven't done much. All it provides is a JAR file that you will use when you want to run tests. That's where it gets interesting.

13.4.2. Using JUnit

To test out your installation, cd to the directory where you unpacked JUnit. If it isn't already part of it, add the current directory (".") to your CLASSPATH:

 $ export CLASSPATH="${CLASSPATH}:." 

Then try:

 $ java junit.swingui.TestRunner junit.samples.AllTests 

You should see a Java Swing GUI appear, with a green bar showing the progress of the testing (Figure 13.3).

Figure 13.3. JUnit Swing GUI running tests

Note

You may see an error message like this in your terminal window:

 (data/time) java.util.prefs.FileSystemPreferences checkLock... WARNING: Could not lock System prefs.Unix error code 136742412 (data/time) java.util.prefs.FileSystemPreferences syncWorld WARNING: Couldn't flush system prefs: java.util.prefs.Backi... 

It will keep repeating as long as JUnit's GUI is running. The easiest fix is to make the jre directory world-writable while you run the GUI the first time. It will create the files it needs (in a directory, .systemPrefs), and thereafter stop pestering you. Remember to change permissions on the directory back to their original value.

This is the GUI part of JUnit, part of what has made it so popular. By writing JUnit tests, you get to use their GUI. If you were to develop your own testing mechanism, you would also have to (re)invent a GUI.

There is an AWT GUI for the Swing-averse, but it is less featured. There is also a plain command-line test case runner:

 $ java junit.textui.TestRunner junit.samples.AllTests ......................................... ......................................... ..................................... Time: 3.834 OK (119 tests) $ 

It prints a period for each test that it runs. (Yes, there are 119 periods there. Go ahead; count them if you must.) The command-line version is useful for incorporating JUnit tests into shell scripts (e.g., for testing nightly builds, e-mailing the results) and is used by ant when it invokes JUnit.