We first start with the Specification interface:

import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Predicate;
import javax.persistence.criteria.Root;

/**
* <code>Specification</code> is used to test an object to see if it satisfies
* a certain criteria.
*
* @author had
* @author http://dddsample.sourceforge.net/
*
* @param  The type of the object to test.
*/
public interface Specification {
  /**
  * Tests the specified <code>candidate</code> if it satisfies the criteria
  * of this specification.
  * @param candidate The object to test.
  * @return <code>true</code> if <code>testObject</code> satisfies the
  * criteria of this specification, <code>false</code> otherwise.
  */
  boolean isSatisfiedBy(T candidate);

  /**
  * Transforms this specification into a predicate. (optional)
  * @param cb The criteria builder to use, must not be null.
  * @param query The query object to use, must not be null.
  * @param root The starting point, must not be null.
  * @return The created predicate which checks the rules.
  * @throws UnsupportedOperationException If this specification does not
  *  support predicate transformation.
  */
  Predicate toPredicate(CriteriaBuilder cb, CriteriaQuery query, Root root) throws UnsupportedOperationException;

  Specification and(Specification other);

  Specification or(Specification other);

  Specification not();
}

Based on the ideas published by Eric Evans (author of the book “Domain Driven Design”), this interface contains the following methods:

• isSatisfiedBy – to check an in-memory object if it satisifies the specification
• and, or, not – for boolean operations on the specification

The interface above has an additional method called toPredicate. This method transforms the (business-driven) intention of the specification into a Predicate which is used to fetch all persisted objects satisfying the specification – one important aspect of the Specification concept. The Predicate interface is defined by the JPA 2.0 Criteria API and can be used to build dynamic queries using predicates (as shown in the previous article).

An abstract specification implements the Specification interface as follows:

public abstract class AbstractSpecification<T> implements Specification<T> {
  @Override
  public Specification<T> and(Specification<T> other) {
    return new AndSpecification<T>(this, other);
  }

  @Override
  public Specification<T> or(Specification<T> other) {
    return new OrSpecification<T>(this, other);
  }

  @Override
  public Specification<T> not() {
    return new NotSpecification<T>(this);
  }
}

Last but not least, we need common implementations for the boolean operators:

import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Predicate;
import javax.persistence.criteria.Root;

public class AndSpecification<T> extends AbstractSpecification<T> {
  private final Specification<T> a;
  private final Specification<T> b;

  public AndSpecification(Specification<T> a, Specification<T> b) {
    this.a = a;
    this.b = b;
  }

  @Override
  public boolean isSatisfiedBy(T candidate) {
    return a.isSatisfiedBy(candidate) && b.isSatisfiedBy(candidate);
  }

  @Override
  public Predicate toPredicate(CriteriaBuilder cb, CriteriaQuery<T> query, Root<T> root) throws UnsupportedOperationException {
    return cb.and(a.toPredicate(cb, query, root), b.toPredicate(cb, query, root));
  }
}

One can easily imagine, how the OrSpecification and the NotSpecification look like.

The PlayerRepository defines two finder methods:

public interface PlayerRepository {
  public List<Player> findFairPlayers();
  public List<Player> findBonusEligiblePlayers();
}

Now your customer adds a new requirement: “I need a list of all players who are fair and bonus eligible!”. Invoking both existing methods and selecting the relevant players manually is not a good idea (not reusable, results in two database queries). Thus, this typically results in another finder method:

public interface PlayerRepository {
  public List<Player> findFairPlayers();
  public List<Player> findBonusEligiblePlayers();
  public List<Player> findFairAndBonusEligiblePlayers();
}

One can imagine that the complexity quickly increases and the DRY principle is violated.

Yesterday, Mischa Kölliker and I gave a talk about Rich Domain Model using JPA 2.0 at the Java Forum Stuttgart where we combined the specification pattern described by Eric Evans with the Criteria API introduced in JPA 2.0. This means that the resulting interface will look like this:

public interface PlayerRepository {
  public List<Player> findAll(Specification<Player> specification);
}

The three finder methods have been reduced to one generic findAll method. The findAll method accepts a specification parameter which – as its name implies – specifies what the repository must select.

The concrete implementation uses JPA 2.0 Criteria API:

public class JPAPlayerRepository implements PlayerRepository {
  public List<Player> findAll(Specification<Player> specification) {
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<Player> q = cb.createQuery(Player.class);
    Root<Player> player = q.from(Player.class);

    q.where(specification.toPredicate(cb, q, player));

    return em.createQuery(q).getResultList();
  }
}

public class FairPlayerSpecification implements Specification<Player> {

  private static final int NUMBER_OF_CARDS = 5;
  private int season = 0;

