1.1.2

This release completes the feature that I got wrong in 1.1.1 -- the ability to exclude our JUnit 4 dependency and still use standard Truth assertions.

• Made it possible for users to exclude our JUnit 4 dependency and still use standard Truth assertions -- really this time, even in cases in which excluding the dependency failed under 1.1.1. (JUnit 4 is still required for some advanced features, like Expect, ExpectFailure, and TruthJUnit.assume().) (948f3ed)
• When JUnit 4 is excluded from the classpath, the AssertionError Truth generates as a substitute for ComparisonFailure now includes the expected and actual values that were missing in 1.1.1. (6b01407)

1.1.1

We recommend not trying to exclude our JUnit dependency even under this release. We will release 1.1.2 with better handling for the missing dependency shortly.

• Made it possible for users to exclude our JUnit 4 dependency and still use standard Truth assertions. (JUnit 4 is still required for some advanced features, like Expect, ExpectFailure, and TruthJUnit.assume().) (2d65326)
  • Update: This appears to let users exclude the dependency in some cases but not all. We are working on a fix.
  • Update 2: Also, even if you succeed in excluding the dependency in your environment, you will see failure messages that are missing information. We have a fix for this ready.

If you wish to exclude our JUnit dependency, you may wish to consider this alternative approach. That approach may be worthwhile even after we fix the bugs described above.

I apologize for the trouble.

1.1

• Fixed (we think :)) R8 compilation failure: Error: com.android.tools.r8.errors.b: Compilation can't be completed because `org.objectweb.asm.ClassVisitor` and 1 other classes are missing. (0bfa285)
• Added unpackingAnyUsing(TypeRegistry, ExtensionRegistry). If you call this method, ProtoTruth will attempt to unpack Any messages before comparing them. (b50d878)
• Added formattingDiffsUsing methods to IterableSubject and MapSubject. This allows you to get failure messages which show diffs between the actual and expected elements (like you get with comparingElementsUsing) while still comparing them using object equality. (ae997be)
• Changed Checker Framework annotations from checker-qual to qual. (e71b57b) With this change, we inadvertently introduced Java 8 bytecode into our dependencies. Please report problems on #882. Sorry for the trouble.
• Added null checks to StringSubject. (3481ab0)
• Included ASM as a dependency (non-<optional>) by default. It is still safe to exclude if you want to minimize dependencies, but by including it, you may see better failure messages. (aea78e8)
• Removed dependency on gwt-user. (b54e9ef)
• API documentation for Truth classes is now easier to reach. For example, for StringSubject, visit truth.dev/StringSubject. Also, more easily access the index at truth.dev/api.

1.0.1

• Changed failure messages to identify trailing whitespace in failed string comparisons. (7a58a45)
• Moved gwt-user to test scope. (51bbbf4)
• Fixed handling of proto maps with keys equal to the key type's default value. (8ebfe2a)
• Worked around what seems to be a classloading bug in old versions of some vendors' Android runtimes. (02c5e79)

Truth 1.0

Truth is a library for performing assertions in tests:

assertThat(notificationText).contains("testuser@google.com");

Truth is owned and maintained by the Guava team. It is used in the majority of the tests in Google’s own codebase.

For more information, see our full documentation at truth.dev, or start with our higher-level blog post.

Users of AssertJ will be particularly interested in our comparison of Truth and AssertJ.

---

Truth 1.0 contains no changes relative to 1.0-rc2. For a list of changes since Truth 0.46, see the release notes for rc1 and rc2.

