com.google.common.truth

Class Subject<S extends Subject<S,T>,T>

java.lang.Object

com.google.common.truth.Subject<S,T>

Type Parameters:

S - the self-type, allowing this-returning methods to avoid needing subclassing

T - the type of the object being tested by this Subject

Direct Known Subclasses:

AtomicLongMapSubject, BooleanSubject, ClassSubject, ComparableSubject, DefaultSubject, GuavaOptionalSubject, IntStreamSubject, IterableOfProtosSubject, IterableSubject, LiteProtoSubject, LongStreamSubject, MapSubject, MapWithProtoValuesSubject, MultimapSubject, MultimapWithProtoValuesSubject, ObjectArraySubject, OptionalDoubleSubject, OptionalIntSubject, OptionalLongSubject, OptionalSubject, PathSubject, PrimitiveBooleanArraySubject, PrimitiveByteArraySubject, PrimitiveCharArraySubject, PrimitiveDoubleArraySubject, PrimitiveFloatArraySubject, PrimitiveIntArraySubject, PrimitiveLongArraySubject, PrimitiveShortArraySubject, Re2jSubjects.Re2jStringSubject, StreamSubject, TableSubject, ThrowableSubject

public class Subject<S extends Subject<S,T>,T>
extends Object

An object that lets you perform checks on the value under test. For example, Subject contains isEqualTo(Object) and isInstanceOf(Class), and StringSubject contains startsWith(String).

To create a Subject instance, most users will call an assertThat method. For information about other ways to create an instance, see this FAQ entry.

For people extending Truth

For information about writing a custom Subject, see our doc on extensions.

Author:

David Saff, Christian Gruber

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Subject.Factory<SubjectT extends Subject<SubjectT,ActualT>,ActualT> In a fluent assertion chain, the argument to the common overload of about, the method that specifies what kind of Subject to create.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Subject(FailureMetadata metadata, T actual) Constructor for use by subclasses.

Method Summary

Modifier and Type	Method and Description
protected T	actual() Returns the unedited, unformatted raw actual value.
protected String	actualAsString() Returns a string representation of the actual value.
protected String	actualCustomStringRepresentation() Supplies the direct string representation of the actual value to other methods which may prefix or otherwise position it in an error message.
protected StandardSubjectBuilder	check() Returns a builder for creating a derived subject but without providing information about how the derived subject will relate to the current subject.
protected StandardSubjectBuilder	check(String format, Object... args) Returns a builder for creating a derived subject.
boolean	equals(Object o) Deprecated. Object.equals(Object) is not supported on Truth subjects. If you meant to test object equality between an expected and the actual value, use isEqualTo(Object) instead.
protected void	fail(String check) Reports a failure constructing a message from a simple verb.
protected void	fail(String verb, Object... messageParts) Assembles a failure message and passes such to the FailureStrategy
protected void	fail(String verb, Object other) Assembles a failure message and passes such to the FailureStrategy
protected void	failComparing(String message, CharSequence expected, CharSequence actual) Passes through a failure message verbatim, along with the expected and actual values that the FailureStrategy may use to construct a ComparisonFailure.
protected void	failComparing(String message, CharSequence expected, CharSequence actual, Throwable cause) Passes through a failure message verbatim, along with a cause and the expected and actual values that the FailureStrategy may use to construct a ComparisonFailure.
protected void	failWithBadResults(String verb, Object expected, String failVerb, Object actual) Assembles a failure message and passes it to the FailureStrategy
protected void	failWithCustomSubject(String verb, Object expected, Object actual) Assembles a failure message with an alternative representation of the wrapped subject and passes it to the FailureStrategy
protected void	failWithoutActual(String check) Assembles a failure message without a given subject and passes it to the FailureStrategy
protected void	failWithoutSubject(String check) Deprecated. Use failWithoutActual(String)
protected void	failWithRawMessage(String message, Object... parameters) Passes through a failure message verbatim.
protected void	failWithRawMessageAndCause(String message, Throwable cause) Passes through a failure message verbatim, along with a cause.
protected T	getSubject() Deprecated. Prefer #actual() for direct access to the subject.
int	hashCode() Deprecated. Object.hashCode() is not supported on Truth subjects.
protected StandardSubjectBuilder	ignoreCheck() Begins a new call chain that ignores any failures.
protected String	internalCustomName() An internal method used to obtain the value set by named(String, Object...).
void	isAnyOf(Object first, Object second, Object... rest) Fails unless the subject is equal to any of the given elements.
void	isEqualTo(Object expected) Fails if the subject is not equal to the given object.
void	isIn(Iterable<?> iterable) Fails unless the subject is equal to any element in the given iterable.
void	isInstanceOf(Class<?> clazz) Fails if the subject is not an instance of the given class.
void	isNoneOf(Object first, Object second, Object... rest) Fails if the subject is equal to any of the given elements.
void	isNotEqualTo(Object unexpected) Fails if the subject is equal to the given object.
void	isNotIn(Iterable<?> iterable) Fails if the subject is equal to any element in the given iterable.
void	isNotInstanceOf(Class<?> clazz) Fails if the subject is an instance of the given class.
void	isNotNull() Fails if the subject is null.
void	isNotSameAs(Object other) Fails if the subject is the same instance as the given object.
void	isNull() Fails if the subject is not null.
void	isSameAs(Object other) Fails if the subject is not the same instance as the given object.
S	named(String format, Object... args) Adds a prefix to the subject, when it is displayed in error messages.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Subject