  public FairPlayerSpecification(int season) {
    this.season = season;
  }

  @Override
  public Predicate toPredicate(
    CriteriaBuilder cb, CriteriaQuery<Player> q, Root<Player> player) {

    Subquery<Long> sq = q.subquery(Long.class);
    Root<Card> card = sq.from(Card.class);

    sq.where(cb.and(cb.equal(card.get(Card_.player), player),
    cb.equal(card.get(Card_.season), this.season)));

    return cb.lt(sq.select(cb.count(card)), NUMBER_OF_CARDS);
  }

  //...
}

The repository delegates the where clause to the specification which transforms itself into a valid JPA 2.0 predicate object. A predicate is just a boolean expression which can be true or false.

This approach shows its strengths best when composing specifications. For example: the talent scout wants to find all his “problem children” who are specified as follows:

• unfair OR not bonus eligible      AND
• long running contract

The corresponding code looks like this:

Specification<Player> unfair;
Specification<Player> notBonusEligible;
Specification<Player> longRunningContract;
Specification<Player> problemChild;

unfair = new FairPlayerSpecification(2009).not();
notBonusEligbile = new BonusEligbileSpecification().not();
longRunningContract = new LongRunningContractSpecification();

problemChild = longRunningContract.and(unfair.or(notBonusEligible));

One may argue that combining specifications with Criteria API mixes up business and technical aspects. In the above example this is certainly true, especially when you need to abstract away from your technology (here JPA). On the other hand you should always look for a pragmatic and cohesive solution… and we think this is a possible approach to start with.

Would be great to hear about your experiences implementing composed specifications using O/R mapping technologies (especially JPA 2.0).

The TransferTestModel source code looks like this:

public class TransferTestModel {
  private Account debitAccount;
  private Account creditAccount;
  private Date transferDate;
  private Money transferAmount;

  private TransferTestModel() {} // not instantiable

  public static TransferTestModel startTransferFromPrivateAccount() {
    return new TransferTestModel() {
      {
        debitAccount = new PrivateAccount(
          "1122334455", new Money("CHF", 5000));
      }
    }
  }

  public TransferTestModel toForeignBankAccount() {
    creditAccount = new GenericBankAccount(
      "9988776655", new Address("Money Receiver", "1234", "Somewhere"));
    return this;
  }

  public TransferTestModel asSoonAsPossible() {
    transferDate = DateUtils.nextBusinessDay();
    return this;
  }

  public TransferTestModel amountGreaterThanAvailableMoney() {
    transferAmount = debitAccount.getBalance().add(1);
    return this;
  }

  public Transfer build() {
    return new Transfer(
      creditAccount, debitAccount, transferDate, transferAmount);
  }
}

This class follows the Builder pattern and consists of three parts:

1. The static (factory) method startTransferFromPrivateAccount starts the build process. (mandatory data)
2. The three member methods toForeignBankAccount, asSoonAsPossible, and amountGreaterThanAvailableMoney define the transfer details. (optional data)
3. The build method finishes the build process and returns the Transfer object.

Even though the TransferTestModel has only one static and three member methods, it already supports eight different test scenarios:

= <number of static methods> * (2 ^ <number of member methods>)

By adding

• new static factory methods (e.g. for account types applying different business rules) and
• new member methods (e.g. for further business aspects, threshold testing, or special cases which need complex initializations),

the model will be enriched and more test scenarios are possible.

Assume we want to test transfers from a savings account (with a different “available money” policy), transfers scheduled on a weekend day, and transfers scheduled in the past. Let’s see how the model will be expanded…

public class TransferTestModel {
  public static TransferTestModel startTransferFromSavingsAccount() {
    return new TransferTestModel() {
      {
        debitAccount = new SavingsAccount(
          "12356789", new Money("CHF", 150000));
      }

      @Override
      public TransferTestModel amountGreaterThanAvailableMoney() {
        // a maximum of CHF 50'000 can be transferred
        // from a savings account
        transferAmount = new Money("CHF", 50001);
        return this;
      }
    }
  }

  public TransferTestModel onWeekendDay() {
    Calendar cal = Calendar.getInstance();
    int dayOfWeek = cal.get(Calendar.DAY_OF_WEEK);
    int offset = Math.min(1, Calendar.SATURDAY - dayOfWeek);
    cal.add(Calendar.DAY_OF_MONTH, offset);
    transferDate = cal.getTime();
    return this;
  }

  public TransferTestModel inThePast() {
    Calendar cal = Calendar.getInstance();
    cal.add(Calendar.DAY_OF_MONTH, -1);
    transferDate = cal.getTime();
    return this;
  }

  // snipped code of first sample (see above)
}

