MockDoclet

What is MockDoclet?

MockDoclet is an active code generation tool for automatically generating mock objects implementation classes from existing classes or interfaces in Java.

What are Mock Objects?

Mock objects are used to assist unit testing. A mock object is passed into an object to be tested and allows testing to occur from the inside.

For example, suppose you have a servlet that looks at parameters from an HttpServletRequest object and runs some SQL against a database passed in as a JDBC Connection based on the parameter. This is quite awkward to test as you require your class to be deployed in a servlet engine and have a database available in order to test it. Even then, you have to establish an HTTP request to the server and check that the database has been updated correctly - how do you do that?

Mock objects provide an elegant solution to this problem. You supply a MockHttpServletRequest and MockConnection to your servlet. Mocks provide 2 useful pieces of functionality in this problem:

• Firstly, you can easily setup a mock object with the necessary values it should return when methods are called. In this case, you could setup the MockHttpServletRequest to return certain parameters that you wish to test your servlet can handle.

• Secondly, you can define how you expect your object to interact with the mock. In this case, our expectations are that the correct SQL is passed to our database, in relation to the parameters from the MockHttpServletRequest. If the servlet doesn't meet our expectations, the unit tests will fail.

More information...

What aren't Mock Objects?

Small animals with three legs of different lengths that run around mountains in the Highlands. Those are haggis.

But why another Mock Object framework?

Here's a quick description of the existing mock object frameworks, and how they relate to Mocklet.

• MockObjects
  The MockObjects project aims to provide some utility classes for building mock objects and mock implementations of common libraries (such as IO, Servlets, JDBC and some vendor specific tools). It also serves as a site for describing usage patterns and hosting a community around mock objects. MockDoclet generated code depends on the MockObjects package.

• MockMaker
  MockMaker achieves exactly the same results as MockDoclet except goes about it in a different way. MockMaker was designed to be a passive code generation tool whereas MockDoclet uses active code generation. See below for the difference. MockDoclet is based on the MockMaker tool and generates nearly identical source code. If you change your preference from passive to active or vice-versa, it should be pretty easy to switch around.

• EasyMock
  EasyMock aims to achieve the same as MockDoclet and MockMaker except it does not generate code. Instead it makes use of reflection using dynamic proxies to automatically take on an interface at runtime. EasyMock is great for simple objects but can get tricky for more complicated interfaces. EasyMock complements MockMaker/MockDoclet nicely.

How does it work?

MockDoclet is built on top of XDoclet which is a generic code generation tool that uses JavaDoc to parse source files and extract JavaDoc comments like @this.

Any source file that defines @mock:generate in its JavaDoc header shall automatically have the source for a MockObject class added to it. The generated source file uses the MockObjects library internally.

The generate classes can then be compiled as normal and used in your unit tests.

Why is active code generation important?

The fundamental difference between MockDoclet and MockMaker is that MockDoclet is designed to be used as an active code generator and MockMaker as a passive code generator.

Passive code generators are wizard-like code generators that developers typically generate code once (with certain options) and then from then onwards treat the file as any other source file. It is the developer's responsibility to ensure it is maintained as the project evolves. Of course, generated code is generally not as clean and maintainable as developers would like them to be and can end up causing maintenance nightmares (MockModified syndrome).

Active code generators generate disposable code. The idea is that you have an input configuration that is easily maintainable and whenever it changes all the generated code is regenerated, overwriting previous versions. This is much simpler to maintain as the developer never actually modifies (or even looks at) the generated code.

Excellent coverage of code generators, including the pros and cons of active and passive generators, is given in the book The Pragmatic Programmer. Recommended read.

What do I need to use it?

Your project must be built using Ant and you need JUnit as your test framework. Some modifications and extra libraries are required at build time, and one extra jar is required when actually running your unit tests.

How do I use it?

You need to include a target in your build file to occur before compilation. This target will use MockDoclet to load the source files and generate any extra source files needed. The example below assumes your source files are in src and the generated source files are to be put in build/src.

