1 User Guide

It depends on the Grails Spock plugin which in turn depends on Spock 0.5-groovy-1.7 version.

1.1 How to use the plugin

class DomainObject {
    String includedSampleProperty
    String ignoredSampleProperty
    SecondLevelDomainObject child
    boolean equals(o) {
        if (o == null) return false
        if (this.is(o)) return true
        if (!(o instanceof DomainObject)) return false
        DomainObject that = (DomainObject) o
        new EqualsBuilder()
            .append(includedProperty, that.includedProperty)
            .append(child, that.child)
            .isEquals()
    }
    int hashCode() {
        new HashCodeBuilder()
            .append(includedProperty)
            .append(child)
            .toHashCode()
    }
}
class SecondLevelDomainObject {
    String sampleProperty
    boolean equals(o) { // … }
    int hashCode() { // … }
}

We should test both equals and hashCode methods if they:

• fulfill equals and hashCode contracts as specified in api:java.lang.Object Javadoc (see below)
• use some properties in equals/hashCode
• ignore some properties (i.e. if their value change, and the remaining properties stay unchanged, equals and hashCode should return the same value as before change)

To keep your code DRY, extend EqualsHashCodeSpec (which in turn extends UnitSpec) and:

• override the factory method createDomainObjectToCompare that spawns a new object under test
• override the method modifiedPropertiesIncludedInEqualsAndHashCode that returns a map of property names used in equals/hashCode and their values changed with respect to the object created by createDomainObjectToCompare
• optionally override the method modifiedPropertiesIgnoredInEqualsAndHashCode for properties NOT used in equals/hashCode
• you may use closures as property values for lazy evaluation (as for child property value in the example below)

Example for our sample DomainObject:

class ChildFactory {
    static newExtremelyComplexSecondLevelDomainObject() {
        new SecondLevelDomainObject(sampleProperty: 'a value')
    }
}
class DomainObjectSpec extends EqualsHashCodeSpec {
    def createDomainObjectToCompare() {
        new DomainObject(includedSampleProperty: 'foo', ignoredSampleProperty: 'bar',
            child: ChildFactory.newExtremelyComplexSecondLevelDomainObject())
    }
    def modifiedPropertiesIncludedInEqualsAndHashCode() {
        [includedSampleProperty: 'foo changed', , child: {
            def child = ChildFactory.newExtremelyComplexSecondLevelDomainObject()
            child.sampleProperty = 'a different value'
            child
        }]
    }
    def modifiedPropertiesIgnoredInEqualsAndHashCode() {
        [ignoredSampleProperty: 'bar changed']
    }
}

1.2 How the plugin works

Tests with changed properties used in equals/hashCode verify that two objects are not equal. They don't check if hashCode values of different objects are the same (although a good implementation of hashCode should return distinct values for unequal objects).

Tests with properties ignored in equals/hashCode verify that two objects are equal and hash codes are the same (although a property value is different in two objects).

1.3 equals and hashCode contracts

• It is reflexive : for any non-null reference value x, x.equals(x) should return true.
• It is symmetric : for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive : for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.

It is consistent : for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified. For any non-null reference value x, x.equals(null) should return false.

hashCode should be always implemented when equals is overriden and:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)