Class Subject

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  Subject.Factory<SubjectT extends Subject,​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 Description
      protected Subject​(FailureMetadata metadata, @Nullable java.lang.Object actual)
      Constructor for use by subclasses.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected java.lang.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​(java.lang.String format, @Nullable java.lang.Object... args)
      Returns a builder for creating a derived subject.
      boolean equals​(@Nullable java.lang.Object o)
      Deprecated.
      Object.equals(Object) is not supported on Truth subjects.
      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​(java.lang.String key, @Nullable java.lang.Object value)
      Fails, reporting a message with two "facts": key: value but was: actual value.
      protected void failWithoutActual​(Fact first, Fact... rest)
      Fails, reporting a message with the given facts, without automatically adding the actual value.
      int hashCode()
      Deprecated.
      Object.hashCode() is not supported on Truth subjects.
      protected StandardSubjectBuilder ignoreCheck()
      Begins a new call chain that ignores any failures.
      void isAnyOf​(@Nullable java.lang.Object first, @Nullable java.lang.Object second, @Nullable java.lang.Object @Nullable ... rest)
      Fails unless the subject is equal to any of the given elements.
      void isEqualTo​(@Nullable java.lang.Object expected)
      Fails if the subject is not equal to the given object.
      void isIn​(@Nullable java.lang.Iterable<?> iterable)
      Fails unless the subject is equal to any element in the given iterable.
      void isInstanceOf​(java.lang.Class<?> clazz)
      Fails if the subject is not an instance of the given class.
      void isNoneOf​(@Nullable java.lang.Object first, @Nullable java.lang.Object second, @Nullable java.lang.Object @Nullable ... rest)
      Fails if the subject is equal to any of the given elements.
      void isNotEqualTo​(@Nullable java.lang.Object unexpected)
      Fails if the subject is equal to the given object.
      void isNotIn​(@Nullable java.lang.Iterable<?> iterable)
      Fails if the subject is equal to any element in the given iterable.
      void isNotInstanceOf​(java.lang.Class<?> clazz)
      Fails if the subject is an instance of the given class.
      void isNotNull()
      Fails if the subject is null.
      void isNotSameInstanceAs​(@Nullable java.lang.Object unexpected)
      Fails if the subject is the same instance as the given object.
      void isNull()
      Fails if the subject is not null.
      void isSameInstanceAs​(@Nullable java.lang.Object expected)
      Fails if the subject is not the same instance as the given object.
      java.lang.String toString()
      Deprecated.
      Object.toString() is not supported on Truth subjects.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • Subject

        protected Subject​(FailureMetadata metadata,
                          @Nullable java.lang.Object actual)
        Constructor for use by subclasses. If you want to create an instance of this class itself, call check(...).that(actual).
    • Method Detail

      • 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 java.lang.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.
        • the actual value is a boxed floating-point type (Double or Float), the expected value is an Integer, and the two are numerically equal when converted to Double. (This allows assertThat(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 an equals 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 as equals is implemented according to the contract for its type.

      • isNotEqualTo

        public void isNotEqualTo​(@Nullable java.lang.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.
      • isSameInstanceAs

        public final void isSameInstanceAs​(@Nullable java.lang.Object expected)
        Fails if the subject is not the same instance as the given object.
      • isNotSameInstanceAs

        public final void isNotSameInstanceAs​(@Nullable java.lang.Object unexpected)
        Fails if the subject is the same instance as the given object.
      • isInstanceOf

        public void isInstanceOf​(java.lang.Class<?> clazz)
        Fails if the subject is not an instance of the given class.
      • isNotInstanceOf

        public void isNotInstanceOf​(java.lang.Class<?> clazz)
        Fails if the subject is an instance of the given class.
      • isIn

        public void isIn​(@Nullable java.lang.Iterable<?> iterable)
        Fails unless the subject is equal to any element in the given iterable.
      • isAnyOf

        public void isAnyOf​(@Nullable java.lang.Object first,
                            @Nullable java.lang.Object second,
                            @Nullable java.lang.Object @Nullable ... rest)
        Fails unless the subject is equal to any of the given elements.
      • isNotIn

        public void isNotIn​(@Nullable java.lang.Iterable<?> iterable)
        Fails if the subject is equal to any element in the given iterable.
      • isNoneOf

        public void isNoneOf​(@Nullable java.lang.Object first,
                             @Nullable java.lang.Object second,
                             @Nullable java.lang.Object @Nullable ... rest)
        Fails if the subject is equal to any of the given elements.
      • actualCustomStringRepresentation

        @ForOverride
        protected java.lang.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​(java.lang.String format,
                                                     @Nullable java.lang.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​(java.lang.String key,
                                            @Nullable java.lang.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")).

      • 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 failWithActual 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")).

      • equals

        @Deprecated
        public final boolean equals​(@Nullable java.lang.Object o)
        Deprecated.
        Object.equals(Object) is not supported on Truth subjects. If you are writing a test assertion (actual vs. expected), use isEqualTo(Object) instead.
        Overrides:
        equals in class java.lang.Object
        Throws:
        java.lang.UnsupportedOperationException - always
      • hashCode

        @Deprecated
        public final int hashCode()
        Deprecated.
        Object.hashCode() is not supported on Truth subjects.
        Overrides:
        hashCode in class java.lang.Object
        Throws:
        java.lang.UnsupportedOperationException - always
      • toString

        @Deprecated
        public java.lang.String toString()
        Deprecated.
        Object.toString() is not supported on Truth subjects.
        Overrides:
        toString in class java.lang.Object
        Throws:
        java.lang.UnsupportedOperationException - always