Now that we have reached 1.0 (after eight years! We're sorry, and we thank you again for your patience), we will maintain binary compatibility.

Truth 1.0-rc2

Sorry for the last-second changes. We still expect to release 1.0 on July 8.

• Changed DoubleSubject and FloatSubject to override isEqualTo and isNotEqualTo instead of declaring an overload. (4743c14)
• Changed MultimapSubject.UsingCorrespondence methods containsExactly and containsAtLeast to require an E for their one non-varargs value argument, and removed their type parameters. (4743c14)
• Eliminated type parameters on MapSubject.UsingCorrespondence and MultimapSubject.UsingCorrespondence methods containsExactlyEntriesIn and containsAtLeastEntriesIn. (4743c14)
• Changed IntStreamSubject and LongStreamSubject methods isInOrder and isInStrictOrder to require a compatible Comparator. (4743c14)

Truth 1.0-rc1

We expect to release 1.0 (and publish an official announcement) on Monday, July 8.

• Made assertThat(0.0).isEqualTo(0) pass, despite the mix of double and int. (And likewise for float and int.) This extends existing support that previously applied only to integral types. (1c5f9e8)
• Added int overloads of isGreaterThan, isLessThan, isAtLeast, and isAtMost. (dc92786)
• Removed the overload of StandardSubjectBuilder.fail(...) that accepts a message. Instead of assert_().fail(...), use assertWithMessage(...).fail(). Similarly, instead of expect.fail(...), use expect.withMessage(...).fail(), and so forth. (f6875d6)
• Removed DefaultSubject. Use plain Subject. (f6875d6)
• Removed AtomicLongMapSubject. In most cases, you can assert on the asMap() view instead. (f6875d6)
• Removed Optional*Subject.hasValueThat(). Instead of assertThat(optional).hasValueThat()...., use assertThat(optional.getAs*())..... (f6875d6)

Truth 0.46

• Removed deprecated containsAllOf and containsAllIn. Use containsAtLeast and containsAtLeastElementsIn, which are equivalent. (5de3d21)
• Removed deprecated isOrdered and isStrictlyOrdered. Use isInOrder and isInStrictOrder, which are equivalent. (5de3d21)
• Removed deprecated SortedMapSubject and SortedSetSubject. Users will have to perform assertions directly on the result of methods like firstKey. We haven't found sufficient demand for the classes to keep them. (057ef31)
• Removed deprecated ListMultimapSubject, SetMultimapSubject, and ProtoTruth equivalents, which add little to the general Multimap subjects. (057ef31)
• Removed the type parameters from Subject. If you subclass this type (or declare it as a method return type, etc.), you will have to update those usages at the same time you update Truth. Or you can remove the type parameters from your usages (temporarily introducing rawtypes/unchecked warnings, which you may wish to suppress) and then update Truth (at which point the warnings will go away and you can remove any suppressions). (3740ee6) To remove the type parameters from Subject subclasses, you can get most of the way there with a Perl-compatible regex search-and-replace operation: s/\bSubject<([^<>]*|[^<>]*<[^<>]*>[^<>]*|[^<>]*<[^<>]*>[^<>]*<[^<>]*>[^<>]*|[^<>]*<[^<>]*<[^<>]*>[^<>]*>)>/Subject/g
• Removed the self-type parameter of ComparableSubject and most of the type parameters of IterableOfProtosSubject, MapWithProtoValuesSubject, and MultimapWithProtoValuesSubject. If you subclass any of those types (or declare them as method return types, etc.), you will have to update those usages at the same time you update Truth. Or you can remove the type parameters from your usages, update Truth, and then add back the remaining type parameters. (e611568)
• Removed the type parameters of ProtoSubject and LiteProtoSubject. If you subclass either of those types (or declare them as method return types, etc.), you will have to update those usages at the same time you update Truth. Or you can remove the type parameters from your usages (temporarily introducing rawtypes/unchecked warnings, which you may wish to suppress) and then update Truth (at which point the warnings will go away and you can remove any suppressions). (eb3852c)
• Removed deprecated actual(), getSubject(), named(), internalCustomName(), and actualAsString(). To automate most migrations, we've provided StoreActualValueInField and NamedToWithMessage (and a quick-and-dirty regex version for common cases). (If you are migrating manually, you may need to know how to handle java.util.Optional, Stream, and other types that aren't built in.) You might also be interested in our notes from the API Review of this decision. (c1db1b7)
• Changed ProtoSubject to not extend ProtoFluentAssertion. It still contains all the same methods, except that isEqualTo and isNotEqualTo now require a Message, rather than accept any Object. (777af33)
• Deprecated the overload of StandardSubjectBuilder.fail(...) that accepts a message. Instead of assert_().fail(...), use assertWithMessage(...).fail(). Similarly, instead of expect.fail(...), use expect.withMessage(...).fail(), and so forth. (227b559)
• Deprecated AtomicLongMapSubject. In most cases, you can assert on the asMap() view instead. (19e1f22)
• Deprecated Optional*Subject.hasValueThat(). Instead of assertThat(optional).hasValueThat()...., use assertThat(optional.getAs*())..... (227b559)
• Changed assertWithMessage to throw an exception if given format arguments but a null format string. (31e44cc)
• Reimplemented the message-accepting overload of fail(...) in terms of withMessage(...). This is mostly a no-op but can affect behavior in unusual cases. For details, see the commit description. (a52f89b)
• Made IterableSubject.isEqualTo produce the same message format as containsExactly. (27a9111)
• Introduced TruthFailureSubject.truthFailures() factory for callers that want to test Truth failure messages with expect, assertWithMessage, etc. (c1db1b7)

