Discussion: Switch the order of 'actual' and 'expected' in `Assertions` APIs

[mkobit]

One of the things that I find unnatural is the ordering in JUnit 4 assertions. They mostly all follow the assert(expected, actual) format. Hamcrest assertions have the reverse with actual, expected which has a more natural flow when reading the code (my opinion) and results in more fluent assertions. The Assertions class in the Jupiter API continues with the JUnit 4 style of expected, actual.

Most newer assertion frameworks now seem to follow the notion of putting the "actual", so I think it would be a good idea to follow that paradigm with JUnit 5 over using the existing assertion ordering that is present in JUnit 4.

[marcphilipp]

Thanks for bringing this up! We discussed this early in the project and decided against it for two reasons. First and foremost, we didn't want to increase the burden for migrating a test to the Jupiter API. Second, we think that people who use assertEquals are used to that order by now. Thus, we think reversing the order would do more harm than good.

Please note that we only consider Assertions as a basic set of assertions. As stated in the User Guide, you almost always want to use a more powerful assertion library:

Even though the assertion facilities provided by JUnit Jupiter are sufficient for many testing scenarios, there are times when more power and additional functionality such as matchers are desired or required. In such cases, the JUnit team recommends the use of third-party assertion libraries such as AssertJ, Hamcrest, Truth, etc. Developers are therefore free to use the assertion library of their choice.