Crash Course in Using JUnit

Introduction

Please note that in this document, I have included only the bare minimum that is sufficient to get you started. To use JUnit effectively, you will need to read more documentation. The references at the end of this document will point you to other useful information. In the next section, I will give you an overview of how to use JUnit followed by a detailed example. Then, I will provide suggestions on how you can package your programs before ending with a list of useful references.

Using JUnit

Overview

Assuming that you want to test a class called Parser. The following are the general steps to use the JUnit framework to test this class:

1. Write a class (let's call it TestParser) to test the Parser class. This class must extend the class TestCase which is defined by the JUnit framework.
2. Create a constructor for this class, passing a name that is representative of the set of tests for this class as the parameter.
3. Create a fixture. A test fixture is a set of sample objects that you want to (re)use during testing. For example, you might create a few sample source files for the Parser to parse. JUnit provides a setUp and a tearDown method to manage the fixture. Therefore, you can eg. create file objects in setUp to open the source files and release these resources in the tearDown method. The important thing to note is that setUp and tearDown will be called for every 'test' that you run.
4. Each 'test' you perform is represented by the implementation of a method in the test class. For example, if you want to test whether the parser extracts the tokens correctly, you can implement a method called testGetToken. An important point is that each method name begins with the word 'test'. This is necessary because JUnit uses reflection to know which tests to run. The collection of test methods you implement forms a test suite.
5. In each test method you create, use the assertion mechanism provided by JUnit to compare the results of running the tests and the results you expected. This will enable you to create repeatable tests as well as saving you lots of time from visually inspecting the results.
6. Finally, run the tests. There are two ways of running the tests. JUnit provides a TestRunner tool that can be invoked from the command line to run the tests and display the results. (there are both text and graphical versions). Alternatively, you can create a main method which invokes the TestRunner for execution. Internally, JUnit creates a test suite object that contains all the test methods of the testing class and execute each method. As each test is run, JUnit will provide feedback on whether the test run successfully, or the test failed, or an exception has occurred.

Example

• Course.java

  // this class is used for storing the information of a course
  public class Course {
      String course_name;           // name of the course
      int grade;                    // grade for this course
  
      // Constructor
      public Course(String nm, int gr) throws RuntimeException {
  	// check that the parameters are valid
  	if (nm == null || nm.equals("") || gr < 0 || gr > 100)
  	    throw new RuntimeException("Illegal inputs for Course");
  
  	// store the course name and its grade
  	course_name = nm;
  	grade = gr;
      }
  
      // method to get the name of the course
      public String getCourseName() { return course_name; }
  
      // method to get the grade of the course
      public int getCourseGrade() { return grade; }
  }
      

• Student.java

  import java.util.*;
  
  // Student is a data manager that keeps a student's record
  public class Student {
      private String name;           // name of the student
      private String number;         // the student's number
      private Vector course_grades;  // courses taken by student
  
      // Constructor
      public Student(String nm, String no) throws RuntimeException {
  	// check that the parameters are valid
  	if (nm == null || no == null)
  	    throw new RuntimeException("Invalid inputs");
  
  	// store the student's name and number
  	name = nm;
  	number = no;
  
  	// initialize the vector that will store the student's grade
  	course_grades = new Vector();
      }
  
      // method to get the student's name
      public String getStuName() { return name; }
  
      // method to get the student's number
      public String getStuNumber() { return number; }
  
      // method to assign a grade to a course
      public void assignGrade(String course, int score) 
        throws RuntimeException {
  	Course c = new Course(course, score);
  	course_grades.addElement(c);
      }
  
      // method to return the grade of a course
      public int getGrade(String course) throws RuntimeException {
  	// check the inputs
  	if (course == null)
  	    throw new RuntimeException("Invalid course name");
  
  	// find the course
  	for (Enumeration e = course_grades.elements(); 
               e.hasMoreElements();) {
  	    Course c = (Course)e.nextElement();
  	    if (course.equals(c.getCourseName()))   
  		return c.getCourseGrade();         
  	} // for
  	// if course does not exists, throw exception
  	throw new RuntimeException("Course " + course + " does not exist");
      }
  }
      

import junit.framework.*;    // Note 1

public class StudentTest extends TestCase {    // Note 2
  // constructor - Note 3
  public StudentTest(String name) {
    super(name);
  }
  
  // method to test the constructor of the Student class
  public void testConstructor() {    // Note 4
    String student_name = "Jimmy";
    String student_no = "946302B";
    
    // create a new student
    Student stu = new Student(student_name, student_no);
    
    // verify that the object is constructed properly - Note 5
    assertEquals("student name wrong", student_name, stu.getStuName());
    assertTrue("student no. wrong", stu.getStuNumber().equals(student_no));
    
    // create some illegal inputs - Note 6
    try { 
      Student s = new Student("Jimmy", null); 
      fail("Constructor allows null student number"); 
    } catch (RuntimeException e) {}

    try { 
      Student s = new Student(null, "980921C"); 
      fail("Constructor allows null student name"); 
    } catch (RuntimeException e) {}
  }
    
  // method to test the assigning and retrieval of grades
  public void testAssignAndRetrieveGrades() {
    // create a student
    Student stu = new Student("Jimmy", "946302B");
    
    // assign a few grades to this student
    stu.assignGrade("cs2102", 60);
    stu.assignGrade("cs2103", 70);
    stu.assignGrade("cs3214s", 80);
    
    // verify that the assignment is correct
    assertTrue("fail to assign cs2102 grade", stu.getGrade("cs2102") == 60);
    assertTrue("fail to assign cs2103 grade", stu.getGrade("cs2103") == 70);
    
    // attempt to retrieve a course that does not exist
    try { 
      stu.getGrade("cs21002");
      fail("fail to catch non-existent course name");
    } catch (RuntimeException e) { }
  }
  
  // method create a test suite - Note 7
  public static Test suite() {
    return new TestSuite(StudentTest.class);
  }
  
  // the main method - Note 8
  public static void main(String args[]) {
    junit.textui.TestRunner.run(suite());
  }
}

• Note 1
  To use the JUnit's classes, you must have this import statement.
• Note 2
  Every test class that you wrote must extend the class TestCase.
• Note 3
  This constructor is quite standard, you can just cut and paste for every test class you create.
• Note 4
  This is an example of a method written to test one of the methods of the Student class. In this case, it's the constructor. Notice that all the method names start with "test" (in lowercase). This is required for JUnit to find the methods to test at runtime. Hence, don't forget to begin all methods with the word "test".
• Note 5
  There are several ways to test whether the results from the test is what you expected. The assertEquals method takes three arguments. The first argument is a message that gets printed if the assertion fails while the remaining two arguments are compared to see if they are equal. The assertion fails if they are not equal. On the other hand, the assertTrue method takes only two arguments. Its only difference from the assertEquals method is that the second argument is a boolean expression which results in either a true or false value.
• Note 6
  You can use the following code to test for cases where an exception is expected. Notice that if the exception is not thrown, the fail method will be invoked causing the test to fail and printing the message passed as an argument to the fail method.
• Note 7
  The class method suite is used for assembling all the tests into a test suite. You will need to include this method for each class that uses the JUnit framework. Just modify accordingly.
• Note 8
  The main method used here invokes the text-based version of the TestRunner. Fairly standard - just cut and paste to your test classes.

java StudentTest

// method to find the average grade of all the courses taken by the student
public float findAveGrade() {
    // if the student has not taken any courses, return 0 marks
    if (course_grades.isEmpty()) return 0.0f;

    // otherwise, find the average grade
    int total = 0;
    for (Enumeration e = course_grades.elements(); e.hasMoreElements();) {
        Course c = (Course)e.nextElement();
        total += c.getCourseGrade();
    }

    return (float)total / course_grades.size();
}

• The JUnit official web site
  Everything you need to know about JUnit can be found here.
• JUnit Primer
  A quickstart guide - very useful to get you up and running fast.
• Test Infected - Programmers Love Writing Tests
  This document provides a more detailed look at using JUnit. If you have a bit of time to spare, it's definitely worth reading.
• JUnit A Cook's Tour and A UML Testing Framework
  Both these are useful in understanding the overall framework of JUnit. They deal mainly with the design of JUnit. Useful if you want to understand what goes behind the scenes in designing JUnit.
• JUnit best practices
  One of the more recent documents on JUnit. This article describes some useful ways for using JUnit as well as things you should avoid when using it.