Class Truth

java.lang.Object

com.google.common.truth.Truth

public final class Truth
extends Object

The primary entry point for Truth, a library for fluent test assertions.

Compare these example JUnit assertions...

 assertEquals(b, a);
 assertTrue(c);
 assertTrue(d.contains(a));
 assertTrue(d.contains(a) && d.contains(b));
 assertTrue(d.contains(a) || d.contains(b) || d.contains(c));
 

...to their Truth equivalents...

 assertThat(a).isEqualTo(b);
 assertThat(c).isTrue();
 assertThat(d).contains(a);
 assertThat(d).containsAtLeast(a, b);
 assertThat(d).containsAnyOf(a, b, c);
 

Advantages of Truth:

• aligns all the "actual" values on the left
• produces more detailed failure messages
• provides richer operations (like IterableSubject.containsExactly(java.lang.Object...))

For more information about the methods in this class, see this FAQ entry.

For people extending Truth

The most common way to extend Truth is to write a custom Subject. (The other, much less common way is to write a custom FailureStrategy.) For more information, visit those types' docs.

Author:

David Saff, Christian Gruber (cgruber@israfil.net)

Method Summary

Modifier and Type	Method	Description
static StandardSubjectBuilder	assert_()	Begins a call chain with the fluent Truth API.
static <CustomSubjectBuilderT extends CustomSubjectBuilder> CustomSubjectBuilderT	assertAbout(CustomSubjectBuilder.Factory<CustomSubjectBuilderT> factory)	A generic, advanced method of extension of Truth to new types, which is documented on CustomSubjectBuilder.
static <S extends Subject, T> SimpleSubjectBuilder<S,T>	assertAbout(Subject.Factory<S,T> factory)	Given a factory for some Subject class, returns a builder whose that(actual) method creates instances of that class.
static PrimitiveBooleanArraySubject	assertThat(boolean @Nullable [] actual)	Begins an assertion about a boolean array.
static PrimitiveByteArraySubject	assertThat(byte @Nullable [] actual)	Begins an assertion about a byte array.
static PrimitiveCharArraySubject	assertThat(char @Nullable [] actual)	Begins an assertion about a char array.
static PrimitiveDoubleArraySubject	assertThat(double @Nullable [] actual)	Begins an assertion about a double array.
static PrimitiveFloatArraySubject	assertThat(float @Nullable [] actual)	Begins an assertion about a float array.
static PrimitiveIntArraySubject	assertThat(int @Nullable [] actual)	Begins an assertion about an int array.
static PrimitiveLongArraySubject	assertThat(long @Nullable [] actual)	Begins an assertion about a long array.
static PrimitiveShortArraySubject	assertThat(short @Nullable [] actual)	Begins an assertion about a short array.
static <ComparableT extends Comparable<?>> ComparableSubject<ComparableT>	assertThat(@Nullable ComparableT actual)	Begins an assertion about a Comparable.
static GuavaOptionalSubject	assertThat(@Nullable Optional<?> actual)	Begins an assertion about a Guava Optional.
static MultimapSubject	assertThat(@Nullable Multimap<?,?> actual)	Begins an assertion about a Multimap.
static MultisetSubject	assertThat(@Nullable Multiset<?> actual)	Begins an assertion about a Multiset.
static TableSubject	assertThat(@Nullable Table<?,?,?> actual)	Begins an assertion about a Table.
static BooleanSubject	assertThat(@Nullable Boolean actual)	Begins an assertion about a Boolean.
static ClassSubject	assertThat(@Nullable Class<?> actual)	Begins an assertion about a Class.
static DoubleSubject	assertThat(@Nullable Double actual)	Begins an assertion about a Double.
static FloatSubject	assertThat(@Nullable Float actual)	Begins an assertion about a Float.
static IntegerSubject	assertThat(@Nullable Integer actual)	Begins an assertion about an Integer.
static IterableSubject	assertThat(@Nullable Iterable<?> actual)	Begins an assertion about an Iterable.
static LongSubject	assertThat(@Nullable Long actual)	Begins an assertion about a Long.
static Subject	assertThat(@Nullable Object actual)	Begins an assertion about an Object.
static StringSubject	assertThat(@Nullable String actual)	Begins an assertion about a String.
static ThrowableSubject	assertThat(@Nullable Throwable actual)	Begins an assertion about a Throwable.
static BigDecimalSubject	assertThat(@Nullable BigDecimal actual)	Begins an assertion about a BigDecimal.
static PathSubject	assertThat(@Nullable Path actual)	Begins an assertion about a Path.
static MapSubject	assertThat(@Nullable Map<?,?> actual)	Begins an assertion about a Map.
static OptionalSubject	assertThat(@Nullable Optional<?> actual)	Begins an assertion about an Optional.
static OptionalDoubleSubject	assertThat(@Nullable OptionalDouble actual)	Begins an assertion about an OptionalDouble.
static OptionalIntSubject	assertThat(@Nullable OptionalInt actual)	Begins an assertion about an OptionalInt.
static OptionalLongSubject	assertThat(@Nullable OptionalLong actual)	Begins an assertion about an OptionalLong.
static IntStreamSubject	assertThat(@Nullable IntStream actual)	Begins an assertion about an IntStream.
static LongStreamSubject	assertThat(@Nullable LongStream actual)	Begins an assertion about a LongStream.
static StreamSubject	assertThat(@Nullable Stream<?> actual)	Begins an assertion about a Stream.
static <T extends @Nullable Object> ObjectArraySubject<T>	assertThat(T @Nullable [] actual)	Begins an assertion about an Object array.
static StandardSubjectBuilder	assertWithMessage(@Nullable String messageToPrepend)	Begins an assertion that, if it fails, will prepend the given message to the failure message.
static StandardSubjectBuilder	assertWithMessage(String format, @Nullable Object... args)	Begins an assertion that, if it fails, will prepend the given message to the failure message.

