JDO and unit tests

Building App Engine apps with Java and GWT has become relatively easy, thanks to the great tool support with the eclipse plugin. Building these applications in a way that everything is easily testable is a little bit more work. The good news: once one has formed a habit of coding with tests in mind and learned a couple patterns on how to do it, it easily becomes second nature and produces leaner, cleaner, and more reliable software. On this blog, I occasionally post articles that focus a little more on that aspect of building App Engine apps (I'm starting to label them from now on for easier discoverability). This article is part of that series. Any code quoted in this post can be downloaded as open source and used under Apache license in any project. I would like to thank Max Ross, who provided a lot of inspiration in the unit tests for datanucleus-appengine and was also very helpful with advice as I was running into a couple of walls along the way :-)

One of the many things I liked about the Java App Engine launch is that right from the start, the team published Information on how to set up an App Engine based unit test. The recipe in those tests worked very well for me, especially since I was mostly working with the lower level DatastoreService and MemcacheService, not the standards based equivalents. Recently however, I wanted to test a class that uses JDO, so I needed a PersistenceManagerFactory. Getting such an object is not quite as straightforward: as documented, only one factory object per entire App Engine application should ever exist. If I try to load the factory more than once (like, say, once for each unit test), the system will actually throw an exception. Also, do I always need a jdoconfig.xml in my classpath? Turns out that the solution is not as complex as I thought at first. It took me a couple of attempts to get the setup right though, so I thought I'd share the recipe on my blog. As mentioned before, if you want to use these classes straight out of the box, you can also download them as a jar file.

Assume we have a class TestEnvironment, just like in the official instructions. With this class, we can create a straightforward TestInitializer class that can prepare an App Engine environment for us:

public class TestInitializer {

  private final ApiProxy.Environment environment;

  private PersistenceManagerFactory pmf;

  /**
   * Constructor
   * 
   * @param environmentOrNull
   *          the environment that should be used for the
   *          test (null to use the default)
   */
  public TestInitializer(
      ApiProxy.Environment environmentOrNull) {
    this.environment =
        (environmentOrNull == null) ? new TestEnvironment()
            : environmentOrNull;
  }

  /** Constructor with default parameters */
  public TestInitializer() {
    this(null);
  }

  /**
   * Sets up a unit test with the options stored in this
   * object. This method should only be called once per
   * object.
   */
  public void setUp() throws Exception {

    ApiProxyLocalImpl proxy =
        new ApiProxyLocalImpl(new File(".")) {
        };
    proxy.setProperty(
        LocalDatastoreService.NO_STORAGE_PROPERTY,
        Boolean.TRUE.toString());
    ApiProxy.setDelegate(proxy);
    ApiProxy.setEnvironmentForCurrentThread(environment);
  }
}

For the tearDown (cleanup after a unit test), I found a useful trick in the JDOTestCase class. Successful tests are expected to clean up after themselves and not leave any open transactions behind, which is verified by the following code:

  public void tearDown(boolean testWasSuccessful)
      throws Exception {
    Transaction txn =
        DatastoreServiceFactory.getDatastoreService()
            .getCurrentTransaction(null);
    try {
      if (txn != null) {
        try {
          txn.rollback();
        } finally {
          if (testWasSuccessful) {
            throw new IllegalStateException(
                "Datastore service still has an active txn.  Please "
                    + "rollback or commit all txns before test completes.");
          }
        }
      }
    } finally {
      ApiProxy.clearEnvironmentForCurrentThread();
    }
  }

So far, so good -- but what about JDO? As it turns out, javax.jdo.JDOHelper has a very useful utility method. It constructs a new PersistenceManagerFactory from a Properties object instead of the jdoconfig.xml This might be highly inefficient in production, but for unit tests, it completely bypasses the create-only-one-factory-ever rule :-). The following tool method makes use of this trick:

  private PersistenceManagerFactory pmf;

  public PersistenceManagerFactory getPersistenceManagerFactory() {
    if (pmf == null) {
      Properties newProperties = new Properties();
      newProperties
          .put(
              "javax.jdo.PersistenceManagerFactoryClass",
              "org.datanucleus.store.appengine.jdo."
              + DatastoreJDOPersistenceManagerFactory");
      newProperties.put("javax.jdo.option.ConnectionURL",
          "appengine");
      newProperties.put(
          "javax.jdo.option.NontransactionalRead", "true");
      newProperties.put(
          "javax.jdo.option.NontransactionalWrite", "true");
      newProperties.put("javax.jdo.option.RetainValues",
          "true");
      newProperties.put(
          "datanucleus.appengine.autoCreateDatastoreTxns",
          "true");
      newProperties.put(
          "datanucleus.appengine.autoCreateDatastoreTxns",
          "true");
      pmf =
          JDOHelper
              .getPersistenceManagerFactory(newProperties);
    }
    return pmf;
  }

Now that our TestInitializer is complete, it is easy to wrap it in a unit test. You can look at the entire code here, so suffice it to say that I create an abstract BaseTest that uses the initializer above and also provides a convenience method that gets me a new PersistenceManager object:

  public PersistenceManager newPersistenceManager() {
    return initializer.getPersistenceManagerFactory()
        .getPersistenceManager();
  }

Assumed we have a simple data class similar to the Employee class. The following unit test is a simple example that simulates storing and loading objects from the store using JDO:

package com.appenginefan.toolkit.unittests;

import java.util.Date;
import javax.jdo.PersistenceManager;

public class SimpleJDOTest
    extends BaseTest {

  public void testSetAndGet() {

    // Create a new employee and write the object to the
    // store
    final Date date = new Date();
    EmployeeData employee =
        new EmployeeData("John", "Doe", date);
    PersistenceManager manager = newPersistenceManager();
    final Long id =
        manager.makePersistent(employee).getId();
    manager.close();

    // From a different persistence manager, look up the
    // object
    manager = newPersistenceManager();
    employee =
        manager.getObjectById(EmployeeData.class, id);
    assertEquals(employee.getFirstName(), "John");
    assertEquals(employee.getLastName(), "Doe");
    manager.close();
  }
}

As shown above, once the BaseTest class is written that does all the setup one needs (and which can be reused throughout the projects), adding new persistence related tests is no longer that cumbersome. And when it's easy to write good tests, it usually is also more fun -- which means, more tests get written and more bugs detected before code goes into production.