JUnit 6: Swap `expected` and `actual` parameters for Assertions

[bjmi]

The vast majority of Assertion libraries for Java make assertions in the order
actual to expected.

• AssertJ
• Hamcrest
• Truth
• Atrium
• TestNG
  (Kotlin: Kotest, kotlinx-assertions, Strikt)

With the introduction of JUnit 6, it would be now possible to incorporating this into JUnit.

When we first introduced assertEquals in JUnit Jupiter, I copied and modified the existing logic from JUnit 4.
There was no rationale other than keeping it similar to JUnit 4.
Ref: #3120 (comment)

Now there is an opportunity to fix this. :)

Refs

• Invert equality check? #3120
• Discussion: Switch the order of 'actual' and 'expected' in Assertions APIs #623

[sormuras]

I'd rather see an API that makes the role explicit instead of relying on parameter positions - and IDEs providing parameter names as hints.

• Actual.of("").equals(new String(""));
• Actual.of("").is(String::isEmpty);

...

Wait! There's https://assertj.github.io 😉

[marcphilipp]

The vast majority of Assertion libraries for Java make assertions in the order
actual to expected.

Well, not exactly. They take actual and then have APIs to specify what's expected. As @sormuras pointed out above there are certainly advantages to that and it allows for more expressive and powerful assertions. JUnit Jupiter's assertions are meant to be "good enough" to write tests but we also use AssertJ in our own test suite.

[marcphilipp]

Team decision: We don't think there's a clear benefit to inverting the current parameter order as more people are likely familiar with the current order. Moreover, it would be a major breaking change for anyone using assertEquals and require them to modify their code, ideally via some automation (e.g. an OpenRewrite recipe).