Laurie Williams, Dright Ho, Ben Smith and Sarah Heckman [Contact Authors]
CSC 326 - Software Engineering
Department of Computer Science
North Carolina State University

Back to Software Engineering Tutorials

JUnit is an open source unit testing framework for automatically unit testing Java programs. JUnit provides functionality for writing and running unit test cases for a project under development, and is helpful when doing Test-Driven Development (TDD). This tutorial describes how to use JUnit within the Jazz environment, but most of the information except for running the JUnit test cases is generic to any JUnit set up. See http://www.junit.org/ for directions on how to run JUnit test cases outside of the Jazz environment.

Jazz is built on the Eclipse platform and comes with JUnit built into the Workbench. You can quickly create test case and test suite classes to write your test code in. With Jazz, Test-Driven Development (TDD), becomes very easy to organize and implement.

Typically, you create the application class that you want to test first. Then a tester can create the associated test case which provides a one-to-one correspondence between application classes and test classes. However, a tester can create test classes individually and later tie them to application classes. By using the built in functionality to create JUnit classes, the test cases are created with the needed imports and extensions for JUnit to run. Once the test case class is built the actual test cases are then coded in by the tester.

JUnit test classes can be rolled up to run in a specific order by creating a Test Suite. When a tester creates a test suite, Jazz will name it for you and will specify all of the test cases in the scope of the project that it can find. The code to run the test suite and to add all of the specified test cases you've created, is added to the test suite for you.

There are two versions of JUnit currently available. JUnit 3.8 uses specific naming conventions for identifying test classes, methods, and suites. These naming conventions are described below:

• Test Case Class: Named [classname]Test.java, where classname is the name of the class that is being tested.
• Test Case Method: Named test[methodname], where methodname is the name of the method that is tested.
• Test Suite: Default name for Jazz/Eclipse is AllTests.java

JUnit 4.0 uses annotations (which are keywords that start with @) to identify test classes, methods, and suites. The key annotations are described below.

• Test Case Class: Named [classname]Test.java, where classname is the name of the class that is being tested.
• Test Case Method: Annotate the method with @Test. The method name does not have to start with test.
• Test Suite: Only write a suite() method if you want to run your JUnit 4 tests with the JUnit 3.8 test runner.
• Test Set Up: Annotate the method with @Before
• Test Tear Down: Annotate the method with @After

1.1 Import CoffeeMaker into Jazz

We will be using the CoffeeMaker example through out this tutorial to highlight the main features of JUnit. CoffeeMaker is a small application that simulates the functionality of a coffee maker. The requirements for CoffeeMaker may be found here.

Download the CoffeeMaker example from here. See Eclipse Import/Export for instructions on how to import CoffeeMaker into your Jazz workspace.

1.2 CoffeeMaker File Structure

It is considered a best practice in testing, to separate the test case code from the application code. Typically the application code is in a source folder called src/ while the test code is in a source folder called unittests/ or tests/. Below is the file structure for the CoffeeMaker example that is used for as the exercise in this tutorial. You can emulate this file structure in your other Eclipse projects.

Figure 1: Best practice file structure

Most projects that you create will have a src/ folder that contain the main application code, a bin/ (which is not shown in the Package Explorer view) folder that contains the compiled .class files, and a lib/ folder that contains jar files that need to be on the project's build path. To run JUnit test cases the JUnit libraries must be on the classpath. JUnit 3.8 and JUnit 4 are integrated with Jazz; therefore, we can add the Jazz provided libraries to the project.

1.3 Putting JUnit libraries on the Project Classpath

The JUnit library is required to be on the project classpath to compile and run the JUnit test cases. The classpath may be specific to the computer that you are on, so check to make sure that the JUnit library is set up correctly. If your JUnit library isn't set up correctly, there will be an warning message at the top of the Java Build Path window.

1.1.1 Right click on the project and select Properties. In the left column select Java Build Path and select the Libraries tab.

Figure 2: Java Build Path for a Java Project

1.1.2. Select the Add Library... button to the right of the window. Select JUnit from the library list, and press the Next > button.

Figure 3: Add Library window.

1.1.3 Use the drop down box to select the version of JUnit that you want to use for your project. We are using JUnit 3 for the CoffeeMaker example in this tutorial. The location of your JUnit 3 library may vary from the one pictured below.

Figure 4: Select version for JUnit library