Methods inherited from class java.lang.Object

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

Method Details

assert_

public static StandardSubjectBuilder assert_()

Begins a call chain with the fluent Truth API. If the check made by the chain fails, it will throw AssertionError.

assertWithMessage

public static StandardSubjectBuilder assertWithMessage(@Nullable String messageToPrepend)

Begins an assertion that, if it fails, will prepend the given message to the failure message.

This method is a shortcut for assert_().withMessage(...).

To set a message when using a custom subject, use assertWithMessage(...).about(...), as discussed in this FAQ entry.

assertWithMessage

public static StandardSubjectBuilder assertWithMessage(String format,
 @Nullable Object... args)

Begins an assertion that, if it fails, will prepend the given message to the failure message.

Note: the arguments will be substituted into the format template using Strings.lenientFormat. Note this only supports the %s specifier.

This method is a shortcut for assert_().withMessage(...).

To set a message when using a custom subject, use assertWithMessage(...).about(...), as discussed in this FAQ entry.

Throws:

IllegalArgumentException - if the number of placeholders in the format string does not equal the number of given arguments

assertAbout

public static <S extends Subject, T>
SimpleSubjectBuilder<S,T> assertAbout(Subject.Factory<S,T> factory)

Given a factory for some Subject class, returns a builder whose that(actual) method creates instances of that class.

assertAbout

public static <CustomSubjectBuilderT extends CustomSubjectBuilder>
CustomSubjectBuilderT assertAbout(CustomSubjectBuilder.Factory<CustomSubjectBuilderT> factory)

A generic, advanced method of extension of Truth to new types, which is documented on CustomSubjectBuilder. Extension creators should prefer Subject.Factory if possible.

assertThat

public static <ComparableT extends Comparable<?>>
ComparableSubject<ComparableT> assertThat(@Nullable ComparableT actual)

Begins an assertion about a Comparable.

assertThat

public static BigDecimalSubject assertThat(@Nullable BigDecimal actual)

Begins an assertion about a BigDecimal.

assertThat

public static Subject assertThat(@Nullable Object actual)

Begins an assertion about an Object.

assertThat

@GwtIncompatible("ClassSubject.java")
public static ClassSubject assertThat(@Nullable Class<?> actual)

Begins an assertion about a Class.

assertThat

public static ThrowableSubject assertThat(@Nullable Throwable actual)

Begins an assertion about a Throwable.

Truth does not provide its own support for calling a method and automatically catching an expected exception, only for asserting on the exception after it has been caught. To catch the exception, we suggest assertThrows (JUnit), assertFailsWith (kotlin.test), or similar functionality from your testing library of choice.

 InvocationTargetException expected =
     assertThrows(InvocationTargetException.class, () -> method.invoke(null));
 assertThat(expected).hasCauseThat().isInstanceOf(IOException.class);
 

