2: Unit Testing

Write tests first

1. Describe what the code is supposed to do, not with some external graphical tool but with code that actually lays the specification down in concrete, verifiable terms.
2. Provide an example of how the code should be used; again, this is a working, tested example, normally showing all the important method calls, rather than just an academic description of a library.
3. Provide a way to verify when the code is finished (when all the tests run correctly).

A very simple framework

//: com:bruceeckel:test:UnitTest.java
// The basic unit testing class
package com.bruceeckel.test;
import java.util.*;

public class UnitTest {
  static String testID;
  static List errors = new ArrayList();
  // Override cleanup() if test object 
  // creation allocates non-memory 
  // resources that must be cleaned up:
  protected void cleanup() {}
  // Verify the truth of a condition:
  protected final void affirm(boolean condition){
    if(!condition)
      errors.add("failed: " + testID);
  }
} ///:~

Writing tests

//: c02:TestDemo.java
// Creating a test
import com.bruceeckel.test.*;

public class TestDemo {
  private static int objCounter = 0;
  private int id = ++objCounter;
  public TestDemo(String s) {
    System.out.println(s + ": count = " + id);
  }
  public void close() {
    System.out.println("Cleaning up: " + id);
  }
  public boolean someCondition() { return true; }
  public static class Test extends UnitTest {
    TestDemo test1 = new TestDemo("test1");
    TestDemo test2 = new TestDemo("test2");
    public void cleanup() { 
      test2.close();
      test1.close();
    }
    public void testA() { 
      System.out.println("TestDemo.testA"); 
      affirm(test1.someCondition());
    }
    public void testB() { 
      System.out.println("TestDemo.testB");
      affirm(test2.someCondition());
      affirm(TestDemo.objCounter != 0);
    }
    // Causes the build to halt:
    //! public void test3() { affirm(false); }
  }
} ///:~

test1: count = 1
test2: count = 2
TestDemo.testA
Cleaning up: 2
Cleaning up: 1
test1: count = 3
test2: count = 4
TestDemo.testB
Cleaning up: 4
Cleaning up: 3

//: c02:TestDemo2.java
// Inheriting from a class that 
// already has a test is no problem.
import com.bruceeckel.test.*;

public class TestDemo2 extends TestDemo {
  public TestDemo2(String s) { super(s); }
  // You can even use the same name 
  // as the test class in the base class:
  public static class Test extends UnitTest {
    public void testA() {
      System.out.println("TestDemo2.testA");
      affirm(1 + 1 == 2);
    }
    public void testB() {
      System.out.println("TestDemo2.testB"); 
      affirm(2 * 2 == 4);
    }
  }
} ///:~

White-box & black-box tests

//: c02:Testable.java

public class Testable {
  private void f1() {}
  void f2() {} // "Friendly": package access
  protected void f3() {} // Also package access
  public void f4() {}
} ///:~

//: c02:TooMuchAccess.java
import com.bruceeckel.test.*;

public class TooMuchAccess extends UnitTest {
  Testable tst = new Testable();
  public void test1() {
    tst.f2(); // Oops!
    tst.f3(); // Oops!
    tst.f4(); // OK
  }
} ///:~

//: c02:testable:Testable.java
package c02.testable;

public class Testable {
  private void f1() {}
  void f2() {} // "Friendly": package access
  protected void f3() {} // Also package access
  public void f4() {}
} ///:~

//: c02:test:BlackBoxTest.java
import c02.testable.*;
import com.bruceeckel.test.*;

public class BlackBoxTest extends UnitTest {
  Testable tst = new Testable();
  public void test1() {
    //! tst.f2(); // Nope!
    //! tst.f3(); // Nope!
    tst.f4(); // Only public methods available
  }
} ///:~

Running tests

//: com:bruceeckel:test:RunUnitTests.java
// Discovering the unit test
// class and running each test.
package com.bruceeckel.test;
import java.lang.reflect.*;
import java.util.Iterator;

public class RunUnitTests {
  public static void 
  require(boolean requirement, String errmsg) {
    if(!requirement) {
      System.err.println(errmsg);
      System.exit(1);
    }
  }
  public static void main(String[] args) {
    require(args.length == 1,
      "Usage: RunUnitTests qualified-class");
    try {
      Class c = Class.forName(args[0]);
      // Only finds the inner classes 
      // declared in the current class:
      Class[] classes = c.getDeclaredClasses();
      Class ut = null;
      for(int j = 0; j < classes.length; j++) {
        // Skip inner classes that are 
        // not derived from UnitTest:
        if(!UnitTest.class.
            isAssignableFrom(classes[j]))
              continue;
        ut = classes[j];
        break; // Finds the first test class only
      }
      // If it found an inner class, 
      // that class must be static:
      if(ut != null)
        require(
          Modifier.isStatic(ut.getModifiers()),
          "inner UnitTest class must be static");
      // If it couldn't find the inner class, 
      // maybe it's a regular class (for black-
      // box testing:
      if(ut == null)
        if(UnitTest.class.isAssignableFrom(c))
          ut = c;
      require(ut != null, 
        "No UnitTest class found");
      require(
        Modifier.isPublic(ut.getModifiers()),
        "UnitTest class must be public");
      Method[] methods = ut.getDeclaredMethods();
      for(int k = 0; k < methods.length; k++) {
        Method m = methods[k];
        // Ignore overridden UnitTest methods:
        if(m.getName().equals("cleanup")) 
          continue;
        // Only public methods with no 
        // arguments and void return 
        // types will be used as test code:
        if(m.getParameterTypes().length == 0 &&
           m.getReturnType() == void.class &&
           Modifier.isPublic(m.getModifiers())) {
             // The name of the test is 
             // used in error messages:
             UnitTest.testID = m.getName();
             // A new instance of the 
             // test object is created and 
             // cleaned up for each test:
             Object test = ut.newInstance();
             m.invoke(test, new Object[0]);
             ((UnitTest)test).cleanup();
        }
      }
    } catch(Exception e) {
      e.printStackTrace(System.err);
      // Any exception will return a nonzero 
      // value to the console, so that 
      // 'make' will abort:
      System.err.println("Aborting make");
      System.exit(1);
    }
    // After all tests in this class are run,
    // display any results. If there were errors,
    // abort 'make' by returning a nonzero value.
    if(UnitTest.errors.size() != 0) {
      Iterator it = UnitTest.errors.iterator();
      while(it.hasNext())
        System.err.println(it.next());
      System.exit(1);
    }
  }
} ///:~

Automatically executing tests

Exercises

1. Install this book’s source code tree and ensure that you have a make utility installed on your system (Gnu make is freely available on the internet at various locations). In TestDemo.java, un-comment test3( ), then type make and observe the results.
2. Modify TestDemo.java by adding a new test that throws an exception. Type make and observe the results.
3. Modify your solutions to the exercises in Chapter 1 by adding unit tests. Write makefiles that incorporate the unit tests.

chris@sunpack.com Last Update:09/08/2001