Test Data Are Documentation

If, as a developer, you have embraced the idea that tests are a good way of documenting the behaviour of your application, then you will agree that any mock/stub/test data used in those tests must be examples of what the real data crunched by your application look like.

I've seen too many Doc's, Grumpy's and Dopey's, too many Disney characters, too many planets, too many Muppets, too much Sesame Street, too many Foo's and Bar's.

They don't provide any useful information.

Suppose you have a CustomerContactRecord class in your system:

import lombok.Builder;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.NonNull;

@Data
@Builder
@EqualsAndHashCode
public class CustomerContactRecord {
    @NonNull
    private String lastName;

    @NonNull
    private String zipCode;

    private String phoneNumber;
}

The zipCode field contains a US zip code and the phoneNumber field contains a US phone domestic phone number.

Suppose you have your CustomerContactRecordValidator class whose responsibility is to verify that all required fields in a customer contact record are present:

public interface CustomerContactRecordValidator {
    void ensureRequiredFieldsArePresent(CustomerContactRecord customerContactRecord) 
            throws MissingRequiredFieldsException;
}

When you build the data for your test, you want to make sure that they have the right semantics, so avoid the following:

public class CustomerContactRecordValidatorTest {


    private static final Set<CustomerContactRecord> VALID_CUSTOMERS = ImmutableSet.of(
            CustomerContactRecord.builder()
                    .lastName("Dopey")
                    .zipCode("123XYZ")
                    .phoneNumber("Elmo")
                    .build(),

            CustomerContactRecord.builder()
                    .lastName("Sneezy")
                    .zipCode("someZipCode")
                    .build()
    );

...
}

...and prefer something along the lines of:

public class CustomerContactRecordValidatorTest {

    private static final Set<CustomerContactRecord> VALID_CUSTOMERS = ImmutableSet.of(
            CustomerContactRecord.builder()
                    .lastName("Smith")
                    .zipCode("95616-6625")
                    .phoneNumber("(541) 754-3010")
                    .build(),

            CustomerContactRecord.builder()
                    .lastName("Smith")
                    .zipCode("95616-6625")
                    .build()
    );
...
}

It will kill some joy in your tests, but it will make everyone's life easier :)

Note

You can enforce the right format for your fields by using the @Pattern annotation in JSR 380 and leveraging the Java Bean Validation mechanism:

@Data
@Builder
@EqualsAndHashCode
public class CustomerContactRecord {
    @NotNull
    private String lastName;

    @NotNull
    @Pattern(regexp = "^[0-9]{5}(?:-[0-9]{4})?$", message = "Invalid zip code")
    private String zipCode;

    @Pattern(regexp = "^\\(?([0-9]{3})\\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$", message = "Invalid phone number")
    private String phoneNumber;
}