On my latest Java project, my colleagues and I are keen to improve the readability of test classes. We’ve chosen to use Mockito and Hamcrest because of their natural language approach to mocking and assertions, but on their own they can’t always convey the meaning of values used in a test.

To overcome this, we use a pattern which I’ll call the “Domain Test Values Class”,  the purpose of which is to provide values used in the testing of a domain in a way which improves understanding of test code by increasing readability and adding meaning to values.

Natural language in tests

Mockito and Hamcrest greatly improve test readability by allowing you write tests like this:

AccountService accountService = mock(AccountService.class);
given(accountService.getBalance(1234567)).willReturn(100.0);

double remainingBalance = accountController.withdraw(1234567, 100.0);

assertThat(remainingBalance, is(0.0));
verify(accountService, never()).markOverdrawn();

So in these few lines we can see what’s mocked, that the remaining balance should be 0.0 and that markOverdrawn() should never be called.

Removing the magic numbers

We’re still lacking some clarity because of those magic numbers and it’s always good practice to replace them with constants:

final long accountNumber = 1234567L;
final double startingBalance = 100.0;
final double withdrawalAmount = startingBalance;

AccountService accountService = mock(AccountService.class);
given(accountService.getBalance(accountNumber)).willReturn(startingBalance);

double remainingBalance = accountController.withdraw(accountNumber, withdrawalAmount);

assertThat(remainingBalance, is(0.0));
verify(accountService, never()).markOverdrawn();

Now it’s more obvious from the code what the numbers mean, but it’s still not ideal, we don’t know if it matters that the account number is 1234567. Or if the starting balance has to be 100. Are we right to assume that 0.0 means that the account is empty?

Adding meaning

With a little renaming the test not only becomes more readable, but it starts showing more intent:

final long anAccountNumber = 1234567L;
final double aCreditBalance = 100.0;
final double aZeroBalace = 0.0;

AccountService accountService = mock(AccountService.class);
given(accountService.getBalance(anAccountNumber)).willReturn(aCreditBalance);

double remainingBalance = accountController.withdraw(anAccountNumber, aCreditBalance);

assertThat(remainingBalance, is(aZeroBalance));
verify(accountService, never()).markOverdrawn();

Now simply by choosing some good names the test is very easily understood, so let’s apply this more generally:

The domain test values class

It’s not hard to see that some of the values in the example above will be required in other tests in the account domain, so instead of putting them at the top of the method or as constants in just one test, let’s statically import them and create an AccountDomainTestValues class:

public class AccountDomainTestValues {
    /**A constant test value*/
    public static final long AN_ACCOUNT_NUMBER = anyAccountNumber();
    /**A constant test value*/
    public static final double A_CREDIT = anyCredit();
    /**A simple constant*/
    public static final double ZERO_BALANCE = 0.0;
    /**A generated value*/
    public static final long anyAccountNumber() {
        //randomly generate an account number
    }

    /**A generated value*/
    public static final long anyCredit() {
        //randomly generate a credit value
    }
}

As well as constants, the class also provides methods for generating values. Notice the naming convention – constants are prefixed with “a” or “an” while methods generating values use “any” – this adds intent to the value:

• “any”: the actual value is not important to the test
• “a”: the value is fixed and so should be considered important and can be used more than once to mean the same thing during a test

For example:

import static com.manbuildswebsite.AccountDomainTestValues.*;
...

accountService.deposit(AN_ACCOUNT_NUMBER, anyCredit());

assertThat(accountService.isOverdrawn(AN_ACCOUNT_NUMBER), is(false));

Using the “any” methods to populate the constant fields exercises a larger range of values than would otherwise be the case; programmers tend to stick to numbers like 1 or 123, and while randomly generating numbers is not a substitute for testing edge cases, it does ensure a range of real-life values are tested.

We’ve found that by using the domain test values class pattern we’ve improved the readability, and so the understanding and maintainability, of our test code for very little effort.

Disclaimer…

This pattern, or something like it, may well have been catalogued somewhere already, though if it has I’m yet to find it, so I present it here in the hope that it either helps others or that someone will point me to a published version of it!

© 2010 Dave Bower/Man Builds Website