Guidelines for third party libraries

[ascopes]

Just wondering if there is any existing guidelines for third party libearies to use to implement custom assertions that build on top of AssertJ.

For example, I have the lib I have been working on which uses AssertJ heavily, but it is hard to tell if I am using the right types or not, or whether there is a better way to achieve what I am doing.

Mostly just curious, as it would be invaluable if any resources or ways of getting feedback exist!

[joel-costigliola]

We have guidelines for writing your own assertions class: https://assertj.github.io/doc/#assertj-core-custom-assertions, but not really something at the library level.

[ascopes]

Cool, will take a look. Thanks!

[ascopes]

So effectively we should prefer providing static assertThat methods on each class rather than a constructor to handle them?

When I integrated with AssertJ, I provided a static class similar to the Assertions/BDDAssertions class AssertJ provides (https://ascopes.github.io/java-compiler-testing/io.github.ascopes.jct/io/github/ascopes/jct/assertions/JctAssertions.html).

One thing I was concerned about was shadowing the AssertJ imports in places where an end user may also wish to make use of AssertJ assertions as well, so I provided a set of explicitly named overloads as well (e.g. assertThat(JctCompilation) is shorthand for assertThatCompilation(JctCompilation)).

Is there a better way of doing this, or does this sound mostly reasonable (without being too jarring for someone who is familiar with AssertJ?)

[scordio]

With version 4 I have in mind to reduce the visibility of all the concrete Assert implementations to package-private. This would clearly show that Assertions / BDDAssertions / WithAssertions are the way to get assertion instances. Also, as a cosmetic improvement, I would remove the Abstract prefix from all the existing abstract classes. This is my personal view and needs further discussion with the team.

About shadowing, your custom class could extend Assertions where possible or implement WithAssertions. Would this help?

[joel-costigliola]

WithAssertions is a good alternative to get access to assertThat in a non static way, we found at the time that having a custom Assertions class inheriting AssertJ's own Assertions class was not super handy (it kinda works ok if you have a single entry point class but if you have several it does not work well).

[ascopes]

That works well, thanks!