Subject (Truth 0.41)

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.

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

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
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)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithActual(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).
`protected void`	`fail(String verb, Object... messageParts)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithActual(Fact, Fact...)`. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
`protected void`	`fail(String verb, Object other)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithActual(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).
`protected void`	`failComparing(String message, CharSequence expected, CharSequence actual)` Deprecated. Instead of manually testing whether the actual value is equal to the expected and then calling this method, ask Truth to do both with a statement like `check("foo()").that(actual().foo()).isEqualTo(expectedFoo)`. (If you are comparing the values using a method other than `Object.equals(java.lang.Object)`, you'll have to wrap your actual and expected values in a custom object that implements your desired logic in `equals` and forwards the `toString` method.)
`protected void`	`failComparing(String message, CharSequence expected, CharSequence actual, Throwable cause)` Deprecated. See the other overload of this method for instructions on how to get Truth to throw a `ComparisonFailure`. To make Truth also attach the `Throwable cause` to the assertion failure, see the instructions on `failWithRawMessageAndCause(java.lang.String, java.lang.Throwable)`.
`protected 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.
`protected void`	`failWithActual(String key, Object value)` Fails, reporting a message with two "facts": key: value but was: actual value.
`protected void`	`failWithBadResults(String verb, Object expected, String failVerb, Object actual)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithActual(Fact, Fact...)`. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
`protected void`	`failWithCustomSubject(String verb, Object expected, Object actual)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithoutActual(Fact, Fact...)`. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
`protected void`	`failWithoutActual(Fact first, Fact... rest)` Fails, reporting a message with the given facts, without automatically adding the actual value.
`protected void`	`failWithoutActual(String check)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithoutActual(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).
`protected void`	`failWithoutSubject(String check)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithoutActual(simpleFact(...))`. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
`protected void`	`failWithRawMessage(String message, Object... parameters)` Deprecated. Prefer to construct `Fact`-style methods, typically by using `failWithActual(Fact, Fact...)`. However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
`protected void`	`failWithRawMessageAndCause(String message, Throwable cause)` Deprecated. Pass the message to `failWithRawMessage(java.lang.String, java.lang.Object...)`, but also, to make Truth attach the `Throwable cause` to the assertion failure, ensure that `cause` appears in the assertion chain. This should typically already be the case, as in `assertThat(throwable).hasMessageThat().isEqualTo("message")`. If it is not, you will need to introduce an extra `check` call into your chain, something like `check().about(unexpectedFailures()).that(cause).wasASuccess(message)`, with `unexpectedFailures()` returning a factory for a "dummy" subject type that defines only a `wasASuccess` method that fails unconditionally.
`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 unexpected)` Fails if the subject is the same instance as the given object.
`void`	`isNull()` Fails if the subject is not null.
`void`	`isSameAs(Object expected)` 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,
                  @NullableDecl
                  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 using Strings.lenientFormat. Note this only supports the %s specifier.
    
    Parameters:
    
    format - a template with %s placeholders
    
    args - the object parameters which will be applied to the message template.
  - 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(@NullableDecl
                      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(@NullableDecl
                         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(@NullableDecl @CompatibleWith(value="T")
                     Object expected)
```
    Fails if the subject is not the same instance as the given object.
  - isNotSameAs
```
public void isNotSameAs(@NullableDecl @CompatibleWith(value="T")
                        Object unexpected)
```
    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(@NullableDecl @CompatibleWith(value="T")
                    Object first,
                    @NullableDecl @CompatibleWith(value="T")
                    Object second,
                    @NullableDecl
                    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(@NullableDecl @CompatibleWith(value="T")
                     Object first,
                     @NullableDecl @CompatibleWith(value="T")
                     Object second,
                     @NullableDecl
                     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, assertThat(caught).hasCauseThat().hasMessageThat() will produce a failure message that includes the string "throwable.getCause().getMessage()," thanks to internal 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 check("onlyColor()").
    
    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 ...).
  - failWithActual
```
protected final void failWithActual(String key,
                                    @NullableDecl
                                    Object value)
```
    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) calls failWithActual("expected to contain", string).
  - failWithActual
