Constructor Detail

• ClassSanityTester

  public ClassSanityTester()

Method Detail

• setDefault

  public <T> ClassSanityTester setDefault(Class<T> type,
                                 T value)

  Sets the default value for type. The default value isn't used in testing Object.equals(java.lang.Object) because more than one sample instances are needed for testing inequality. To set distinct values for equality testing, use setDistinctValues(java.lang.Class<T>, T, T) instead.

• setSampleInstances

  @Deprecated
  public <T> ClassSanityTester setSampleInstances(Class<T> type,
                                                    Iterable<? extends T> instances)

  Deprecated. To supply multiple values, use setDistinctValues(java.lang.Class<T>, T, T). It accepts only two values, which is enough for any equals testing. To supply a single value, use setDefault(java.lang.Class<T>, T). This method will be removed in Guava release 20.0.
  Sets sample instances for type, so that when a class Foo is tested for Object.equals(java.lang.Object) and Object.hashCode(), and its construction requires a parameter of type, the sample instances can be passed to create Foo instances that are unequal.

  Used for types where ClassSanityTester doesn't already know how to instantiate distinct values. It's usually necessary to add two unequal instances for each type, with the exception that if the sample instance is to be passed to a Nullable parameter, one non-null sample is sufficient. Setting an empty list will clear sample instances for type.

• setDistinctValues

  public <T> ClassSanityTester setDistinctValues(Class<T> type,
                                        T value1,
                                        T value2)

  Sets distinct values for type, so that when a class Foo is tested for Object.equals(java.lang.Object) and Object.hashCode(), and its construction requires a parameter of type, the distinct values of type can be passed as parameters to create Foo instances that are unequal.

  Calling setDistinctValues(type, v1, v2) also sets the default value for type that's used for testNulls(java.lang.Class<?>).

  Only necessary for types where ClassSanityTester doesn't already know how to create distinct values.

  Returns:

  this tester instance

  Since:

  17.0

• testNulls

  public void testNulls(Class<?> cls)

  Tests that cls properly checks null on all constructor and method parameters that aren't annotated with Nullable. In details:

  • All non-private static methods are checked such that passing null for any parameter that's not annotated with Nullable should throw NullPointerException.
  • If there is any non-private constructor or non-private static factory method declared by cls, all non-private instance methods will be checked too using the instance created by invoking the constructor or static factory method.
  • If there is any non-private constructor or non-private static factory method declared by cls:
    • Test will fail if default value for a parameter cannot be determined.
    • Test will fail if the factory method returns null so testing instance methods is impossible.
    • Test will fail if the constructor or factory method throws exception.
  • If there is no non-private constructor or non-private static factory method declared by cls, instance methods are skipped for nulls test.
  • Nulls test is not performed on method return values unless the method is a non-private static factory method whose return type is cls or cls's subtype.

• testEquals

  public void testEquals(Class<?> cls)

  Tests the Object.equals(java.lang.Object) and Object.hashCode() of cls. In details:

  • The non-private constructor or non-private static factory method with the most parameters is used to construct the sample instances. In case of tie, the candidate constructors or factories are tried one after another until one can be used to construct sample instances.
  • For the constructor or static factory method used to construct instances, it's checked that when equal parameters are passed, the result instance should also be equal; and vice versa.
  • If a non-private constructor or non-private static factory method exists:
    • Test will fail if default value for a parameter cannot be determined.
    • Test will fail if the factory method returns null so testing instance methods is impossible.
    • Test will fail if the constructor or factory method throws exception.
  • If there is no non-private constructor or non-private static factory method declared by cls, no test is performed.
  • Equality test is not performed on method return values unless the method is a non-private static factory method whose return type is cls or cls's subtype.
  • Inequality check is not performed against state mutation methods such as List.add(E), or functional update methods such as Joiner.skipNulls().

  Note that constructors taking a builder object cannot be tested effectively because semantics of builder can be arbitrarily complex. Still, a factory class can be created in the test to facilitate equality testing. For example:

   public class FooTest {
  
     private static class FooFactoryForTest {
       public static Foo create(String a, String b, int c, boolean d) {
         return Foo.builder()
             .setA(a)
             .setB(b)
             .setC(c)
             .setD(d)
             .build();
       }
     }
  
     public void testEquals() {
       new ClassSanityTester()
         .forAllPublicStaticMethods(FooFactoryForTest.class)
         .thatReturn(Foo.class)
         .testEquals();
     }
   }
   

  It will test that Foo objects created by the create(a, b, c, d) factory method with equal parameters are equal and vice versa, thus indirectly tests the builder equality.

• forAllPublicStaticMethods

  public ClassSanityTester.FactoryMethodReturnValueTester forAllPublicStaticMethods(Class<?> cls)

  Returns an object responsible for performing sanity tests against the return values of all public static methods declared by cls, excluding superclasses.