org.meanbean.test

Class EqualsMethodTester

java.lang.Object

org.meanbean.test.EqualsMethodTester

public class EqualsMethodTester
extends Object

Provides a means of testing the correctness of the equals logic implemented by a type, based solely on the type, with respect to:

• the general equals contract
• the programmer's expectation of property significance in object equality

The following is tested:

• the reflexive item of the equals contract - x.equals(x) should hold
• the symmetric item of the equals contract - if x.equals(y), then y.equals(x) should also hold
• the transitive item of the equals contract - if x.equals(y) and y.equals(z), then x.equals(z) should hold
• the consistent item of the equals contract - if x.equals(y), then x.equals(y) should hold (remain consistent) across multiple invocations, so long as neither object changes
• the null item of the equals contract - a non-null object should not be deemed equal to another null object
• that an entirely different type of object is not deemed equal to an object created by the specified factory.
• that the equality of an object is not affected by properties that are not considered in the equality logic
• that the equality of an object is affected by properties that are considered in the equality logic

To test the equals logic implemented by a class called MyClass do the following:

 EqualsMethodTester tester = new EqualsMethodTester();
 tester.testEqualsMethod(MyClass.class);
 

In the above example all properties are assumed to be considered by MyClass's equals logic.

The following example tests the equals logic implemented by a class called MyComplexClass which has two properties: firstName and lastName. Only firstName is considered in the equals logic. Therefore, lastName is specified in the insignificantProperties varargs:

 EqualsMethodTester tester = new EqualsMethodTester();
 tester.testEqualsMethod(MyComplexClass.class, "lastName");
 

In order for the above to work successfully, the class under test must have a no-argument constructor. If this is not the case, you must provide an EquivalentFactory implementation:

 EqualsMethodTester tester = new EqualsMethodTester();
 tester.testEqualsMethod(new EquivalentFactory<MyClass>() {
        @Override
        public MyClass create() {
                MyClass result = new MyClass();
                // initialize result...
                result.setName("TEST_NAME");
                return result;
        }
 });
 

The Factory creates new logically equivalent instances of MyClass. MyClass has overridden equals() and hashCode(). In the above example, there is only one property, name, which is considered by MyClass's equals logic.

The following example tests the equals logic implemented by a class called MyComplexClass which has two properties: firstName and lastName, but lacks a no-argument constructor. Only firstName is considered in the equals logic. Therefore, lastName is specified in the insignificantProperties varargs:

 EqualsMethodTester tester = new EqualsMethodTester();
 tester.testEqualsMethod(new EquivalentFactory<MyComplexClass>() {
        @Override
        public MyComplexClass create() {
                MyComplexClass result = new MyComplexClass("TEST_FIRST_NAME", "TEST_LAST_NAME");
                return result;
        }
 }, "lastName");
 

Author:

Graham Williamson

Constructor Summary

Constructors

Constructor and Description
EqualsMethodTester() Prefer BeanVerifier

Method Summary

Modifier and Type	Method and Description
void	testEqualsMethod(Class<?> clazz, Configuration customConfiguration, String... insignificantProperties) Test that the equals logic implemented by the type specified is correct by testing:
void	testEqualsMethod(Class<?> clazz, String... insignificantProperties) Test that the equals logic implemented by the type specified is correct by testing:
void	testEqualsMethod(EquivalentFactory<?> factory, Configuration customConfiguration, String... insignificantProperties) Test that the equals logic implemented by the type the specified factory creates is correct by testing:
void	testEqualsMethod(EquivalentFactory<?> factory, String... insignificantProperties) Test that the equals logic implemented by the type the specified factory creates is correct by testing:

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EqualsMethodTester

public EqualsMethodTester()

Prefer BeanVerifier

Method Detail

testEqualsMethod

public void testEqualsMethod(Class<?> clazz,
                             String... insignificantProperties)
                      throws IllegalArgumentException,
                             BeanInformationException,
                             BeanTestException,
                             AssertionError

Test that the equals logic implemented by the type specified is correct by testing:

• the reflexive item of the equals contract - x.equals(x) should hold
• the symmetric item of the equals contract - if x.equals(y), then y.equals(x) should also hold
• the transitive item of the equals contract - if x.equals(y) and y.equals(z), then x.equals(z) should hold
• the consistent item of the equals contract - if x.equals(y), then x.equals(y) should hold (remain consistent) across multiple invocations, so long as neither object changes
• the null item of the equals contract - a non-null object should not be deemed equal to another null object
• that an entirely different type of object is not deemed equal to an object of the specified type
• that the equality of an object is not affected by properties that are not considered in the equality logic
• that the equality of an object is affected by properties that are considered in the equality logic

If the test fails, an AssertionError is thrown.

Parameters:

clazz - The type to test the equals logic of.

insignificantProperties - The names of properties that are not used when deciding whether objects are logically equivalent. For example, "lastName".

Throws:

IllegalArgumentException - If either the specified clazz or insignificantProperties are deemed illegal. For example, if either is null. Also, if any of the specified insignificantProperties do not exist on the class under test.

BeanInformationException - If a problem occurs when trying to obtain information about the type to test.

BeanTestException - If a problem occurs when testing the type, such as an inability to read or write a property of the type to test.

AssertionError - If the test fails.

testEqualsMethod

public void testEqualsMethod(Class<?> clazz,
                             Configuration customConfiguration,
                             String... insignificantProperties)
                      throws IllegalArgumentException,
                             BeanInformationException,
                             BeanTestException,
                             AssertionError