assertThat

public static LongSubject assertThat(@Nullable Long actual)

Begins an assertion about a Long.

assertThat

public static DoubleSubject assertThat(@Nullable Double actual)

Begins an assertion about a Double.

assertThat

public static FloatSubject assertThat(@Nullable Float actual)

Begins an assertion about a Float.

assertThat

public static IntegerSubject assertThat(@Nullable Integer actual)

Begins an assertion about an Integer.

assertThat

public static BooleanSubject assertThat(@Nullable Boolean actual)

Begins an assertion about a Boolean.

assertThat

public static StringSubject assertThat(@Nullable String actual)

Begins an assertion about a String.

assertThat

public static IterableSubject assertThat(@Nullable Iterable<?> actual)

Begins an assertion about an Iterable.

assertThat

public static <T extends @Nullable Object>
ObjectArraySubject<T> assertThat(T @Nullable [] actual)

Begins an assertion about an Object array.

assertThat

public static PrimitiveBooleanArraySubject assertThat(boolean @Nullable [] actual)

Begins an assertion about a boolean array.

assertThat

public static PrimitiveShortArraySubject assertThat(short @Nullable [] actual)

Begins an assertion about a short array.

assertThat

public static PrimitiveIntArraySubject assertThat(int @Nullable [] actual)

Begins an assertion about an int array.

assertThat

public static PrimitiveLongArraySubject assertThat(long @Nullable [] actual)

Begins an assertion about a long array.

assertThat

public static PrimitiveByteArraySubject assertThat(byte @Nullable [] actual)

Begins an assertion about a byte array.

assertThat

public static PrimitiveCharArraySubject assertThat(char @Nullable [] actual)

Begins an assertion about a char array.

assertThat

public static PrimitiveFloatArraySubject assertThat(float @Nullable [] actual)

Begins an assertion about a float array.

assertThat

public static PrimitiveDoubleArraySubject assertThat(double @Nullable [] actual)

Begins an assertion about a double array.

assertThat

public static GuavaOptionalSubject assertThat(@Nullable Optional<?> actual)

Begins an assertion about a Guava Optional.

assertThat

public static MapSubject assertThat(@Nullable Map<?,?> actual)

Begins an assertion about a Map.

assertThat

public static MultimapSubject assertThat(@Nullable Multimap<?,?> actual)

Begins an assertion about a Multimap.

assertThat

public static MultisetSubject assertThat(@Nullable Multiset<?> actual)

Begins an assertion about a Multiset.

assertThat

public static TableSubject assertThat(@Nullable Table<?,?,?> actual)

Begins an assertion about a Table.

assertThat

public static OptionalSubject assertThat(@Nullable Optional<?> actual)

Begins an assertion about an Optional.

Since:

1.3.0 (present in Truth8 since before 1.0)

assertThat

public static OptionalIntSubject assertThat(@Nullable OptionalInt actual)

Begins an assertion about an OptionalInt.

Since:

1.3.0 (present in Truth8 since before 1.0)

assertThat

public static OptionalLongSubject assertThat(@Nullable OptionalLong actual)

Begins an assertion about an OptionalLong.

Since:

1.4.0 (present in Truth8 since before 1.0)

assertThat

public static OptionalDoubleSubject assertThat(@Nullable OptionalDouble actual)

Begins an assertion about an OptionalDouble.

Since:

1.4.0 (present in Truth8 since before 1.0)

assertThat

public static StreamSubject assertThat(@Nullable Stream<?> actual)

Begins an assertion about a Stream.

Since:

1.4.0 (present in Truth8 since before 1.0)

assertThat

public static IntStreamSubject assertThat(@Nullable IntStream actual)

Begins an assertion about an IntStream.

Since:

1.4.0 (present in Truth8 since before 1.0)

assertThat

public static LongStreamSubject assertThat(@Nullable LongStream actual)

Begins an assertion about a LongStream.

Since:

1.4.0 (present in Truth8 since before 1.0)

assertThat

@GwtIncompatible
@J2ObjCIncompatible
public static PathSubject assertThat(@Nullable Path actual)

Begins an assertion about a Path.

Since:

1.4.0 (present in Truth8 since before 1.0)