The JUnit team realized that programmers are always busy. A deadline is always looming. They knew that if JUnit wasn't easy to use, JUnit wouldn't be used. As a result, implementing JUnit tests requires little new knowledge. By learning one annotation and one method call, you can successfully write complex test suites. You just can't get much easier than that.

To implement a JUnit test, follow these steps:

Run JUnit using the java command. The target main class is org.junit.runner.JUnitCore. JUnitCore is followed by a space-separated list of test classes. Running tests from the command line takes the following form:

java -cp <tests and JUnit> org.junit.runner.JUnitCore <test classes>

I give a working example of using JUnit from the Terminal later in this appendix.

JUnit integrates with most build environments. Integrating JUnit with Xcode does not get as much attention as integrating with Eclipse or NetBeans, so few (if any) tutorials explain Xcode/JUnit integration. This section fills the gap by explaining how to integrate JUnit with Xcode. I use JUnit 4.6 and Xcode 3.2 for the following example.

Begin by creating a Java Tool project in Xcode for this integration example:

Your project is not quite ready to use. There are still a few steps to complete. You need an Executable and a Target.

These steps give you a properly configured Target:

Figure B.5. Configured target dialog box

Your Target is ready to use. This allows building and cleaning of the project. Before the next step, temporarily comment out the code in your XcodeAndJUnit class main() method and the import statements, and then click Build

Next, from inside Xcode, create the Executable by taking these steps:

Next, I explain adding JUnit to your project.

JUnit is conveniently packaged as a single JAR. The junit.jar is available from http://www.junit.org/. The junit.jar is named junit-<version number>.jar. I refer to it as the junit.jar for simplicity.

If you are working from a previously built Xcode project, your project contains a jar directory. When including the junit.jar in an Xcode project, placing the junit.jar in the project's jars/ directory may be your first impulse. Xcode's build.xml contains a clean target that deletes the jars/ directory. If you place the junit.jar in the jars/ directory, every time you clean your project, you also have to add JUnit back to the project.

A closer look at build.xml shows the comment "lib directory should contain any pre-built jar files needed to build the project." Place the junit.jar in the lib/ directory. Any JAR'ed libraries used to build the project should be placed in the lib/ directory.

All JAR'ed libraries placed in the lib/ directory end up repackaged in the project JAR. In our case, that is the XcodeAndJUnit.jar. Bundling junit.jar is fine during development, but it should be avoided for release builds. Also, remove test classes from release builds.

For this section's example, I jar junit.jar and the test classes in the build. If you want to prevent junit.jar and test classes from being built, you can place them in separate test directories, and then create and name the directories something like test_lib and test_src so they are easily identifiable. Then create a new external target and modify the build.xml file so that Ant builds and bundles the tests only when the new target is used.

The example code in this section requires Java 1.6. The Java target in Xcode uses Ant. On some OS X distributions, Ant—when run from Xcode—defaults to an older version of Java that cannot build this example's source. A quick fix is to include the JAVA_HOME property in the Target's Build Settings, as shown in Figure B.9, with the value being the path to /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home or a similar Java Home directory.

Figure B.9. Target with JAVA_HOME property

In this book, I harp on never hard coding JAVA_HOME. However, development environments are usually personalized to individual projects, computers, and developers. It is very likely that you do not want the target's version of Java in your project to change when you change the Java Preferences. This is one of those rare cases where hard coding JAVA_HOME makes sense.

The code example for this appendix consists of three classes and an enum. This Xcode project represents a rudimentary bill of materials generator. The code is contained in XcodeAndJUnit.java, Pricing.java, BillOfMaterials.java, and BillOfMaterialsTest.java.

The XcodeAndJUnit class creates and prints a bill of materials. This class contains the main() method. XcodeAndJUnit is not used during the JUnit test. Deleting this class has absolutely no affect on running the test. This class demonstrates the use of the BillOfMaterials class that is the object of the example test.

Once again, here is the code for XcodeAndJUnit:

import java.util.*;
import com.genedavis.*;
public class XcodeAndJUnit
{

   public static void main (String args[])
   {
      BillOfMaterials bom = new BillOfMaterials();

      bom.addGlass(6);
      bom.addSteel(10);
      bom.addOil(1);

      bom.printBill();
   }
}

The Pricing enum contains three materials (STEEL, OIL, and GLASS) that are initialized to a unit price in cents. In a real accounting program, I might use BigDecimal, but ints representing cents work in this limited example. The single method, getPricePerUnit(), is provided.

Here is the code for Pricing:

package com.genedavis;
public enum Pricing
{
   STEEL (5000),
   OIL   (100),
   GLASS (1500);
   private final int pricePerUnit;

