I want to talk about essence vs. ceremony in unit testing.

If I give you this:

OrderTest
    testCalculatePrice
        1 20.00
        2  5.00
          30.00

Can you tell what this is about? This is a specification of the calculatePrice() method on an Order object, where there are two LineItem objects and the expected price is $30.00. Did you figure that out without the explanation? This is essence.

Instead, what you often see is something like this:

public class OrderTest { 

    @Test
    public void testCalculatePrice() {
        Order order = new Order();
        Product product1 = new Product(20.00);
        LineItem lineItem1 = new LineItem(1, product1);
        order.add(lineItem1);
        Product product2 = new Product(5.00);
        LineItem lineItem2 = new LineItem(2, product2);
        order.add(lineItem2);
        assertEquals(30.00, order.calculatePrice());
    }
}

Here, you're blinded with irrelevant details that obscure what this test is all about. The essence of the specification is buried in details. What you want is clarity at this level.

You can factor out the obscurity with something like this:

public class OrderTest {
    private Order order = new Order();

    @Test
    public void testCalculatePrice() {
        lineItem(1, 20.00);
        lineItem(2, 5.00);
        expectPrice(30.00);
    }
}

That's gets us about as close as we can in Java.

A consequence of this approach is that you have more methods overall, but I've always felt that clarity trumps in specifications. Others have agreed.

What's interesting with these helper methods is that I can change how I implement them and not change the higher level, essence methods at all. For example, in lineItem() I can inject real production objects (as I did in the original example with LineItem and Product), or I can inject a mock or stub LineItem.

So my suggestion is when you are specifying these high level methods, attempt to only show the essence of the test and factor out the ceremony.

The rule I use is that you can go up a package hierarchy and over to the right, but you can’t go down or to the left.  (Props go to Michael Gaffney for working with me to come up with this rule years ago).  Over to the right?  I’m working in the context of a layered architecture and when I say “over to the right,” I’m talking about something like this:

   presentation -> business -> persistence -> general utilities

So starting on the left, dependencies flow to the right.  You wouldn't want to go back to the left.  That would introduce a cycle.  Also, within a layer, you could go up the package hierarchy, but you wouldn't want to go down.

Here’s an example.  Suppose I’m developing a web application and I’m working on a class in the presentation layer.  I might have something like (contrived):

   package com.mycompany.myapp.web.struts;

   import java.util.List;
   import javax.servlet.http.HttpServletRequest;
   import javax.servlet.http.HttpServletResponse;
   import org.apache.commons.beanutils.PropertyUtils;
   import org.apache.struts.action.ActionForm;
   import org.apache.struts.action.ActionForward;
   import org.apache.struts.action.ActionMapping;

   import com.mycompany.myapp.utils.SomeUtil;
   import com.mycompany.myapp.domain.SomeDomainObject;
   import com.mycompany.myapp.domain.SomeOtherDomainObject;
   import com.mycompany.myapp.web.SomethingHigher;
   import com.mycompany.myapp.web.utils.SomethingToTheRightWithinModule;

Now, ideally, I’d like to list those imports in the exact opposite order.  That way, I could start at the package statement and look down and make sure the imports flow in an acceptable, directed acyclic graph kind of order, following the rule above.  In fact, I used to list them in this order, but everybody else lists them in an order more like the above, and so, I accepted defeat and now follow suit.  I just start at the bottom and look up.

I only care about ordering among packages here.  I don’t try to list the imports in dependency order among classes at the same package level.  That would be crazy.  However, I am strict within the layer of the class I’m working with.  In the example, that would be the web layer.  I’m looking at a class in ...web.struts and I want to make sure that I’m going to the right first, then up, all within com.mycompany.myapp.web in an appropriate package order.

Once I’m past the web layer, I loosen up.  I just want to make sure all the imports for the next layer are grouped together, and so on.  So in the example, all the domain imports would be together, then all the utils, and so on, all the way up to java.util.

You can set up this ordering standard in Eclipse under the Organize Imports preference.

How else could you check your dependencies?  There are useful tools out there like JDepend, and I use them.  But I still like this import ordering practice.  I typically do the manual scan right before check in time.

1. Extract Local Variable (possibly multiple times).
2. Extract Method
3. Inline the local variables created in step 1.

Let’s take the Range.equals() example from the previous blog. My brain dump would have resulted in a table like this:

Min	Max	Equals?
same	same	true
different	same	false
same	different	false

Yes, I would have jotted down other, exceptional cases for things like null and a non-Range object, but that’s out of scope here. For this blog, I’m just concentrated on comparing Range objects. I start with the positive case and come up with something like:

   private static final int MIN = 1;
   private static final int MAX = 7;

   private Range range = new Range(MIN, MAX);