```
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.
    If you have only one fact to report (and it's a key-value fact), prefer the simpler overload.
    Example usage: The check isEmpty() calls failWithActual(simpleFact("expected to be empty")).
  - fail
```
@Deprecated
protected final void fail(String check)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithActual(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
protected final void fail(String verb,
                                      Object other)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithActual(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 asserted
    
    other - the value against which the subject is compared
  - fail
```
@Deprecated
protected final void fail(String verb,
                                      Object... messageParts)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithActual(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 asserted
    
    messageParts - the expectations against which the subject is compared
  - failWithBadResults
```
@Deprecated
protected final void failWithBadResults(String verb,
                                                    Object expected,
                                                    String failVerb,
                                                    Object actual)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithActual(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 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
```
@Deprecated
protected final void failWithCustomSubject(String verb,
                                                       Object expected,
                                                       Object actual)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithoutActual(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 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. Prefer to construct Fact-style methods, typically by using failWithoutActual(simpleFact(...)). However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
  - failWithoutActual
```
protected final void failWithoutActual(Fact first,
                                       Fact... rest)
```
    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 failWithAcutal instead. However, failWithoutActual is useful in some cases:
    - when the actual value is obvious from the rest of the message. For example, isNotEmpty() calls failWithoutActual(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(...) calls failWithoutActual so that it can put the expected and actual values together, followed by the tolerance.
    Example usage: The check isEmpty() calls failWithActual(simpleFact("expected to be empty")).
  - failWithoutActual
```
@Deprecated
protected final void failWithoutActual(String check)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithoutActual(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
  - failWithRawMessage
```
@Deprecated
protected void failWithRawMessage(String message,
                                              Object... parameters)
```
    Deprecated. Prefer to construct Fact-style methods, typically by using failWithActual(Fact, Fact...). However, if you want to preserve your exact failure message as a migration aid, you can inline this method.
    
    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 - a template with %s placeholders
    
    parameters - the object parameters which will be applied to the message template.
  - failWithRawMessageAndCause
```
@Deprecated
protected final void failWithRawMessageAndCause(String message,
                                                            Throwable cause)
```
    Deprecated. Pass the message to failWithRawMessage(java.lang.String, java.lang.Object...), but also, to make Truth attach the Throwable cause to the assertion failure, ensure that cause appears in the assertion chain. This should typically already be the case, as in assertThat(throwable).hasMessageThat().isEqualTo("message"). If it is not, you will need to introduce an extra check call into your chain, something like check().about(unexpectedFailures()).that(cause).wasASuccess(message), with unexpectedFailures() returning a factory for a "dummy" subject type that defines only a wasASuccess method that fails unconditionally.
    
    Passes through a failure message verbatim, along with a cause.
  - failComparing
```
@Deprecated
protected final void failComparing(String message,
                                               CharSequence expected,
                                               CharSequence actual)
```
    Deprecated. Instead of manually testing whether the actual value is equal to the expected and then calling this method, ask Truth to do both with a statement like check("foo()").that(actual().foo()).isEqualTo(expectedFoo). (If you are comparing the values using a method other than Object.equals(java.lang.Object), you'll have to wrap your actual and expected values in a custom object that implements your desired logic in equals and forwards the toString method.)
    
    Passes through a failure message verbatim, along with the expected and actual values that the FailureStrategy may use to construct a ComparisonFailure.
  - failComparing
```
@Deprecated
protected final void failComparing(String message,
                                               CharSequence expected,
                                               CharSequence actual,
                                               Throwable cause)
```
    Deprecated. See the other overload of this method for instructions on how to get Truth to throw a ComparisonFailure. To make Truth also attach the Throwable cause to the assertion failure, see the instructions on failWithRawMessageAndCause(java.lang.String, java.lang.Throwable).
    
    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(@NullableDecl
                                        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

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

For people extending Truth

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Subject

Method Detail

internalCustomName

named

isNull

isNotNull

isEqualTo

isNotEqualTo

isSameAs

isNotSameAs

isInstanceOf

isNotInstanceOf

isIn

isAnyOf

isNotIn

isNoneOf

getSubject

actual

actualAsString

actualCustomStringRepresentation

check

check

ignoreCheck

failWithActual

failWithActual

fail

fail

fail

failWithBadResults

failWithCustomSubject

failWithoutSubject

failWithoutActual

failWithoutActual

failWithRawMessage

failWithRawMessageAndCause

failComparing

failComparing

equals

hashCode

toString