Getting Started with JUnit

810:188
Agile Software Development

I have adapted this help sheet from the README file that comes with JUnit 3.8.1, both to simplify it and to fill in some details that you may find helpful.

Introduction

JUnit is a simple framework to write repeatable tests. It is an instance of the xUnit architecture for unit testing frameworks.

• Downloading and Installing JUnit
• Getting Started with JUnit
• Documentation
• Contents
• Possible Problems

Downloading and Installing JUnit

You can download JUnit from my site (v3.8.1) or from www.junit.org. The result is a zip file named junit.zip.

To install JUnit, do the following.

1. Unzip the junit.zip file. Place it in the directory of your choice.

   Confirm that you have a complete installation by comparing the contents of your junit3.8.1 directory to the expected contents.

2. Add junit.jar to your CLASSPATH.

   How to do this is system-specific. Here are some instructions that we have learned from experience on some particular platforms.

   • under the tcsh shell

     This is a common Unix shell, and the default shell for Mac OS X users.

   • under the bash shell

     This is also a common Unix shell, and the default shell for Linux users.

   • under Windows

     The instructions for different versions of Windows seem to vary, but I have collected what we know about 98, NT, and XP (the OS, not the agile methodology!) into one help file..

   If you use a different system or have any problems setting your classpath using these instructions, please let me know.

3. Test your installation by using one of JUnit's interfaces to run the suite of tests that comes with JUnit. All of the tests should pass.

   First, change into the junit3.8.1 directory. Then...

   • To run the tests using JUnit's text interface, enter:

     java junit.textui.TestRunner junit.samples.AllTests

   • To run the tests using JUnit's graphical interface (AWT), enter:

     java junit.awtui.TestRunner junit.samples.AllTests

   • To run the tests using JUnit's graphical interface (Swing), enter:

     java junit.swingui.TestRunner junit.samples.AllTests

You are now ready to begin programming test-first!

Getting Started with JUnit

To get started with unit testing and JUnit, read Test Infected - Programmers Love Writing Tests. This article appeared in the Java Report several years ago and introduced the world to JUnit. You can also find this article in <junit3.8.1/doc/testinfected/testing.htm>.

Test Infected demonstrates the development process with JUnit using a set of classes for arithmetic on money and currencies. The source code for this paper is in junit/samples/money/.

You can find some other examples in the junit.samples package:

• SimpleTest.java - some simple test cases
• VectorTest.java - test cases for java.util.Vector

Documentation

Here is some of the documentation that comes with JUnit:

• JUnit Cookbook -- doc/cookbook/cookbook.htm
  A cookbook for implementing tests with JUnit. You can also find this article at http://junit.sourceforge.net/doc/cookbook/cookbook.htm .

• JUnit - A cooks tour -- doc/cookstour/cookstour.htm
  A cookbook for implementing tools like JUnit. You can also find this article at http://junit.sourceforge.net/doc/cookstour/cookstour.htm .

• Javadoc -- javadoc/index.html
  API documentation generated with javadoc.

• Frequently asked questions -- doc/faq/faq.htm
  Some frequently asked questions about using JUnit.

• TestRunner Preference settings -- doc/JUnitProperties.html
  Describes the preferences settings that can be configured for the JUnit TestRunners.

Full Contents of the Release

A complete junit3.8.1/ directory contains:

The junit directory contains two subdirectories:

• samples -- examples that you can use to learn how to write test cases
• tests -- test cases for JUnit itself

Possible Problems

Don't place junit.jar into the extension directory of your JDK installation. If you do, your system will not be able to find the test classes.

The reason that you have to switch into the junit3.8.1 directory to run the tests is that JUnit's test suite is not in the junit.jar file. If you add INSTALL_DIR/junit3.8.1/ to your classpath, you should be able to run the tests from any directory, as well as access the sample classes that come with JUnit from anywhere, too.