To be honest, I probably would have had the MIN and MAX constants hardcoded in there, but at some point, I would have performed Extract Constant to come up with the above.

After I get that test to pass (by returning true), I’m ready to write the next test. I want to pick something simple again (of course in this example they’re all simple). But before I write the next test, I do something that is probably considered cheating by the hardcore test-driven development crowd. I’m not too concerned because I know from experience that I’m going to end up with tabular tests. In fact, the table is specified above!  So here goes the set of refactorings:

I first Extract Local Variable on MIN and MAX:

   public void testEqualsAnotherRange() {
      int testMin = MIN;
      int testMax = MAX;
      Range anotherRange = new Range(testMin, testMax);
      assertEquals(range, anotherRange);
   }

Now I know from my table that I need a boolean for my expected equals. There's no simple Eclipse refactoring so I manually make the change:

   public void testEqualsAnotherRange() {
      int testMin = MIN;
      int testMax = MAX;
      boolean expectedEquals = true;
      Range anotherRange = new Range(testMin, testMax);
      assertEquals(expectedEquals, range.equals(anotherRange));
   }

I highlight the last two lines and perform Extract Method:

   public void testEqualsAnotherRange() {
       int testMin = MIN;
       int testMax = MAX;
       boolean expectedEquals = true;
       testEqualsAnotherRange(testMin, testMax, expectedEquals);
   }

   private void testEqualsAnotherRange(int testMin, int testMax,
           boolean expectedEquals) {
       Range anotherRange = new Range(testMin, testMax);
       assertEquals(expectedEquals, range.equals(anotherRange));
   }

I want to get back to what it looks like in the table, so I Inline each local variable:

   public void testEqualsAnotherRange() {
      testEqualsAnotherRange(MIN, MAX, true);
   }

   private void testEqualsAnotherRange(int testMin, int testMax,
         boolean expectedEquals) {
      Range anotherRange = new Range(testMin, testMax);
      assertEquals(expectedEquals, range.equals(anotherRange));
   }

I just created the first row of the table by applying the set of refactorings that is the topic of this blog. At this point, I usually look at the parameterized method and make sure I’m happy with the signature. I’ve already done most of this when I extracted the method, but Eclipse doesn’t let me make the method static, if that’s appropriate (in this case it’s not). Eclipse also lists all the checked exceptions, which for tests, I’d rather generalize to Exception.  This doesn't apply in this case either.

During this set of refactorings, I would have ran the tests after a change or two just to make sure I didn’t break anything. I also do that because it feels good to get that green bar.

This is a pretty trivial example. Most of the time much more is going on in the parameterized method, but this still shows the removal of duplication.

I could have made these changes manually, but like I mentioned above, I like the automation; I’m less likely to break things.

   public void testEqualsAnotherRange() {
      testEqualsAnotherRange(MIN,     MAX, true);
      testEqualsAnotherRange(MIN - 1, MAX, false);
   }

I’ve got the red bar. Time to make it green.

Now, I know there are other tests for the equals() method, but I'm focusing on the meat of the tests here.  I also want to emphasize that I don't start out specifying all the tests like this.  I actually write one of the test cases, get that test to pass by minimally implementing the Range class, and then, as I start to write the next test case, I see the pattern and will extract the method and parameterize it for the next test case.

Time to make some points:

1. Test cases for the equals() method are grouped together.  If I want to know how the equals() method works for non-exceptional cases, all the test cases are right there. When I write code, I focus on a method for a particular production class.  That is, I'm trying to build out all the functionality for that method before moving on to the next method (or class).  I find it helpful to have all the test cases grouped together.  Parameterizing tests keeps the test cases as close together as possible.
2. Whenever I detect duplication, I strive to remove it.  This is a way to do so among the test cases.
3. The mapping between test methods and production class methods is nearly one to one.  There's one main testEquals() method for one equals() method.  Of course, I'll have test methods for exceptional cases, but I don't have much more test methods than production methods.  If I kept each test case in its own method, I'd have a harder time removing duplication and I would have much more test code than production code.
   

I should also point out that many times, I don't use the same fixture.  In the example above, I did, but many times I don't.  The parameters passed in to the test helper method could be used to setup the production object.  Sometimes, the parameters are used to help mock a nested object.   Take, for example, the typical web site Order class.  Let's suppose I were focused on the getTotal() method:

Now, I should point out some of the concerns of using this technique:

1. It doesn't follow the JUnit convention of working with the same fixture per TestCase.  Many times, my "fixture" is just an empty production object that will be setup in individual test methods.  Behaviour Driven Development (BDD) is getting press these days and its focus is on fixtures called Contexts.  Caveat: my knowledge of BDD is from reading this one article by Dave Astels, and I haven't experimented with it.  It seems to be good for showing behavior in a given context, whereas my technique is method focused.  Maybe I'll give it a shot in the future.
   
