Consider documenting AssertProvider interface

[jmaniquet]

Hi AssertJ team

Thanks for this wonderful tool, I use it a lot.

I recently contributed a small change on the AssertJ DB library, an AssertJ-inspired library used to perform assertions on the state of a database.

The goal was to be able to use both AssertJ Core assertions and AssertJ DB assertions in the same class, without having a double import problem that looks like this :

import static org.assertj.db.api.Assertions.assertThat;
import org.assertj.core.api.Assertions;
...
myDao.insert(stuff);
Request request = assertDbConnection
                .request("select foo from bar where toto = ?")
                .parameters("dummy")
                .build();
RequestAssert assert = assertThat(request); // static import there - which is what I would like everywhere
// perform some db assertion there
...
String t = myDao.selectStuff();
Assertions.assertThat(t).isEqualTo(...); // non static import there - both static import with same method name can't coexist

See assertj/assertj-db#329 for more details .

I suggested using the AssertProvider interface to solve that problem, and the suggestion was accepted.
I had the idea by looking at Spring Boot controller test support : one of their object implements this interface, and doing assertions on the results of the request integrate seamlessly with basic assertThat static import.

From that, my understanding of that interface was that it is intended to allow custom assertions from other sources/frameworks to integrate seamlessly with the basic AssertJ Core assertThat import.

Now I may be wrong with that assumption.
I checked the AssertJ Core documentation anyway, and could not find any mention of that interface.
So I feel like it could use some better documentation.

It looks like it could be very useful for other Assertj-based libraries, yet it does not seem really used.
I checked some, and though I do not use them, they would meet the same double import problem I had with Assertj DB :

• AssertJ Guava provides its own Assertions.assertThat class/method - I found no AssertProvider in the code base
• VavrAssertions provides VavrAssertions.assertThat - same
  There are others that do not seem to be maintained, like AssertJ-Swing, but had the same characteristics.

So the goal of this ticket would be to provide documentation for the AssertProvider interface:

• At least its goal
• Some example usage

If the goal is indeed for other frameworks to integrate more easily :

• Documentation should made that clear
• Maybe it should discourage them to provide their own assertThat entry point - the AssertJ DB side may deprecate their own in the future, following the change
• It could also mention framework that already do (to my knowledge : Spring Boot, and AssertJ DB with its next release)
• Some other places where AssertProvider is used as input could probably be covered to - for example AssertJ DB also provides a BDDAssertions.then similar to AssertJ Core BDDAssertions.then which has the same problem (not sure if there are others)

If it is not the goal, and that usage is a bad idea, maybe the documentation should discourage that usage (that would mean my idea was bad)

If by chance I missed something in the documentation, thanks in advance for pointing it to me; that ticket would be moot obviously.

Regards

[scordio]

Thanks for raising it, @jmaniquet! You're totally right, AssertProvider is missing in the user guide.