protected Subject(FailureMetadata metadata,
                  @Nullable
                  T actual)

Constructor for use by subclasses. If you want to create an instance of this class itself, call check().that(actual).

Method Detail

internalCustomName

protected String internalCustomName()

An internal method used to obtain the value set by named(String, Object...).

named

@CanIgnoreReturnValue
public S named(String format,
                                     Object... args)

Adds a prefix to the subject, when it is displayed in error messages. This is especially useful in the context of types that have no helpful toString() representation, e.g. boolean. Writing assertThat(foo).named("foo").isTrue(); then results in a more reasonable error message.

named() takes a format template and argument objects which will be substituted into the template, similar to String.format(String, Object...), the chief difference being that extra parameters (for which there are no template variables) will be appended to the resulting string in brackets. Additionally, this only supports the %s template variable type.

isNull

public void isNull()

Fails if the subject is not null.

isNotNull

public void isNotNull()

Fails if the subject is null.

isEqualTo

public void isEqualTo(@Nullable
                      Object expected)

Fails if the subject is not equal to the given object. For the purposes of this comparison, two objects are equal if any of the following is true:

• they are equal according to Objects.equal(java.lang.Object, java.lang.Object)
• they are arrays and are considered equal by the appropriate Arrays.equals(long[], long[]) overload
• they are boxed integer types (Byte, Short, Character, Integer, or Long) and they are numerically equal when converted to Long.

isNotEqualTo

public void isNotEqualTo(@Nullable
                         Object unexpected)

Fails if the subject is equal to the given object. The meaning of equality is the same as for the isEqualTo(java.lang.Object) method.

isSameAs

public void isSameAs(@Nullable @CompatibleWith(value="T")
                     Object other)

Fails if the subject is not the same instance as the given object.

isNotSameAs

public void isNotSameAs(@Nullable @CompatibleWith(value="T")
                        Object other)

Fails if the subject is the same instance as the given object.

isInstanceOf

public void isInstanceOf(Class<?> clazz)

Fails if the subject is not an instance of the given class.

isNotInstanceOf

public void isNotInstanceOf(Class<?> clazz)

Fails if the subject is an instance of the given class.

isIn

public void isIn(Iterable<?> iterable)

Fails unless the subject is equal to any element in the given iterable.

isAnyOf

public void isAnyOf(@Nullable @CompatibleWith(value="T")
                    Object first,
                    @Nullable @CompatibleWith(value="T")
                    Object second,
                    @Nullable
                    Object... rest)

Fails unless the subject is equal to any of the given elements.

isNotIn

public void isNotIn(Iterable<?> iterable)

Fails if the subject is equal to any element in the given iterable.

isNoneOf

public void isNoneOf(@Nullable @CompatibleWith(value="T")
                     Object first,
                     @Nullable @CompatibleWith(value="T")
                     Object second,
                     @Nullable
                     Object... rest)

Fails if the subject is equal to any of the given elements.

getSubject

@Deprecated
protected T getSubject()

Deprecated. Prefer #actual() for direct access to the subject.

actual

protected final T actual()

Returns the unedited, unformatted raw actual value.

actualAsString

protected final String actualAsString()

Returns a string representation of the actual value. This will either be the toString() of the value or a prefixed "name" along with the string representation.

actualCustomStringRepresentation

@ForOverride
protected String actualCustomStringRepresentation()

Supplies the direct string representation of the actual value to other methods which may prefix or otherwise position it in an error message. This should only be overridden to provide an improved string representation of the value under test, as it would appear in any given error message, and should not be used for additional prefixing.

Subjects should override this with care.

By default, this returns String.ValueOf(getActualValue()).

check

protected final StandardSubjectBuilder check()

Returns a builder for creating a derived subject but without providing information about how the derived subject will relate to the current subject. In most cases, you should provide such information by using the other overload.

check

protected final StandardSubjectBuilder check(String format,
                                             Object... args)

Returns a builder for creating a derived subject.

