Package com.google.common.testing

Class AbstractPackageSanityTests

java.lang.Object

junit.framework.Assert

junit.framework.TestCase

com.google.common.testing.AbstractPackageSanityTests

All Implemented Interfaces:

junit.framework.Test

@Beta
@GwtIncompatible
public abstract class AbstractPackageSanityTests
extends junit.framework.TestCase

Automatically runs sanity checks against top level classes in the same package of the test that extends AbstractPackageSanityTests. Currently sanity checks include NullPointerTester, EqualsTester and SerializableTester. For example:

 public class PackageSanityTests extends AbstractPackageSanityTests {}
 

Note that only top-level classes with either a non-private constructor or a non-private static factory method to construct instances can have their instance methods checked. For example:

 public class Address {
   private final String city;
   private final String state;
   private final String zipcode;

   public Address(String city, String state, String zipcode) {...}

   @Override public boolean equals(Object obj) {...}
   @Override public int hashCode() {...}
   ...
 }
 

No cascading checks are performed against the return values of methods unless the method is a static factory method. Neither are semantics of mutation methods such as someList.add(obj) checked. For more detailed discussion of supported and unsupported cases, see testEquals(), testNulls() and testSerializable().

For testing against the returned instances from a static factory class, such as

 interface Book {...}
 public class Books {
   public static Book hardcover(String title) {...}
   public static Book paperback(String title) {...}
 }
 

please use ClassSanityTester.forAllPublicStaticMethods(java.lang.Class<?>).

If not all classes on the classpath should be covered, ignoreClasses(com.google.common.base.Predicate<? super java.lang.Class<?>>) can be used to exclude certain classes. As a special case, classes with an underscore in the name (like AutoValue_Foo) can be excluded using ignoreClasses(UNDERSCORE_IN_NAME).

setDefault(java.lang.Class<T>, T) allows subclasses to specify default values for types.

This class incurs IO because it scans the classpath and reads classpath resources.

Since:

14.0

Field Summary

Fields

Modifier and Type	Field	Description
static Predicate<java.lang.Class<?>>	UNDERSCORE_IN_NAME	A predicate that matches classes with an underscore in the class name.

Constructor Summary

Constructors

Constructor	Description
AbstractPackageSanityTests()

Method Summary

Modifier and Type	Method	Description
protected void	ignoreClasses(Predicate<? super java.lang.Class<?>> condition)	Specifies that classes that satisfy the given predicate aren't tested for sanity.
protected void	publicApiOnly()	Restricts the sanity tests for public API only.
protected <T> void	setDefault(java.lang.Class<T> type, T value)	Sets the default value for type, when dummy value for a parameter of the same type needs to be created in order to invoke a method or constructor.
protected <T> void	setDistinctValues(java.lang.Class<T> type, T value1, T value2)	Sets two distinct values for type.
void	testEquals()	Tests equals() and hashCode() implementations for every top-level class in the package, that explicitly implements Object.equals(java.lang.Object).
void	testNulls()	Performs NullPointerTester checks for all top-level classes in the package.
void	testSerializable()	Tests all top-level Serializable classes in the package.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from class junit.framework.TestCase

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, countTestCases, createResult, fail, fail, failNotEquals, failNotSame, failSame, format, getName, run, run, runBare, runTest, setName, setUp, tearDown, toString

Field Detail

UNDERSCORE_IN_NAME

public static final Predicate<java.lang.Class<?>> UNDERSCORE_IN_NAME

A predicate that matches classes with an underscore in the class name. This can be used with ignoreClasses(com.google.common.base.Predicate<? super java.lang.Class<?>>) to exclude generated classes, such as the AutoValue_Foo classes generated by AutoValue.

Since:

19.0

Constructor Detail

AbstractPackageSanityTests

public AbstractPackageSanityTests()

Method Detail

publicApiOnly

protected final void publicApiOnly()

Restricts the sanity tests for public API only. By default, package-private API are also covered.

testSerializable

public void testSerializable()
                      throws java.lang.Exception

Tests all top-level Serializable classes in the package. For a serializable Class C:

• If C explicitly implements Object.equals(java.lang.Object), the deserialized instance will be checked to be equal to the instance before serialization.
• If C doesn't explicitly implement equals but instead inherits it from a superclass, no equality check is done on the deserialized instance because it's not clear whether the author intended for the class to be a value type.
• If a constructor or factory method takes a parameter whose type is interface, a dynamic proxy will be passed to the method. It's possible that the method body expects an instance method of the passed-in proxy to be of a certain value yet the proxy isn't aware of the assumption, in which case the equality check before and after serialization will fail.
• If the constructor or factory method takes a parameter that AbstractPackageSanityTests doesn't know how to construct, the test will fail.
• If there is no visible constructor or visible static factory method declared by C, C is skipped for serialization test, even if it implements Serializable.
• Serialization test is not performed on method return values unless the method is a visible static factory method whose return type is C or C's subtype.

In all cases, if C needs custom logic for testing serialization, you can add an explicit testSerializable() test in the corresponding CTest class, and C will be excluded from automated serialization test performed by this method.

Throws:

java.lang.Exception

testNulls

public void testNulls()
               throws java.lang.Exception

Performs NullPointerTester checks for all top-level classes in the package. For a class C

• All visible static methods are checked such that passing null for any parameter that's not annotated with Nullable should throw NullPointerException.
• If there is any visible constructor or visible static factory method declared by the class, all visible instance methods will be checked too using the instance created by invoking the constructor or static factory method.
• If the constructor or factory method used to construct instance takes a parameter that AbstractPackageSanityTests doesn't know how to construct, the test will fail.
• If there is no visible constructor or visible static factory method declared by C, instance methods are skipped for nulls test.
• Nulls test is not performed on method return values unless the method is a visible static factory method whose return type is C or C's subtype.

In all cases, if C needs custom logic for testing nulls, you can add an explicit testNulls() test in the corresponding CTest class, and C will be excluded from the automated null tests performed by this method.

Throws:

java.lang.Exception

testEquals

public void testEquals()
                throws java.lang.Exception

Tests equals() and hashCode() implementations for every top-level class in the package, that explicitly implements Object.equals(java.lang.Object). For a class C:

• The visible constructor or visible 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.
• Inequality check is not performed against state mutation methods such as List.add(E), or functional update methods such as Joiner.skipNulls().
• If the constructor or factory method used to construct instance takes a parameter that AbstractPackageSanityTests doesn't know how to construct, the test will fail.
• If there is no visible constructor or visible static factory method declared by C, C is skipped for equality test.
• Equality test is not performed on method return values unless the method is a visible static factory method whose return type is C or C's subtype.

In all cases, if C needs custom logic for testing equals(), you can add an explicit testEquals() test in the corresponding CTest class, and C will be excluded from the automated equals test performed by this method.

Throws:

java.lang.Exception

setDefault

protected final <T> void setDefault(java.lang.Class<T> type,
                                    T value)

Sets the default value for type, when dummy value for a parameter of the same type needs to be created in order to invoke a method or constructor. The default value isn't used in testing Object.equals(java.lang.Object) because more than one sample instances are needed for testing inequality.

setDistinctValues

protected final <T> void setDistinctValues(java.lang.Class<T> type,
                                           T value1,
                                           T value2)

Sets two distinct values for type. These values can be used for both null pointer testing and equals testing.

Since:

17.0

ignoreClasses

protected final void ignoreClasses(Predicate<? super java.lang.Class<?>> condition)

Specifies that classes that satisfy the given predicate aren't tested for sanity.