2. Because there isn't a real fixture, the test methods are more static than object-oriented.  That is, I might not be working with instance variables of the TestCase.  I don't find this to be an issue though.  I thought I'd point it out for OO purists.
   
3. Gerard Meszaros, who is writing a good book on test automation patterns, pointed out that if one of my earlier tests fails, then later tests won't be run.  He also pointed out that it is harder to determine how many total test cases there are since some are embedded.  These are valid points.  To counter, I mentioned that I am following test-driven development, so I am building the tests as I go, and I usually don't run into the situation where an earlier test fails, although it does happen.  I also never run into the situation where a bunch of tests are all of the sudden failing.  As for the number of test cases, I've never had a need to know.  But his points are definitely valid.
4. Tests aren't isolated.  You don't start fresh each time.  Thus, earlier tests could have unwanted side effects.  You have to be aware of this.  I either want side effects (as in the Order example where I'm building up an Order) or I simply start with an empty production object and build it up in the helper test method.
   

The first tip is coding by intention. The first time I learned of this was in college. I was reviewing some code with a professor of mine, Dave Binkley of Loyola College. We were reviewing a long method of mine and Professor Binkley said something equivalent to, “I like to extract a method here to make it more clear what I’m doing.” The light came on. I learned that programming was more than just a science, but an art. This was back in the early 90s, before the Extreme Programming/Agile folks coined terms like “extract method”, “refactor”, and “code by intention”.

Now, I'm a big fan of Test-Driven Development (TDD).  Since I've got to write a test first, I start there.  The real code doesn't exist yet.  The intent part starts here.  I think, "I've got this piece of functionality to implement.  What would I call if I could write anything?  What would the method name be and its arguments?  How would I call this functionality as a client so that what I'm doing is crystal clear? The world is my oyster."

Coding by intention from the point of view of the test is pretty obvious.  What I wanted to emphasize in this blog entry is to continue coding by intention all the way through until you've completely implemented everything.  So after you've created a new call in the test, you start implementing it.  It'll most likely be a public method.  When you're implementing this, you continue coding by intention.  You could just crank out a possibly long method to get the functionality implemented, but that's not what I'm talking about – that’s what I did in the early days of college.  The public method now becomes like another client.  You code by intention here, asking yourself what you would call if what you needed already existed.  You keep doing this with every method you need to implement, creating lots of small, but communicative and easy to understand methods.  Eventually, you'll get to a level where the implementation is small and simple and you're done.  What you've done is created some possibly reusable and very easy to maintain methods along the way.

It’s time for an example. Suppose I’m working with the usual Order/Line Items web site shopping example. One coding by intention technique I use when I need to process a collection like LineItems looks like this:

Instead of writing all the code in the while loop to process an item, I code by intention, pretending that the process(LineItem) method already exists.

Here’s another, albeit obviously contrived example. Suppose I’m working on Goldilocks’ Porridge class and need to implement the isJustRight() method. Right now I just have:

To implement isJustRight(), in coding by intention style, I would do:

So why code by intention? There are several reasons I can think of off the bat. The first is, as I’ve stated above, you end up creating small, possibly reusable methods. My first tip was going to be “create small methods”, but I realized that coding by intention drives that. In my next entry, I’ll go into more detail on why I think creating small methods is really important. There’s a process to crafting elegant software and this is the first step.

Another reason is that the top level methods become really easy to understand. 
They describe the algorithm in almost pseudo-code level. They communicate your intent of what you’re trying to accomplish step by step.

Yet another reason is that it is sometimes hard to get started on a task and by coding by intention you are delaying all the details, but still getting things done. That is, not everything you need is available, but you’re coding like it is. You’re working top down, drilling down into the details level by level until your done, making progress along the way.

Now, if you’re doing true TDD, you are writing just enough test to get a failing test, and just enough code to pass that test. Remember, compiler errors count as failures. I’m a little lenient on this practice. I like writing an entire test method for one test case scenario before going to the code. So in the isJustRight() method above, I’d first write a complete test method for a Porridge object that is too cold with all its calls and assertions. Then, I’d write just enough code to get the test to pass, but still coding by intention in the Porridge class. So, in this case, the isJustRight() method would just call notTooCold() for now.

I suppose if you truly wanted to follow TDD, and in particular, get a passing test as fast as you could, you could just write the code in isJustRight(), then extract a notTooCold() method. Just remember to do this. Sometimes, we as programmers get a little lazy. Still, I favor coding by intention top down from the beginning.

Well, that’s it for my first blog. Hope you enjoyed.