[build.xml]

<!-- Path to mockdoclet and dependencies -->
<path id="mockdoclet">
  <fileset dir="lib/mockdoclet/" />
</path>

<target name="buildmocks">
  <!-- Load mockdoclet taskdef -->
  <taskdef name="mockdoclet"
       classname="org.mockmaker.doclet.MockDocletTask"
       classpathref="mockdoclet" />
  <mkdir dir="build/src" />
  <mockdoclet sourcepath="src" destdir="build/src" classpathref="mockdocklet">

    <!-- Process all src files -->
    <fileset dir="src">
      <exclude name="**/test/*" />
    </fileset>

    <!-- Generate Mock Object classes -->
    <mockobjects />

  </mockdoclet>
</target>

Next you markup your interfaces that you want Mock Objects generated for using @mock:generate.

[Database.java]

/**
 * Simple database abstraction.
 *
 * @mock:generate
 */
public interface Database {

  /**
   * Execute some SQL that modifies the database (UPDATE, INSERT, DELETE...).
   */
  void execute( String sql );

  /**
   * Execute some SQL that returns rows (SELECT...).
   */
  Rows select( String sql );

  // more methods...

}

[Rows.java]

/**
 * Simple database resultset abstraction.
 *
 * @mock:generate
 */
public interface Rows {

  boolean hasNext();
  String getString( String columName );

  // more methods...

}

Run ant buildmocks and it will generate MockDatabase and MockRows.

Now we have our mock objects, we can start testing code that depends on these above classes.

[AccountCleaner.java]

public class AccountCleaner {

  private Database database;

  public AccountCleaner( Database database ) {
    this.database = database;
  }

  public void fixCreditFlags() {
    Rows rows = database.select( "SELECT account, balance, credit FROM accounts" );
    database.start();
    while( rows.hasNext() ) {
      long account = rows.getLong( "account" );
      long balance = rows.getLong( "balance" );
      boolean credit = rows.getBoolean( "credit" );
      if ( balance < 0 && credit ) {
        database.execute( "UPDATE accounts SET credit = false WHERE account = " + account );
      }
      else if ( balance >= 0 && ! credit ) {
        database.execute( "UPDATE accounts SET credit = true WHERE account = " + account );
      }
    }
    database.commit();
  }

}

[AccountCleanerTest.java]

// more methods...

public void testBalances() {

  // check correct query is used for database.select().
  MockDatabase database = new MockDatabase();
  database.addExpectedSelectValues( "SELECT account, balance, credit FROM accounts" );

  // return some dummy data from database.select().
  MockRows rows = new MockRows();
  setupAccountRow( rows, 123, 999, true ); // correct
  setupAccountRow( rows, 124, -999, false ); // correct
  setupAccountRow( rows, 125, -1, true ); // should be corrected to false
  setupAccountRow( rows, 126, 5, false ); // should be corrected to true
  rows.setupHasNext( false );
  database.setupSelect( rows );

  // these are the expectations that need to be met to pass the test.
  database.addExpectedExecuteValues( "UPDATE accounts SET credit = false WHERE account = 125" );
  database.addExpectedExecuteValues( "UPDATE accounts SET credit = true WHERE account = 126" );

  // execute method to be tested.
  AccountCleaner cleaner = new AccountCleaner( database );
  cleaner.fixCreditFlags();

  // check it met our expectations.
  database.verify();

}

private void setupAccountRow( MockRows rows, long account, long balance, boolean credit ) {
  rows.setupHasNext( true );
  rows.setupGetLong( account );
  rows.setupGetLong( balance );
  rows.setupGetBoolean( credit );
}

// more methods...

Where do I get MockDoclet?

Download Mockdoclet

Tell me more!

• Endo-Testing: Unit Testing with Mock Objects
• MockObjects.com
• MockObjects on the XP-Developer Wiki

---

- Joe Walnes <joe@truemesh.com>