001/* 002 * Copyright (C) 2011 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.Beta; 024import com.google.common.annotations.GwtCompatible; 025import com.google.common.base.Equivalence; 026import com.google.common.collect.ImmutableList; 027import com.google.common.collect.Lists; 028import com.google.common.testing.RelationshipTester.ItemReporter; 029import java.util.List; 030 031/** 032 * Tester for {@link Equivalence} relationships between groups of objects. 033 * 034 * <p>To use, create a new {@link EquivalenceTester} and add equivalence groups where each group 035 * contains objects that are supposed to be equal to each other. Objects of different groups are 036 * expected to be unequal. For example: 037 * 038 * <pre>{@code 039 * EquivalenceTester.of(someStringEquivalence) 040 * .addEquivalenceGroup("hello", "h" + "ello") 041 * .addEquivalenceGroup("world", "wor" + "ld") 042 * .test(); 043 * }</pre> 044 * 045 * <p>Note that testing {@link Object#equals(Object)} is more simply done using the {@link 046 * EqualsTester}. It includes an extra test against an instance of an arbitrary class without having 047 * to explicitly add another equivalence group. 048 * 049 * @author Gregory Kick 050 * @since 10.0 051 */ 052@Beta 053@GwtCompatible 054public final class EquivalenceTester<T> { 055 private static final int REPETITIONS = 3; 056 057 private final Equivalence<? super T> equivalence; 058 private final RelationshipTester<T> delegate; 059 private final List<T> items = Lists.newArrayList(); 060 061 private EquivalenceTester(Equivalence<? super T> equivalence) { 062 this.equivalence = checkNotNull(equivalence); 063 this.delegate = 064 new RelationshipTester<T>(equivalence, "equivalent", "hash", new ItemReporter()); 065 } 066 067 public static <T> EquivalenceTester<T> of(Equivalence<? super T> equivalence) { 068 return new EquivalenceTester<T>(equivalence); 069 } 070 071 /** 072 * Adds a group of objects that are supposed to be equivalent to each other and not equivalent to 073 * objects in any other equivalence group added to this tester. 074 */ 075 public EquivalenceTester<T> addEquivalenceGroup(T first, T... rest) { 076 addEquivalenceGroup(Lists.asList(first, rest)); 077 return this; 078 } 079 080 public EquivalenceTester<T> addEquivalenceGroup(Iterable<T> group) { 081 delegate.addRelatedGroup(group); 082 items.addAll(ImmutableList.copyOf(group)); 083 return this; 084 } 085 086 /** Run tests on equivalence methods, throwing a failure on an invalid test */ 087 public EquivalenceTester<T> test() { 088 for (int run = 0; run < REPETITIONS; run++) { 089 testItems(); 090 delegate.test(); 091 } 092 return this; 093 } 094 095 private void testItems() { 096 for (T item : items) { 097 /* 098 * TODO(cpovirk): consider no longer running these equivalent() tests on every Equivalence, 099 * since the Equivalence base type now implements this logic itself 100 */ 101 assertTrue(item + " must be inequivalent to null", !equivalence.equivalent(item, null)); 102 assertTrue("null must be inequivalent to " + item, !equivalence.equivalent(null, item)); 103 assertTrue(item + " must be equivalent to itself", equivalence.equivalent(item, item)); 104 assertEquals( 105 "the hash of " + item + " must be consistent", 106 equivalence.hash(item), 107 equivalence.hash(item)); 108 } 109 } 110}