Fluent assertions for Java and Android
This release is the final step of copying all our methods from Truth8
to Truth
. If you have not already migrated your usages from Truth8
to Truth
, you may see build errors:
OptionalSubjectTest.java:39: error: reference to assertThat is ambiguous
assertThat(Optional.of("foo")).isPresent();
^
both method assertThat(@org.checkerframework.checker.nullness.qual.Nullable Optional<?>) in Truth8 and method assertThat(@org.checkerframework.checker.nullness.qual.Nullable Optional<?>) in Truth match
In most cases, you can migrate your whole project mechanically: git grep -l Truth8 | xargs perl -pi -e 's/\bTruth8\b/Truth/g;'
. (You can make that change before upgrading to Truth 1.4.2 or as part of the same commit.)
If you instead need to migrate your project incrementally (for example, because it is very large), you may want to upgrade your version of Truth incrementally, too, following our instructions for 1.3.0 and 1.4.0.
Please feel welcome to open an issue to report problems or request help.
Truth.assertThat(Stream)
and Truth.assertThat(Optional)
. This can create build errors, which you can fix by replacing all your references to Truth8
with references to Truth
. (45782bd0e)This release deprecates Truth8
.
All its methods have become available on the main Truth
class. In most cases, you can migrate your whole project mechanically: git grep -l Truth8 | xargs perl -pi -e 's/\bTruth8\b/Truth/g;'
While we do not plan to delete Truth8
, we recommend migrating off it, at least if you static import assertThat
: If you do not migrate, such static imports will become ambiguous in Truth 1.4.2, breaking your build.
In this release, our assertions on Java 8 types continue to move from the Truth8
class to the main Truth
class. This change should not break compatibility for any supported JDK or Android version, even users who test under old versions of Android without API desugaring. Additionally, we will never break binary compatibility, though some users will have to make changes to their source code in order for it to compile against newer versions.
This release is likely to lead to more build failures than 1.3.0 did. However, those failures should be straightforward to fix.
Foo.java:152: error: reference to assertThat is ambiguous
assertThat(repo.findFileWithName("foo")).isNull();
^
both method assertThat(@org.checkerframework.checker.nullness.qual.Nullable Path) in Truth8 and method assertThat(@org.checkerframework.checker.nullness.qual.Nullable Path) in Truth match
In the same commit:
import static com.google.common.truth.Truth8.assertThat;
with import static com.google.common.truth.Truth.assertThat;
.
import com.google.common.truth.Truth8.assertThat
with import com.google.common.truth.Truth.assertThat
.import com.google.common.truth.Truth8;
with import com.google.common.truth.Truth;
.
Truth8
with references to Truth
.
Truth8.assertThat(optional).isPresent()
with Truth.assertThat(optional).isPresent()
.If you're feeling lucky, you can try this one-liner for the code updates:
git grep -l Truth8 | xargs perl -pi -e 's/import static com.google.common.truth.Truth8.assertThat;/import static com.google.common.truth.Truth.assertThat;/g; s/import com.google.common.truth.Truth8.assertThat/import com.google.common.truth.Truth.assertThat/g; s/import com.google.common.truth.Truth8/import com.google.common.truth.Truth/g; s/\bTruth8[.]/Truth./g;'
In most cases, that can be further simplified to:
git grep -l Truth8 | xargs perl -pi -e 's/\bTruth8\b/Truth/g;'
After that process, it is possible that you'll still see build errors from ambiguous usages of assertThat
static imports. If so, you can find a workaround in the section about overload ambiguity in the release notes for 1.3.0. Alternatively, you can wait to upgrade until after a future Truth release, which will eliminate the ambiguity by changing the signatures of some Truth.assertThat
overloads.
If you have a very large repo or you have other reasons to prefer to upgrade incrementally, you can use the approach that we used inside Google. Roughly, that approach was:
Truth8.assertThat
, change them to avoid static import.
assertThat(optional).isPresent()
with Truth8.assertThat(optional).isPresent()
.Truth8
with references to Truth
(including restoring static imports if desired), as discussed in section about the simple upgrade strategy above.assertWithMessage(...).about(intStreams()).that(...)
, expect.about(optionalLongs()).that(...)
, or similar, you can remove your call to about
. This change will never be necessary; it is just a simplification.
streams
and optionals
, whereas 1.4.0 solves it for the other Truth8
types.Please feel welcome to open an issue to report problems or request help.
Truth8.assertThat
overloads to the main Truth
class. (9be8e774c, 1f81827f1)that
overloads to make it possible to write type-specific assertions when using the remaining Java 8 types. (7c65fc611)In this release, our assertions on Java 8 types begin to move from the truth-java8-extensions
artifact and the Truth8
class to the main truth
artifact and the Truth
class. This change should not break compatibility for any supported JDK or Android version, even users who test under old versions of Android without API desugaring. Additionally, we will never break binary compatibility, though some users will have to make changes to their source code in order for it to compile against newer versions.
This change will be routine for most users, but we're providing as much information as we can for any users who do encounter problems.
We will post fuller instructions for migration later on, once we've learned more from our internal migration efforts. For now, you may find that you need to make one kind of change, and you may elect to make others. (If we missed anything, please open an issue to report problems or request help.)
The change you might need to make:
Truth.assertThat
, we cause some code to fail to compile because of an overload ambiguity. This is rare, but it can happen if you static import both Truth.assertThat
and some other assertThat
method that includes overloads for Optional
or Stream
. (It does not happen for Truth8.assertThat
, though, except with the Eclipse compiler. Nor it does necessarily happen for other assertThat(Stream)
and assertThat(Optional)
methods.) If this happens to you, you'll need to remove one of the static imports, changing the corresponding call sites from "assertThat
" to "FooSubject.assertThat
."
Truth.assertThat
overloads. Once we make those further changes, you may be able to simultaneously replace all your imports of Truth8.assertThat
with imports of Truth.assertThat
as you upgrade to the new version, likely without introducing overload ambiguities.The changes you might elect to make:
If you use Truth8.assertThat(Stream)
or Truth8.assertThat(Optional)
, you can migrate to the new overloads in Truth
. If you static import Truth8.assertThat
, you can usually make this change simply by replacing that static import with a static import of Truth.assertThat
—or, if you already have an import of Truth.assertThat
, by just removing the import of Truth8.assertThat
. (If you additionally use less common assertion methods, like assertThat(OptionalInt)
, you'll want to use both imports for now. Later, we'll move assertThat(OptionalInt)
and friends, too.) We recommend making this change now, since your calls to Truth8.assertThat
will fail to compile against some future version of Truth, unless you plan to wait to update your Truth dependency until we've made all our changes for Java 8 types.
If you use assertWithMessage(...).about(streams()).that(...)
, expect.about(optionals()).that(...)
, or similar, you can remove your call to about
. This change will never be necessary; it is just a simplification.
If you depend on truth-java8-extension
, you may remove it. All its classes are now part of the main truth
artifact. This change, too, is not necessary; it is just a simplification. (OK, if your build system has a concept of strict deps, there is a chance that you'll need to add deps on truth
to replace your deps on truth-java8-extension
.)
Finally, the changelog for this release:
StreamSubject
avoid collecting the Stream
until necessary, and made its isEqualTo
and isNotEqualTo
methods no longer always throw. (f8ecaec69)assertThat
overloads for Optional
and Stream
to the main Truth
class. (37fd8bea9)that
overloads to make it possible to write type-specific assertions when using expect.that(optional)
and expect.that(stream)
. (ca7e8f4c5)truth-java8-extension
classes into the main truth
artifact. There is no longer any need to depend on truth-java8-extension
, which is now empty. (We've also removed the Truth8
GWT module.) (eb0426eb7)Again, if you have any problems, please let us know.
Any
messages. This fix may cause tests to fail, since ProtoTruth will now check whether the message contents match. If so, you may need to change the values that your tests expect, or there may be a bug in the code under test that had been hidden by the Truth bug. Sorry for the trouble. (8bd3ef613)isWithin().of()
support to IntegerSubject
and LongSubject
. (6464cb5ca, 0e99a2711)IterableOfProtosSubject
to produce a proper failure message instead of NPE when the actual value is null
.-source 8 -target 8
. This means that it no longer runs under Java 7 VMs. It continues to run under Android, even old versions, for all apps that have enabled support for Java 8 language features. (db5db2429)value of: method()
to expect.that
, matching the existing support for assertThat
. (bd8efd003)IterableSubject.containsAtLeastElementsIn().inOrder()
to print an extra line that shows only the expected elements in their actual order. (9da7dd184)comparingExpectedFieldsOnly()
handles oneof
fields. (f27208428)comparingExpectedFieldsOnly
to work when required fields are absent. (f27208428)Subject.toString()
to throw UnsupportedOperationException
. (fa4c7b512)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.
Expect
, ExpectFailure
, and TruthJUnit.assume()
.) (948f3edca)AssertionError
Truth generates as a substitute for ComparisonFailure
now includes the expected and actual values that were missing in 1.1.1. (6b0140730)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.
Expect
, ExpectFailure
, and TruthJUnit.assume()
.) (2d65326ec)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.