Truth 0.45

We are pushing hard to release a Truth 1.0 by June 30, after which we don't expect to remove any more APIs. Thanks for your patience with both our slow progress over the past several years and our rapid churn now.

To use the migration tools below, you'll need to set up Error Prone and configure our tools as plugins to run in patch mode.

Deletions:

• Removed deprecated Subject.isSameAs and isNotSameAs. Use isSameInstanceAs and isNotSameInstanceAs, which are equivalent. (36200e6)
• Hid the constuctor of Correspondence. Use the class's static factory methods instead. The most mechanical migration is usually to Correspondence.from. To help with migration, we're released CorrespondenceSubclassToFactoryCall. (11da1ca)
• Removed deprecated Subject.fail* methods. See Subject.failWithActual and failWithoutActual, which use the new Fact class. To help with migration, we're released FailWithFacts (and also ImplementAssertionWithChaining, which is also sometimes useful for these migrations), though you will likely need to make manual changes, as well. (36200e6)
• Removed deprecated no-arg Subject.check(). Use the overload that accepts a description. (To help with this migration, we have added ProvideDescriptionToCheck to Error Prone -- but then removed it before it became part of a release, so you'll need to pull it in manually.) (36200e6)
• Removed deprecated MathUtil. For similar static methods, see Guava's DoubleMath.fuzzyEquals. But callers from custom Subject implementations may prefer an approach like check("score()").that(actual.score()).isWithin(tolerance).of(expected). (7b2876d)
• Removed deprecated createAndEnableStackTrace(). Use create(), which now also enables stack traces. (9362f4c)

Deprecations:

• Deprecated isOrdered() and isStrictlyOrdered(). Use isInOrder() and isInStrictOrder(), which are equivalent. (146080a, 386207d)
• Deprecated containsAll* on ProtoTruth, *StreamSubject, and Primitive*ArraySubject.*ArrayAsIterable. Use containsAtLeast*, which is equivalent. (82c1f2d, 386207d)
• Deprecated Subject.actual(). Instead of calling it, declare your own field to store the actual value. To automate most migrations, we've provided StoreActualValueInField. (297c0f1)
• Deprecated Subject.named. Instead of assertThat(foo).named("foo"), use assertWithMessage("foo").that(foo). For custom subjects, use assertWithMessage("foo").about(foos()).that(foo). For other scenarios, see this FAQ entry about adding messages. To automate most migrations, we've provided NamedToWithMessage (and a quick-and-dirty regex version for common cases). You might be interested in our notes from the API Review of this decision. (08afb24)
• "Deprecated" the type parameters on Subject. To prepare for their removal in the next release, you can edit your code today to refer to the raw Subject type. (Kotlin Subject authors, see below.) Also "deprecated" the self-type parameter on ComparableSubject. Again, you can prepare your code by referring to raw ComparableSubject (and later change it to refer to ComparableSubject<T> when the class has only one type parameter next release). Similarly, "deprecated" the type parameters on ProtoSubject and LiteProtoSubject, along with most of the type parameters of IterableOfProtosSubject, MapWithProtoValuesSubject, and MultimapWithProtoValuesSubject. (21c29f7, 5abd9ed)
• Loosened type parameters on Subject.Factory. This permits custom Subject subclasses extend raw Subject instead of Subject<FooSubject, Foo> to prepare for when we remove the type parameters from Subject entirely.
• Deprecated DefaultSubject. Use plain Subject. (7b5311b)
• Deprecated SortedMapSubject and SortedSetSubject. Users will have to perform assertions directly on the result of methods like firstKey. We haven't found sufficient demand for the classes to keep them. (46aebcf)
• Deprecated the SetMultimap-specific and ListMultimap-specific Subjects, which add little to the general Multimap subjects. (2103fee)
• Deprecated actualAsString() and internalCustomName(). They exist primarily to support named(), which is being removed. (d69ba29)

Other migration notes:

• The order in which you migrate can be important: Migrate off actual() and named() before removing type parameters from custom Subject classes.
• The tool we'll release for migrating off named requires that custom Subject classes expose a Subject.Factory, as described in our docs about extensions.
• To remove the type parameters from Subject subclasses, you can get most of the way there with a Perl-compatible regex search-and-replace operation: s/\bSubject<([^<>]*|[^<>]*<[^<>]*>[^<>]*|[^<>]*<[^<>]*>[^<>]*<[^<>]*>[^<>]*|[^<>]*<[^<>]*<[^<>]*>[^<>]*>)>/Subject/g

Features:

• For very simple tests, failure messages will include a "value of:" line. For example, the failure message of assertThat(fetchLogMessages()).isEmpty() might contain "value of: fetchLogMessages()." This feature is not available under Android or GWT, and it is only available if you have ASM on your classpath.
• Exposed the constructors of ThrowableSubject, MapSubject, and MultimapSubject to subclasses. Note that actually extending those subjects won't fully work until we remove the type parameters from Subject. (1a39d5a, 32f76a5)
• Temporarily made DefaultSubject extensible again. Kotlin subjects can now extend DefaultSubject instead of Subject. This lets those subjects compile both before and after we remove the type parameters from Subject. After we remove the type parameters, Kotlin subjects should extend Subject again (with no type parameters), as we'll later remove DefaultSubject. (6e45b27)
• Made ProtoTruth Subject classes extend IterableSubject, MapSubject, and MultimapSubject. (1a39d5a).
• Updated stack-trace cleaning to handle reflection under Java 9.

Truth 0.44

To use the migration tools below, you'll need to set up Error Prone and configure our tools as plugins to run in patch mode.

• Deprecated Subject.isSameAs and isNotSameAs. Use isSameInstanceAs and isNotSameInstanceAs, which are equivalent. (bc845f0)
• Deprecated IterableSubject.containsAllOf and containsAllIn. Use the containsAtLeast and containsAtLeastElementsIn, which are equivalent. (bc845f0)
• Deprecated the no-arg Subject.check(). Use the overload that accepts a description. (To help with this migration, we have added ProvideDescriptionToCheck to Error Prone -- but then removed it before it became part of a release, so you'll need to pull it in manually.) (bc845f0)
• Deprecated Expect.createAndEnableStackTrace(). Expect.create() now does the same thing. (bc845f0)
• Deprecated the constructor of Correspondence. Instead of extending the type, use its new static factories. To help with migration, we're released CorrespondenceSubclassToFactoryCall. (bc845f0, 8bd19b4)
• Deprecated MathUtil. For similar static methods, see Guava's DoubleMath.fuzzyEquals. But callers from custom Subject implementations may prefer an approach like check("score()").that(actual.score()).isWithin(tolerance).of(expected). (bc845f0)
• Removed deprecated ComparableSubject.comparesEqualTo and Primitive{Double,Float}ArraySubject.hasValues{,Not}Within. (cc796b3)
• Removed deprecated ThrowableSubject.hasMessage() (3164a24)
• You can now create a Correspondence instance that adds in diff-formatting behavior to an existing Correspondence using Correspondence.formattingDiffsUsing. (d222360)

Also note that the next version of Error Prone will include ImplementAssertionWithChaining, which is sometimes useful for migrating off the deprecated Subject.fail* methods.