JUnit convention is that there is a test class created for every application class that does not contain GUI code. Usually all paths through each method in a class are tested in a unit test; however, you do not need to test trivial getter and setter methods.

2.1 There are many ways to create a JUnit Test Case Class.

2.1.1 Select File > New > JUnit Test Case

2.1.2 Select the arrow of the button in the upper left of the toolbar. Select JUnit Test Case ,

2.1.3 Right click on a package in the Package Explorer view in the Java Perspective, and select JUnit Test Case, or

2.1.4 Click on the arrow of the icon in the toolbar. Select JUnit Test Case .

2.1.5 You can create a normal Java class as shown in the Eclipse tutorial, but include junit.framework.TestCase as the super class of the test class you are creating.

2.1.6 Right click on an application class that you want to create a test class for, and select New > JUnit Test Case.

2.2 The wizard for creating a new JUnit test case classes is displayed in Figure 5. If you use the method of creating a JUnit test case presented in step 2.1.6, most of the information below will be filled in for you, but may require minor modifications.

Figure 5: JUnit test case class creation wizard

2.2.1 The source folder specifies where you want to create the test case. Based on the project hierarchy presented in Figure 1, we want to create the new test case in the unittests/ source folder.

2.2.2 Next, specify the package you want your test case to belong to. If you are associating your test case with an application class, then you will want both of these classes to share the same package so you can take advantage of package level visibility when testing your application class.

2.2.3 Specify the test case name. If you are associating your test case with an application class the convention is that the test case name is the application class name followed by Test.

2.2.4 JUnit has several standard methods that are useful for testing. setUp() and tearDown() methods are run before and after each test method.

2.2.5 If you are associating your test case with an application class, then Browse for the application class in the Class under test field.

2.3 If you selected a Class under test you can click the Next button to select which methods you want to write test cases for. The method signatures will be created for you. Click Finish and the new test case class will open in the editor.

2.4 Below is a test case template from the JUnit 3 FAQ. This test class demonstrates the basic functionality of the setUp() and tearDown() methods, and gives example test cases. The testForException() method demonstrates how to test that an exception is properly thrown.

Note: All source methods in the class under test must be public or protected, not private, in order to be tested by JUnit. If the method in the class under test is protected, the test class must be in the same package.

import junit.framework.TestCase;


public class SampleTest extends TestCase {


     private java.util.List emptyList;


     /**
      * Sets up the test fixture. 
      * (Called before every test case method.) 
      */ 
     protected void setUp() { 
          emptyList = new java.util.ArrayList();
     } 


     /**
      * Tears down the test fixture. 
      * (Called after every test case method.) 
      */ 
     protected void tearDown() { 
          emptyList = null; 
     } 


     public void testSomeBehavior() { 
          assertEquals("Empty list should have 0 elements", 0, emptyList.size());
     } 

     public void testForException() { 
          try { 
               Object o = emptyList.get(0); 
               fail("Should raise an IndexOutOfBoundsException");
          } 
          catch (IndexOutOfBoundsException success) {
          } 
     } 

}

 

2.5 Below is a test case template based on the examples presented in the JUnit 4 FAQ. This test class demonstrates the basic functionality of the setUp() and tearDown() methods, and gives example test cases. The testForException() method demonstrates how to test that an exception is properly thrown.

Note: All source methods in the class under test must be public or protected, not private, in order to be tested by JUnit. If the method in the class under test is protected, the test class must be in the same package.

import org.junit.*; 
import static org.junit.Assert.*; 


public class SampleTest { 


private java.util.List emptyList; 


    /** 
     * Sets up the test fixture. 
     * (Called before every test case method.) 
     */ 
    @Before 
    public void setUp() { 
        emptyList = new java.util.ArrayList(); 
    } 


    /** 
     * Tears down the test fixture. 
     * (Called after every test case method.) 
     */ 
    @After 
    public void tearDown() { 
        emptyList = null; 
    } 


    @Test 
    public void testSomeBehavior() { 
        assertEquals("Empty list should have 0 elements", 0, emptyList.size()); 
    } 

    @Test(expected=IndexOutOfBoundsException.class) 
    public void testForException() { 
        Object o = emptyList.get(0); 
    } 
}

• JUnit
• JUnit FAQ
• JUnit API
• Eclipse
• CoffeeMaker Example