org.meanbean.test.EqualsMethodTester Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of meanbean Show documentation
Mean Bean is an open source Java test library that tests equals and hashCode contract compliance, as well as JavaBean/POJO getter and setter methods.
There is a newer version: 2.0.3
Show newest version
package org.meanbean.test;

import org.meanbean.bean.info.BeanInformationException;
import org.meanbean.factories.FactoryCollectionProvider;
import org.meanbean.lang.Factory;

/**
 * 
 * Defines a means of testing the correctness of the equals logic implemented by a 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
 * 
 * 
 * @author Graham Williamson
 */
public interface EqualsMethodTester extends FactoryCollectionProvider {

	/** Default number of times a type should be tested. */
	static final int TEST_ITERATIONS_PER_TYPE = 100;

	/**
	 * 
	 * 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.
	 * 
	 * 
	 * @param factory
	 *            A Factory 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.
	 * @param 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.
	 * @throws BeanInformationException
	 *             If a problem occurs when trying to obtain information about the type to test.
	 * @throws BeanTestException
	 *             If a problem occurs when testing the type, such as an inability to read or write a property of the
	 *             type to test.
	 * @throws AssertionError
	 *             If the test fails.
	 */
	void testEqualsMethod(Factory 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.
	 * 
	 * 
	 * @param factory
	 *            A Factory 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.
	 * @param 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.
	 * @param 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.
	 * @throws BeanInformationException
	 *             If a problem occurs when trying to obtain information about the type to test.
	 * @throws BeanTestException
	 *             If a problem occurs when testing the type, such as an inability to read or write a property of the
	 *             type to test.
	 * @throws AssertionError
	 *             If the test fails.
	 */
	void testEqualsMethod(Factory factory, Configuration customConfiguration, String... insignificantProperties)
	        throws IllegalArgumentException, AssertionError;
}