The startTransferFromSavingsAccount method initializes a transfer using a savings account and overrides the default amountGreaterThanAvailableMoney method. Of course, a real-life test model would not use hardcoded amounts and policy rules (as used in the example above) but would rather delegate this to the business layer.

By overriding the default implementation, the static factory method defines and therefore encapsulates the (context bound) test behavior.  A unit test based on this new method does not care about these details:

public class TransferServiceTest {
  @Test
  public void testTransferUsingInvalidAmount() {
    Transfer transfer = TransferTestModel
      .startTransferFromSavingsAccount()
      .toForeignBankAccount()
      .asSoonAsPossible()
      .amountGreaterThanAvailableMoney()
      .build();

    Transaction transaction = transferService.transfer(transfer);
    // Assert expected transaction details
  }
}

This test only denotes that it wants to transfer an “invalid” amount but does not know what “invalid” means in terms of a savings account – this knowledge is hidden in the test model.

Outlook

A further article will focus on test assertions and method naming… stay tuned!

How do you manage complex test scenarios especially the variety of parameters, entities, and their interdependencies? What are your experiences maintaining these test cases?

According to my experience, writing automated tests does not implicitly mean that these tests are useful and maintainable. Furthermore, writing tests for a complex domain can become a pretty tricky task. A lot of test methods are full of cumbersome (and itself error-prone) initialization code to build the test parameters and to invoke the methods under test.

This article shows the drawbacks of a hard coded, naïve test approach and proposes a “rich test model” to address those issues.

Test at first feel

Let’s transfer some money and test the transfer service:

public class TransferServiceTest {
  @Test
  public void testTransferWithInvalidAmount() {
    Transfer transfer = new Transfer();
    transfer.setDebitAccount("1122334455");
    transfer.setCreditAccount("9988776655",
      new Address("Money Receiver", "1234", "Somewhere"));
    transfer.setTransferDate(new Date());
    transfer.setAmount("EUR", 1000);

    Transaction transaction = transferService.transfer(transfer);
    // assert expected transaction details ...
  }
}

There are some issues with this approach:

1. Explicit interdependencies.
   The explicit usage of account numbers, address data, date, and amount requires detailed knowledge about the data structures and their relationships. Replacing the hard coded values by constants would not solve the problem as we still need to know which values suit together for this test scenario.
2. Complicated threshold value testing.
   Since the transfer amount and date are explicitly set, threshold value testing becomes cumbersome. Assume you want to test the following scenarios: the transfer amount is 1) lower, 2) equal, and 3) greater than the currently available money. You will need to know the type of account “1122334455″, the current balance and the allowed overdraw policy of this account. This is too much information for such a simple example.
3. Violated DRY principle.
   If different test scenarios are based on the same test data set, we run the risk of violating the DRY (don’t repeat yourself) principle because the “knowledge” of these data interdependencies is spread all over the tests.
4. Maintenance hell.
   Automated tests are an essential key factor for successful projects. At first feel, automated tests seem to behave nicely. But if you need to change those tests – and this happens – they can show their true colors. What happens if interdependencies change, or if new business rules affect all your tests? In the worst case you have to change hundreds of test scenarios.

This rule addresses the aforementioned issues:

Test methods must express what they test, not how they test.

Separate test method from the model

Let’s change the above code snippet a little bit:

public class TransferServiceTest {
  @Test
  public void testTransferUsingInvalidAmount() {
    Transfer transfer = TransferTestModel
      .startTransferFromPrivateAccount()
      .toForeignBankAccount()
      .asSoonAsPossible()
      .amountGreaterThanAvailableMoney()
      .build();

    Transaction transaction = transferService.transfer(transfer);
    // Assert expected transaction details
  }
}

This code is the result of a strict separation of concerns (SoC). The test method just describes what it wants to test: a transfer from a private account to a foreign bank account, transfer the money as soon as possible, and use an amount which is greater than the available money.

All the transfer details (account numbers, addresses, exact date and amount) are abstracted and hidden in the TransferTestModel class. The TransferTestModel class follows the builder pattern and knows the domain internals and how to parameterize the test data. This builder class represents a test model with rich behavior. I therefore call it a “rich test model“.

Conclusions

Effective tests focus on what to test. Technical details and data interdependencies should be abstracted and hidden in a rich test model based on the domain under test. The resulting rich test model builds a (test-driven) DSL and is therefore an ideal discussion basis for developers, testers, and domain experts.

The separation of concerns (rich test model and test scenario) allows to successfully manage data interdependencies and to minimize the maintenance effort.

Outlook

In future articles I will show the details of the TransferTestModel class, enrich the model in order to support more sophisticated tests, and emphasize the importance of the ubiquitous language in the rich test model.