TL;DR
We currently expose overlapping assertThat entry points across Assertions, AssertionsForClassTypes, and AssertionsForInterfaceTypes (plus additional assertThat<Type> variants), which can be confusing for users.
For example, we mention in the README:
just type assertThat(underTest). and use code completion to show you all assertions available
and in the user guide:
The Assertions class is the only class you need to start using AssertJ
However, when trying to statically import assertThat() on 3.27.7, users see:
Per JLS §15.12.2.5 (most-specific method selection) and JLS §4.10.2 (class/interface supertypes), class-specific overloads already win with a concrete class value. Ambiguity can appear:
- When a value matches multiple unrelated interface overloads (for example,
CharBuffer matching both CharSequence and Comparable)
- With bounded type variables like any
<T extends X> where X is a class that also participates in interface-based overload competition
Given this, both AssertionsForClassTypes and AssertionsForInterfaceTypes can be replaced with assertThat<Type> variants in Assertions to improve discoverability. However, the AssertionsForClassTypes full coverage might still be unnecessary, i.e., assertThatString(String) is not required as String cannot be subclassed.
As a target, we should:
- Converge on a single set of
assertThat methods positioned in Assertions
- Keep/add explicit
assertThat<Type> helpers only for concrete ambiguity cases, like assertThatIterable, assertThatCharSequence, assertThatDate, etc., making sure we provide the full coverage of AssertionsForInterfaceTypes and cherry-pick what's really required from AssertionsForClassTypes
- Deprecate the split classes in 3.x, and remove them in 4.0
References
TL;DR
We currently expose overlapping
assertThatentry points acrossAssertions,AssertionsForClassTypes, andAssertionsForInterfaceTypes(plus additionalassertThat<Type>variants), which can be confusing for users.For example, we mention in the README:
and in the user guide:
However, when trying to statically import
assertThat()on 3.27.7, users see:Per JLS §15.12.2.5 (most-specific method selection) and JLS §4.10.2 (class/interface supertypes), class-specific overloads already win with a concrete class value. Ambiguity can appear:
CharBuffermatching bothCharSequenceandComparable)<T extends X>whereXis a class that also participates in interface-based overload competitionGiven this, both
AssertionsForClassTypesandAssertionsForInterfaceTypescan be replaced withassertThat<Type>variants inAssertionsto improve discoverability. However, theAssertionsForClassTypesfull coverage might still be unnecessary, i.e.,assertThatString(String)is not required asStringcannot be subclassed.As a target, we should:
assertThatmethods positioned inAssertionsassertThat<Type>helpers only for concrete ambiguity cases, likeassertThatIterable,assertThatCharSequence,assertThatDate, etc., making sure we provide the full coverage ofAssertionsForInterfaceTypesand cherry-pick what's really required fromAssertionsForClassTypesReferences