com.google.common.testing.EqualsTester Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of guava-testlib-jdk5 Show documentation

Guava testlib is a set of java classes used for more convenient unit testing - particularly to assist the tests for Guava itself.

There is a newer version: 17.0

Show newest version

/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.testing;

import static com.google.common.base.Preconditions.checkNotNull;
import static junit.framework.Assert.assertEquals;
import static junit.framework.Assert.assertTrue;

import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import com.google.common.base.Equivalence;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.Iterables;
import com.google.common.collect.Lists;

import java.util.List;

/**
 * Tester for equals() and hashCode() methods of a class.
 *
 * To use, create a new EqualsTester and add equality groups where each group
 * contains objects that are supposed to be equal to each other, and objects of
 * different groups are expected to be unequal. For example:
 * 
 * new EqualsTester()
 *     .addEqualityGroup("hello", "h" + "ello")
 *     .addEqualityGroup("world", "wor" + "ld")
 *     .addEqualityGroup(2, 1 + 1)
 *     .testEquals();
 * 
 * This tests:
 * 

 * comparing each object against itself returns true
 * 
comparing each object against null returns false
 * 
comparing each object against an instance of an incompatible class
 *     returns false
 * 
comparing each pair of objects within the same equality group returns
 *     true
 * 
comparing each pair of objects from different equality groups returns
 *     false
 * 
the hash codes of any two equal objects are equal
 * 
 *
 * When a test fails, the error message labels the objects involved in
 * the failed comparison as follows:
 * 

 *   "{@code [group }i{@code , item }j{@code ]}" refers to the
 *       j^th item in the i^th equality group,
 *       where both equality groups and the items within equality groups are
 *       numbered starting from 1.  When either a constructor argument or an
 *       equal object is provided, that becomes group 1.
 * 
 *
 * @author Jim McMaster
 * @author Jige Yu
 * @since 10.0
 */
@Beta
@GwtCompatible
public final class EqualsTester {
  private static final int REPETITIONS = 3;

  private final List> equalityGroups = Lists.newArrayList();
  private final RelationshipTester.ItemReporter itemReporter;

  /**
   * Constructs an empty EqualsTester instance
   */
  public EqualsTester() {
    this(new RelationshipTester.ItemReporter());
  }

  EqualsTester(RelationshipTester.ItemReporter itemReporter) {
    this.itemReporter = checkNotNull(itemReporter);
  }

  /**
   * Adds {@code equalityGroup} with objects that are supposed to be equal to
   * each other and not equal to any other equality groups added to this tester.
   */
  public EqualsTester addEqualityGroup(Object... equalityGroup) {
    checkNotNull(equalityGroup);
    equalityGroups.add(ImmutableList.copyOf(equalityGroup));
    return this;
  }

  /**
   * Run tests on equals method, throwing a failure on an invalid test
   */
  public EqualsTester testEquals() {
    RelationshipTester