   private Pricing(int ppu)
   {
      this.pricePerUnit = ppu;
   }
   public int getPricePerUnit()
   {
      return pricePerUnit;
   }
}

The class I will test with JUnit is BillOfMaterials. BillOfMaterials offers methods for adding units of glass, oil, and steel to the current bill of materials. The added items are stored in the lineItems HashMap<String,Integer>. The printBill() method calls the getTotalCost() method and the getBillBody() methods and then prints the results.

Here is the source for BillOfMaterials:

package com.genedavis;
import java.util.*;
import static com.genedavis.Pricing.*;
public class BillOfMaterials
{
   HashMap<String, Integer> lineItems =
      new HashMap<String, Integer>();

   public BillOfMaterials() {}

   public void addGlass(int quantity)
   {
      int ppu = GLASS.getPricePerUnit();
      int price = ppu*quantity;
      lineItems.put("Glass", price);
   }

   public void addSteel(int quantity)
   {
      int ppu = STEEL.getPricePerUnit();
      int price = ppu*quantity;

lineItems.put("Steel", price);
   }

   public void addOil(int quantity)
   {
      int ppu = OIL.getPricePerUnit();
      int price = ppu*quantity;
      lineItems.put("Oil", price);
   }

   public int getTotalCost()
   {
      int total = 0;

      for(Map.Entry<String,Integer> entry : lineItems.entrySet())
      {
         int value = entry.getValue();
         total += value;
      }

      return total;
   }

   public String getBillBody()
   {
      String billBody = "";

      for(Map.Entry<String,Integer> entry : lineItems.entrySet())
      {
         int value = entry.getValue();

         int dollars = value / 100;
         String cents = Integer.toString(value);
         cents = cents.substring(cents.length() - 2);

         String product = entry.getKey();

         billBody += product+"     $"+dollars+"."+cents+"
";

      }

      return billBody;
   }

public void printBill()
   {
      int total = getTotalCost();
      String billBody = getBillBody();

      int dollars = total / 100;
      int cents =  total % 100;

      System.out.print(billBody);

      System.out.println("

   total: $"+dollars+"."+cents);
   }
}

Finally, I can show you the actual test class, BillOfMaterialsTest. Comparing the test method of BillOfMaterialsTest with the main() method of XcodeAndJUnit, you see a strong correspondence. Both create and set up a BillOfMaterials. However, BillOfMaterialsTest attempts to assert the value of the BillOfMaterials getTotalCost() method.

The @Test annotation and the assertTrue() method make this test work. The packages imported are org.junit.* and org.junit.Assert.*. Once imported, the assertTrue() method and the @Text annotation are available. The @Test annotation marks a method as being a JUnit test. The assertTrue() method is the actual test. Using only one annotation and one method, you can build very powerful unit tests for your projects.

Here is the source code for the JUnit test class, BillOfMaterialsTest:

package com.genedavis;
import org.junit.*;
import static org.junit.Assert.*;
public class BillOfMaterialsTest
{
   @Test
   public void testBillOfMaterials()
   {
      BillOfMaterials testBom = new BillOfMaterials();

testBom.addGlass(6);
      testBom.addSteel(10);
      testBom.addOil(1);

      int testTotal = testBom.getTotalCost();
      assertTrue(testTotal == 59100);
   }
}

If you have not yet done so, add these three new classes () to the src/com/genedavis directory of your project. You need to create the com and genedavis directories. After you add these classes to your src/ directory, shown on the far left of Figure B.10, click Build and Run from the Xcode Console. This verifies that the project is working properly. After running your project, you are ready to test.

Figure B.10. Xcode project window with all Java source files in the directory tree on the left

If you want to run JUnit only from the command line at this point, these instructions will take care of running the BillOfMaterialsTest:

You should see a result similar to Figure B.11.

Figure B.11. JUnit test results shown in the Terminal

Running the test from inside of Xcode is not much different, and it may be even easier after it has been configured. The following instructions configure and run the JUnit test from Xcode:

Figure B.12. Executable arguments dialog box tab with new -cp

Clicking Build and Run in the Xcode Console should result in output similar to Figure B.13.

Figure B.13. Xcode Console test result

In this appendix, I explained the uses of JUnit. JUnit is written with test-driven development in mind. JUnit works well for regression testing and more casual testing strategies also.

JUnit is designed for simplicity of use. By learning as little as one annotation and one assertion method, you can create complex test suites. The annotation is @Test, and the assertion method is assertTrue().

Integrate JUnit with Xcode by placing the junit.jar in the build path. Create one or more JUnit test classes. The last step is to add a new -cp XcodeAndJUnit.jar org.junit.runner.JUnitCore <tests list> argument to the Java executable and run the tests.