Test that the equals logic implemented by the type specified is correct by testing:

• the reflexive item of the equals contract - x.equals(x) should hold
• the symmetric item of the equals contract - if x.equals(y), then y.equals(x) should also hold
• the transitive item of the equals contract - if x.equals(y) and y.equals(z), then x.equals(z) should hold
• the consistent item of the equals contract - if x.equals(y), then x.equals(y) should hold (remain consistent) across multiple invocations, so long as neither object changes
• the null item of the equals contract - a non-null object should not be deemed equal to another null object
• that an entirely different type of object is not deemed equal to an object of the specified type
• that the equality of an object is not affected by properties that are not considered in the equality logic
• that the equality of an object is affected by properties that are considered in the equality logic

If the test fails, an AssertionError is thrown.

Parameters:

clazz - The type to test the equals logic of.

customConfiguration - A custom Configuration to be used when testing to ignore the testing of named properties or use a custom test data Factory when testing a named property. This Configuration is only used for this individual test and will not be retained for future testing of this or any other type. If no custom Configuration is required, pass null or use testEqualsMethod(Class<?>,String...) instead.

insignificantProperties - The names of properties that are not used when deciding whether objects are logically equivalent. For example, "lastName".

Throws:

IllegalArgumentException - If either the specified clazz or insignificantProperties are deemed illegal. For example, if either is null. Also, if any of the specified insignificantProperties do not exist on the class under test.

BeanInformationException - If a problem occurs when trying to obtain information about the type to test.

BeanTestException - If a problem occurs when testing the type, such as an inability to read or write a property of the type to test.

AssertionError - If the test fails.

testEqualsMethod

public void testEqualsMethod(EquivalentFactory<?> factory,
                             String... insignificantProperties)
                      throws IllegalArgumentException,
                             BeanInformationException,
                             BeanTestException,
                             AssertionError

Test that the equals logic implemented by the type the specified factory creates is correct by testing:

• the reflexive item of the equals contract - x.equals(x) should hold
• the symmetric item of the equals contract - if x.equals(y), then y.equals(x) should also hold
• the transitive item of the equals contract - if x.equals(y) and y.equals(z), then x.equals(z) should hold
• the consistent item of the equals contract - if x.equals(y), then x.equals(y) should hold (remain consistent) across multiple invocations, so long as neither object changes
• the null item of the equals contract - a non-null object should not be deemed equal to another null object
• that an entirely different type of object is not deemed equal to an object created by the specified factory.
• that the equality of an object is not affected by properties that are not considered in the equality logic
• that the equality of an object is affected by properties that are considered in the equality logic

If the test fails, an AssertionError is thrown.

Parameters:

factory - An EquivalentFactory that creates non-null logically equivalent objects that will be used to test whether the equals logic implemented by the type is correct. The factory must create logically equivalent but different actual instances of the type upon each invocation of create() in order for the test to be meaningful and correct.

insignificantProperties - The names of properties that are not used when deciding whether objects are logically equivalent. For example, "lastName".

Throws:

IllegalArgumentException - If either the specified factory or insignificantProperties are deemed illegal. For example, if either is null. Also, if any of the specified insignificantProperties do not exist on the class under test.

BeanInformationException - If a problem occurs when trying to obtain information about the type to test.

BeanTestException - If a problem occurs when testing the type, such as an inability to read or write a property of the type to test.

AssertionError - If the test fails.

testEqualsMethod

public void testEqualsMethod(EquivalentFactory<?> factory,
                             Configuration customConfiguration,
                             String... insignificantProperties)
                      throws IllegalArgumentException,
                             BeanInformationException,
                             BeanTestException,
                             AssertionError

Test that the equals logic implemented by the type the specified factory creates is correct by testing:

• the reflexive item of the equals contract - x.equals(x) should hold
• the symmetric item of the equals contract - if x.equals(y), then y.equals(x) should also hold
• the transitive item of the equals contract - if x.equals(y) and y.equals(z), then x.equals(z) should hold
• the consistent item of the equals contract - if x.equals(y), then x.equals(y) should hold (remain consistent) across multiple invocations, so long as neither object changes
• the null item of the equals contract - a non-null object should not be deemed equal to another null object
• that an entirely different type of object is not deemed equal to an object created by the specified factory.
• that the equality of an object is not affected by properties that are not considered in the equality logic
• that the equality of an object is affected by properties that are considered in the equality logic

If the test fails, an AssertionError is thrown.

Parameters:

factory - An EquivalentFactory that creates non-null logically equivalent objects that will be used to test whether the equals logic implemented by the type is correct. The factory must create logically equivalent but different actual instances of the type upon each invocation of create() in order for the test to be meaningful and correct.

customConfiguration - A custom Configuration to be used when testing to ignore the testing of named properties or use a custom test data Factory when testing a named property. This Configuration is only used for this individual test and will not be retained for future testing of this or any other type. If no custom Configuration is required, pass null or use testEqualsMethod(Factory<?>,String...) instead.

insignificantProperties - The names of properties that are not used when deciding whether objects are logically equivalent. For example, "lastName".

Throws:

IllegalArgumentException - If either the specified factory or insignificantProperties are deemed illegal. For example, if either is null. Also, if any of the specified insignificantProperties do not exist on the class under test.

BeanInformationException - If a problem occurs when trying to obtain information about the type to test.

BeanTestException - If a problem occurs when testing the type, such as an inability to read or write a property of the type to test.

AssertionError - If the test fails.