Derived subjects retain the FailureStrategy and messages of the current subject, and in some cases, they automatically supplement their failure message with information about the original subject.

For example, ThrowableSubject.hasMessageThat(), which returns a StringSubject, is implemented with check("getMessage()").that(actual().getMessage().

The arguments to check describe how the new subject was derived from the old, formatted like a chained method call. This allows Truth to include that information in its failure messages. For example, the assertThat(caught).hasCauseThat().hasMessageThat() will produce a failure message that includes throwable.getCause().getMessage(), thanks to check calls that supplied "getCause()" and "getMessage()" as arguments.

If the method you're delegating to accepts parameters, you can pass check a format string. For example, MultimapSubject.valuesForKey(java.lang.Object) calls check("valuesForKey(%s)", key).

If you aren't really delegating to an instance method on the actual value -- maybe you're calling a static method, or you're calling a chain of several methods -- you can supply whatever string will be most useful to users. For example, if you're delegating to getOnlyElement(actual().colors()), you might call .

Parameters:

format - a template with %s placeholders

args - the arguments to be inserted into those placeholders

ignoreCheck

protected final StandardSubjectBuilder ignoreCheck()

Begins a new call chain that ignores any failures. This is useful for subjects that normally delegate with to other subjects by using check() but have already reported a failure. In such cases it may still be necessary to return a Subject instance even though any subsequent assertions are meaningless. For example, if a user chains together more ThrowableSubject.hasCauseThat() calls than the actual exception has causes, hasCauseThat returns ignoreCheck().that(... a dummy exception ...).

fail

protected final void fail(String check)

Reports a failure constructing a message from a simple verb.

Parameters:

check - the check being asserted

fail

protected final void fail(String verb,
                          Object other)

Assembles a failure message and passes such to the FailureStrategy

Parameters:

verb - the check being asserted

other - the value against which the subject is compared

fail

protected final void fail(String verb,
                          Object... messageParts)

Assembles a failure message and passes such to the FailureStrategy

Parameters:

verb - the check being asserted

messageParts - the expectations against which the subject is compared

failWithBadResults

protected final void failWithBadResults(String verb,
                                        Object expected,
                                        String failVerb,
                                        Object actual)

Assembles a failure message and passes it to the FailureStrategy

Parameters:

verb - the check being asserted

expected - the expectations against which the subject is compared

failVerb - the failure of the check being asserted

actual - the actual value the subject was compared against

failWithCustomSubject

protected final void failWithCustomSubject(String verb,
                                           Object expected,
                                           Object actual)

Assembles a failure message with an alternative representation of the wrapped subject and passes it to the FailureStrategy

Parameters:

verb - the check being asserted

expected - the expected value of the check

actual - the custom representation of the subject to be reported in the failure.

failWithoutSubject

@Deprecated
protected final void failWithoutSubject(String check)

Deprecated. Use failWithoutActual(String)

failWithoutActual

protected final void failWithoutActual(String check)

Assembles a failure message without a given subject and passes it to the FailureStrategy

Parameters:

check - the check being asserted

failWithRawMessage

protected void failWithRawMessage(String message,
                                  Object... parameters)

Passes through a failure message verbatim. Used for Subject subclasses which need to provide alternate language for more fit-to-purpose error messages.

Parameters:

message - the message template to be passed to the failure. Note, this method only guarantees to process %s tokens. It is not guaranteed to be compatible with String.format(). Any other formatting desired (such as floats or scientific notation) should be performed before the method call and the formatted value passed in as a string.

parameters - the object parameters which will be applied to the message template.

failWithRawMessageAndCause

protected final void failWithRawMessageAndCause(String message,
                                                Throwable cause)

Passes through a failure message verbatim, along with a cause.

failComparing

protected final void failComparing(String message,
                                   CharSequence expected,
                                   CharSequence actual)

Passes through a failure message verbatim, along with the expected and actual values that the FailureStrategy may use to construct a ComparisonFailure.

failComparing

protected final void failComparing(String message,
                                   CharSequence expected,
                                   CharSequence actual,
                                   Throwable cause)

Passes through a failure message verbatim, along with a cause and the expected and actual values that the FailureStrategy may use to construct a ComparisonFailure.

equals

@Deprecated
public final boolean equals(@Nullable
                                        Object o)

Deprecated. Object.equals(Object) is not supported on Truth subjects. If you meant to test object equality between an expected and the actual value, use isEqualTo(Object) instead.

Overrides:

equals in class Object

Throws:

UnsupportedOperationException - always

hashCode

@Deprecated
public final int hashCode()

Deprecated. Object.hashCode() is not supported on Truth subjects.

Overrides:

hashCode in class Object

Throws:

UnsupportedOperationException - always

toString

public String toString()

Overrides:

toString in class Object