Class Subject
- Direct Known Subclasses:
AbstractArraySubject
,BooleanSubject
,ClassSubject
,ComparableSubject
,GuavaOptionalSubject
,IntStreamSubject
,IterableSubject
,LongStreamSubject
,MapSubject
,MultimapSubject
,OptionalDoubleSubject
,OptionalIntSubject
,OptionalLongSubject
,OptionalSubject
,PathSubject
,StreamSubject
,TableSubject
,ThrowableSubject
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
The result of comparing two objects for equality.(package private) static enum
static interface
Subject.Factory<SubjectT extends Subject,
ActualT> -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final Object
private String
private static final char[]
private static final char[]
private static final FailureStrategy
private final FailureMetadata
private final String
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Subject
(FailureMetadata metadata, Object actual) Constructor for use by subclasses.(package private)
Subject
(FailureMetadata metadata, Object actual, String typeDescriptionOverride) Special constructor that lets subclasses provide a description of the type they're testing. -
Method Summary
Modifier and TypeMethodDescription(package private) final Object
actual()
Returns the actual value under test.protected String
Supplies the direct string representation of the actual value to other methods which may prefix or otherwise position it in an error message.(package private) final String
private static String
private static char[]
asUnicodeHexEscape
(char c) private static String
base16
(byte[] bytes) (package private) final Fact
butWas()
Returns a "but was:" string. (package private) final StandardSubjectBuilder
check()
Deprecated.Use the other overload, which requires you to supply more information to include in any failure messages.protected final StandardSubjectBuilder
Returns a builder for creating a derived subject.private static Subject.ComparisonResult
checkArrayEqualsRecursive
(Object expectedArray, Object actualArray, String lastIndex) Returns null if the arrays are equal, recursively.private static Subject.ComparisonResult
checkByteArrayEquals
(byte[] expected, byte[] actual) Returns null if the arrays are equal.(package private) final StandardSubjectBuilder
checkNoNeedToDisplayBothValues
(String format, Object... args) private static boolean
private Subject.ComparisonResult
compareForEquality
(Object expected) Returns whetheractual
equalsexpected
differ and, in some cases, a description of how they differ.private StandardSubjectBuilder
doCheck
(FailureMetadata.OldAndNewValuesAreSimilar valuesAreSimilar, String format, Object[] args) private void
doubleArrayAsString
(double[] items) final boolean
Deprecated.Object.equals(Object)
is not supported on Truth subjects.private static String
escapeWhitespace
(char c) private static String
(package private) final void
Deprecated.(package private) final void
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual(String, Object)
.(package private) final void
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual(Fact, Fact...)
.private void
failEqualityCheck
(Subject.EqualityCheck equalityCheck, Object expected, Subject.ComparisonResult difference) (package private) final void
Special version offailEqualityCheck(com.google.common.truth.Subject.EqualityCheck, java.lang.Object, com.google.common.truth.Subject.ComparisonResult)
for use fromIterableSubject
, documented further there.private void
failEqualityCheckNoComparisonFailure
(Subject.ComparisonResult difference, Fact... facts) protected final void
failWithActual
(Fact first, Fact... rest) Fails, reporting a message with the given facts, followed by an automatically added fact of the form: but was: actual value.(package private) final void
failWithActual
(Facts facts) (package private) final void
failWithActual
(Iterable<Fact> facts) protected final void
failWithActual
(String key, Object value) Fails, reporting a message with two "facts": key: value but was: actual value.(package private) final void
failWithBadResults
(String verb, Object expected, String failVerb, Object actual) Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual(Fact, Fact...)
.(package private) final void
failWithCustomSubject
(String verb, Object expected, Object actual) Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithoutActual(Fact, Fact...)
.protected final void
failWithoutActual
(Fact first, Fact... rest) Fails, reporting a message with the given facts, without automatically adding the actual value.(package private) final void
failWithoutActual
(Facts facts) (package private) final void
failWithoutActual
(Iterable<Fact> facts) (package private) final void
failWithoutActual
(String check) Deprecated.(package private) final void
failWithoutSubject
(String check) Deprecated.floatArrayAsString
(float[] items) private String
private static boolean
gwtSafeObjectEquals
(Object actual, Object expected) final int
hashCode()
Deprecated.Object.hashCode()
is not supported on Truth subjects.protected final StandardSubjectBuilder
Begins a new call chain that ignores any failures.private static long
void
Fails unless the subject is equal to any of the given elements.void
Fails if the subject is not equal to the given object.void
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.private static boolean
void
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
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
Fails if the subject is null.final void
isNotSameInstanceAs
(Object unexpected) Fails if the subject is the same instance as the given object.void
isNull()
Fails if the subject is not null.final void
isSameInstanceAs
(Object expected) Fails if the subject is not the same instance as the given object.private com.google.common.collect.ImmutableList
<Fact> private com.google.common.collect.ImmutableList
<Fact> prependNameIfAny
(com.google.common.collect.ImmutableList<Fact> facts) private void
standardIsEqualTo
(Object expected) private void
standardIsNotEqualTo
(Object unexpected) private static Iterable
<?> stringableIterable
(Object[] array) toString()
private boolean
tryFailForEmptyString
(Object expected) Checks whether the actual and expected values are empty strings.private boolean
tryFailForTrailingWhitespaceOnly
(Object expected) Checks whether the actual and expected values are strings that match except for trailing whitespace.(package private) final String
private static String
typeDescriptionOrGuess
(Class<? extends Subject> clazz, String typeDescriptionOverride)
-
Field Details
-
IGNORE_STRATEGY
-
metadata
-
actual
-
customName
-
typeDescriptionOverride
-
hexDigits
private static final char[] hexDigits -
STRINGIFY
-
HEX_DIGITS
private static final char[] HEX_DIGITS
-
-
Constructor Details
-
Subject
Constructor for use by subclasses. If you want to create an instance of this class itself, callcheck(...)
.that(actual)
. -
Subject
Subject(FailureMetadata metadata, Object actual, String typeDescriptionOverride) Special constructor that lets subclasses provide a description of the type they're testing. For example,ThrowableSubject
passes the description "throwable." Normally, Truth is able to infer this name from the class name. However, if we lack runtime type information (notably, under j2cl with class metadata off), we might not have access to the original class name.We don't expect to make this a public API: Class names are nearly always available. It's just that we want to be able to run Truth's own tests run with class metadata off, and it's easier to tweak the subjects to know their own names rather than generalize the tests to accept obfuscated names.
-
-
Method Details
-
isNull
public void isNull()Fails if the subject is not null. -
isNotNull
public void isNotNull()Fails if the subject is null. -
isEqualTo
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
, orLong
) and they are numerically equal when converted toLong
. - the actual value is a boxed floating-point type (
Double
orFloat
), the expected value is anInteger
, and the two are numerically equal when converted toDouble
. (This allowsassertThat(someDouble).isEqualTo(0)
to pass.)
Note: This method does not test the
Object.equals(java.lang.Object)
implementation itself; it assumes that method is functioning correctly according to its contract. Testing anequals
implementation requires a utility such as guava-testlib's EqualsTester.In some cases, this method might not even call
equals
. It may instead perform other tests that will return the same result as long asequals
is implemented according to the contract for its type. - they are equal according to
-
standardIsEqualTo
-
isNotEqualTo
Fails if the subject is equal to the given object. The meaning of equality is the same as for theisEqualTo(java.lang.Object)
method. -
standardIsNotEqualTo
-
compareForEquality
Returns whetheractual
equalsexpected
differ and, in some cases, a description of how they differ.The equality check follows the rules described on
isEqualTo(java.lang.Object)
. -
isIntegralBoxedPrimitive
-
integralValue
-
isSameInstanceAs
Fails if the subject is not the same instance as the given object. -
isNotSameInstanceAs
Fails if the subject is the same instance as the given object. -
isInstanceOf
Fails if the subject is not an instance of the given class. -
isNotInstanceOf
Fails if the subject is an instance of the given class. -
isIn
Fails unless the subject is equal to any element in the given iterable. -
isAnyOf
Fails unless the subject is equal to any of the given elements. -
isNotIn
Fails if the subject is equal to any element in the given iterable. -
isNoneOf
Fails if the subject is equal to any of the given elements. -
actual
Returns the actual value under test. -
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())
. -
actualCustomStringRepresentationForPackageMembersToCall
-
formatActualOrExpected
-
base16
-
stringableIterable
-
checkByteArrayEquals
Returns null if the arrays are equal. If not equal, returns a string comparing the two arrays, displaying them in the style "[1, 2, 3]" to supplement the main failure message, which uses the style "010203." -
checkArrayEqualsRecursive
private static Subject.ComparisonResult checkArrayEqualsRecursive(Object expectedArray, Object actualArray, String lastIndex) Returns null if the arrays are equal, recursively. If not equal, returns the string of the index at which they're different. -
arrayType
-
gwtSafeObjectEquals
-
doubleArrayAsString
-
floatArrayAsString
-
check
Deprecated.Use the other overload, which requires you to supply more information to include in any failure messages.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
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 aStringSubject
, is implemented withcheck("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,assertThat(caught).hasCauseThat().hasMessageThat()
will produce a failure message that includes the string "throwable.getCause().getMessage()," thanks to internalcheck
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)
callscheck("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 callcheck("onlyColor()")
.- Parameters:
format
- a template with%s
placeholdersargs
- the arguments to be inserted into those placeholders
-
checkNoNeedToDisplayBothValues
-
doCheck
private StandardSubjectBuilder doCheck(FailureMetadata.OldAndNewValuesAreSimilar valuesAreSimilar, String format, Object[] args) -
ignoreCheck
Begins a new call chain that ignores any failures. This is useful for subjects that normally delegate with to other subjects by usingcheck()
but have already reported a failure. In such cases it may still be necessary to return aSubject
instance even though any subsequent assertions are meaningless. For example, if a user chains together moreThrowableSubject.hasCauseThat()
calls than the actual exception has causes,hasCauseThat
returnsignoreCheck().that(... a dummy exception ...)
. -
failWithActual
Fails, reporting a message with two "facts":- key: value
- but was: actual value.
This is the simplest failure API. For more advanced needs, see the other overload and
failWithoutActual
.Example usage: The check
contains(String)
callsfailWithActual("expected to contain", string)
. -
failWithActual
Fails, reporting a message with the given facts, followed by an automatically added fact of the form:- but was: actual value.
If you have only one fact to report (and it's a key-value fact), prefer the simpler overload.
Example usage: The check
isEmpty()
callsfailWithActual(simpleFact("expected to be empty"))
. -
failWithActual
-
failWithActual
-
fail
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual
(
simpleFact(...)
)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method (and then inline the resulting method call, as well).Reports a failure constructing a message from a simple verb.- Parameters:
check
- the check being asserted
-
fail
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual(String, Object)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method (and then inline the resulting method call, as well).Assembles a failure message and passes such to the FailureStrategy- Parameters:
verb
- the check being assertedother
- the value against which the subject is compared
-
fail
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual(Fact, Fact...)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.Assembles a failure message and passes such to the FailureStrategy- Parameters:
verb
- the check being assertedmessageParts
- the expectations against which the subject is compared
-
failEqualityCheckForEqualsWithoutDescription
Special version offailEqualityCheck(com.google.common.truth.Subject.EqualityCheck, java.lang.Object, com.google.common.truth.Subject.ComparisonResult)
for use fromIterableSubject
, documented further there. -
failEqualityCheck
private void failEqualityCheck(Subject.EqualityCheck equalityCheck, Object expected, Subject.ComparisonResult difference) -
tryFailForTrailingWhitespaceOnly
Checks whether the actual and expected values are strings that match except for trailing whitespace. If so, reports a failure and returns true. -
escapeWhitespace
-
escapeWhitespace
-
tryFailForEmptyString
Checks whether the actual and expected values are empty strings. If so, reports a failure and returns true. -
asUnicodeHexEscape
private static char[] asUnicodeHexEscape(char c) -
failEqualityCheckNoComparisonFailure
private void failEqualityCheckNoComparisonFailure(Subject.ComparisonResult difference, Fact... facts) -
failWithBadResults
@Deprecated final void failWithBadResults(String verb, Object expected, String failVerb, Object actual) Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithActual(Fact, Fact...)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.Assembles a failure message and passes it to the FailureStrategy- Parameters:
verb
- the check being assertedexpected
- the expectations against which the subject is comparedfailVerb
- the failure of the check being assertedactual
- the actual value the subject was compared against
-
failWithCustomSubject
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithoutActual(Fact, Fact...)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.Assembles a failure message with an alternative representation of the wrapped subject and passes it to the FailureStrategy- Parameters:
verb
- the check being assertedexpected
- the expected value of the checkactual
- the custom representation of the subject to be reported in the failure.
-
failWithoutSubject
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithoutActual
(
simpleFact(...)
)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method. -
failWithoutActual
Fails, reporting a message with the given facts, without automatically adding the actual value.Most failure messages should report the actual value, so most checks should call
failWithActual
instead. However,failWithoutActual
is useful in some cases:- when the actual value is obvious from the rest of the message. For example,
isNotEmpty()
callsfailWithoutActual(simpleFact("expected not to be empty")
. - when the actual value shouldn't come last or should have a different key than the default
of "but was." For example,
isNotWithin(...).of(...)
callsfailWithoutActual
so that it can put the expected and actual values together, followed by the tolerance.
Example usage: The check
isEmpty()
callsfailWithActual(simpleFact("expected to be empty"))
. - when the actual value is obvious from the rest of the message. For example,
-
failWithoutActual
-
failWithoutActual
-
failWithoutActual
Deprecated.Prefer to constructFact
-style methods, typically by usingfailWithoutActual
(
simpleFact(...)
)
. However, if you want to preserve your exact failure message as a migration aid, you can inline this method (and then inline the resulting method call, as well).Assembles a failure message without a given subject and passes it to the FailureStrategy- Parameters:
check
- the check being asserted
-
equals
Deprecated.Object.equals(Object)
is not supported on Truth subjects. If you meant to test object equality between an expected and the actual value, useisEqualTo(Object)
instead.- Overrides:
equals
in classObject
- Throws:
UnsupportedOperationException
- always
-
hashCode
Deprecated.Object.hashCode()
is not supported on Truth subjects.- Overrides:
hashCode
in classObject
- Throws:
UnsupportedOperationException
- always
-
toString
-
butWas
Returns a "but was:" string. This method should be rarely needed, since Truth inserts a "but was" fact by default for assertions. However, it's occasionally useful for calls to failWithoutActual
that want a "but was" fact but don't want it to come last, where Truth inserts it by default. -
typeDescription
-
typeDescriptionOrGuess
-
classMetadataUnsupported
private static boolean classMetadataUnsupported() -
doFail
-
prependNameIfAny
-
nameAsFacts
-