001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.testing;
018
019import static com.google.common.base.Preconditions.checkNotNull;
020import static junit.framework.Assert.assertEquals;
021import static junit.framework.Assert.assertTrue;
022
023import com.google.common.annotations.GwtCompatible;
024import com.google.common.base.Equivalence;
025import com.google.common.collect.ImmutableList;
026import com.google.common.collect.Iterables;
027import com.google.common.collect.Lists;
028import java.util.List;
029
030/**
031 * Tester for equals() and hashCode() methods of a class.
032 *
033 * <p>The simplest use case is:
034 *
035 * <pre>
036 * new EqualsTester().addEqualityGroup(foo).testEquals();
037 * </pre>
038 *
039 * <p>This tests {@code foo.equals(foo)}, {@code foo.equals(null)}, and a few other operations.
040 *
041 * <p>For more extensive testing, add multiple equality groups. Each group should contain objects
042 * that are equal to each other but unequal to the objects in any other group. For example:
043 *
044 * <pre>
045 * new EqualsTester()
046 *     .addEqualityGroup(new User("page"), new User("page"))
047 *     .addEqualityGroup(new User("sergey"))
048 *     .testEquals();
049 * </pre>
050 *
051 * <p>This tests:
052 *
053 * <ul>
054 *   <li>comparing each object against itself returns true
055 *   <li>comparing each object against null returns false
056 *   <li>comparing each object against an instance of an incompatible class returns false
057 *   <li>comparing each pair of objects within the same equality group returns true
058 *   <li>comparing each pair of objects from different equality groups returns false
059 *   <li>the hash codes of any two equal objects are equal
060 * </ul>
061 *
062 * <p>When a test fails, the error message labels the objects involved in the failed comparison as
063 * follows:
064 *
065 * <ul>
066 *   <li>"{@code [group }<i>i</i>{@code , item }<i>j</i>{@code ]}" refers to the
067 *       <i>j</i><sup>th</sup> item in the <i>i</i><sup>th</sup> equality group, where both equality
068 *       groups and the items within equality groups are numbered starting from 1. When either a
069 *       constructor argument or an equal object is provided, that becomes group 1.
070 * </ul>
071 *
072 * @author Jim McMaster
073 * @author Jige Yu
074 * @since 10.0
075 */
076@GwtCompatible
077public final class EqualsTester {
078  private static final int REPETITIONS = 3;
079
080  private final List<List<Object>> equalityGroups = Lists.newArrayList();
081  private final RelationshipTester.ItemReporter itemReporter;
082
083  /** Constructs an empty EqualsTester instance */
084  public EqualsTester() {
085    this(new RelationshipTester.ItemReporter());
086  }
087
088  EqualsTester(RelationshipTester.ItemReporter itemReporter) {
089    this.itemReporter = checkNotNull(itemReporter);
090  }
091
092  /**
093   * Adds {@code equalityGroup} with objects that are supposed to be equal to each other and not
094   * equal to any other equality groups added to this tester.
095   */
096  public EqualsTester addEqualityGroup(Object... equalityGroup) {
097    checkNotNull(equalityGroup);
098    equalityGroups.add(ImmutableList.copyOf(equalityGroup));
099    return this;
100  }
101
102  /** Run tests on equals method, throwing a failure on an invalid test */
103  public EqualsTester testEquals() {
104    RelationshipTester<Object> delegate =
105        new RelationshipTester<>(
106            Equivalence.equals(), "Object#equals", "Object#hashCode", itemReporter);
107    for (List<Object> group : equalityGroups) {
108      delegate.addRelatedGroup(group);
109    }
110    for (int run = 0; run < REPETITIONS; run++) {
111      testItems();
112      delegate.test();
113    }
114    return this;
115  }
116
117  private void testItems() {
118    for (Object item : Iterables.concat(equalityGroups)) {
119      assertTrue(item + " must not be Object#equals to null", !item.equals(null));
120      assertTrue(
121          item + " must not be Object#equals to an arbitrary object of another class",
122          !item.equals(NotAnInstance.EQUAL_TO_NOTHING));
123      assertTrue(item + " must be Object#equals to itself", item.equals(item));
124      assertEquals(
125          "the Object#hashCode of " + item + " must be consistent",
126          item.hashCode(),
127          item.hashCode());
128      if (!(item instanceof String)) {
129        assertTrue(
130            item + " must not be Object#equals to its Object#toString representation",
131            !item.equals(item.toString()));
132      }
133    }
134  }
135
136  /**
137   * Class used to test whether equals() correctly handles an instance of an incompatible class.
138   * Since it is a private inner class, the invoker can never pass in an instance to the tester
139   */
140  private enum NotAnInstance {
141    EQUAL_TO_NOTHING;
142  }
143}