Package com.google.common.testing
Class ClassSanityTester
- java.lang.Object
-
- com.google.common.testing.ClassSanityTester
-
@Beta @GwtIncompatible public final class ClassSanityTester extends Object
Tester that runs automated sanity tests for any given class. A typical use case is to test static factory classes like:interface Book {...} public class Books { public static Book hardcover(String title) {...} public static Book paperback(String title) {...} }
And all the created
Book
instances can be tested with:new ClassSanityTester() .forAllPublicStaticMethods(Books.class) .thatReturn(Book.class) .testEquals(); // or testNulls(), testSerializable() etc.
- Since:
- 14.0
- Author:
- Ben Yu
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
ClassSanityTester.FactoryMethodReturnValueTester
Runs sanity tests against return values of static factory methods declared by a class.
-
Constructor Summary
Constructors Constructor Description ClassSanityTester()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ClassSanityTester.FactoryMethodReturnValueTester
forAllPublicStaticMethods(Class<?> cls)
Returns an object responsible for performing sanity tests against the return values of all public static methods declared bycls
, excluding superclasses.<T> ClassSanityTester
setDefault(Class<T> type, T value)
Sets the default value fortype
.<T> ClassSanityTester
setDistinctValues(Class<T> type, T value1, T value2)
Sets distinct values fortype
, so that when a classFoo
is tested forObject.equals(java.lang.Object)
andObject.hashCode()
, and its construction requires a parameter oftype
, the distinct values oftype
can be passed as parameters to createFoo
instances that are unequal.void
testEquals(Class<?> cls)
void
testNulls(Class<?> cls)
Tests thatcls
properly checks null on all constructor and method parameters that aren't annotated nullable (according to the rules ofNullPointerTester
).
-
-
-
Constructor Detail
-
ClassSanityTester
public ClassSanityTester()
-
-
Method Detail
-
setDefault
public <T> ClassSanityTester setDefault(Class<T> type, T value)
Sets the default value fortype
. The default value isn't used in testingObject.equals(java.lang.Object)
because more than one sample instances are needed for testing inequality. To set distinct values for equality testing, usesetDistinctValues(java.lang.Class<T>, T, T)
instead.
-
setDistinctValues
public <T> ClassSanityTester setDistinctValues(Class<T> type, T value1, T value2)
Sets distinct values fortype
, so that when a classFoo
is tested forObject.equals(java.lang.Object)
andObject.hashCode()
, and its construction requires a parameter oftype
, the distinct values oftype
can be passed as parameters to createFoo
instances that are unequal.Calling
setDistinctValues(type, v1, v2)
also sets the default value fortype
that's used fortestNulls(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 thatcls
properly checks null on all constructor and method parameters that aren't annotated nullable (according to the rules ofNullPointerTester
). In details:- All non-private static methods are checked such that passing null for any parameter
that's not annotated 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
orcls
's subtype.
- All non-private static methods are checked such that passing null for any parameter
that's not annotated nullable should throw
-
testEquals
public void testEquals(Class<?> cls)
Tests theObject.equals(java.lang.Object)
andObject.hashCode()
ofcls
. 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
orcls
's subtype. - Inequality check is not performed against state mutation methods such as
List.add(E)
, or functional update methods such asJoiner.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 bycls
, excluding superclasses.
-
-