Document benefits of messageSupplier in Assertions

[ankitwasankar]

Overview

Documented the benefits of MessageSupplier in assertion, as per the discussion on issue #3153

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide and Release Notes

[sbrannen]

Let's take a different approach.

I actually like the original text in the assertion failure messages (perhaps because I wrote them), and I think we should keep that content.

So, let's move that text to a new paragraph before the example code in the User Guide, and let's incorporate some of the text you wrote in the same paragraph -- in other words, combine the existing text with your text to come up with something more comprehensive.

After doing that, let's go back to an example similar to the one you proposed in #3153 (comment). Having plain strings in both variants (String and Supplier<String>) is what was wrong with the example to begin with. Using a lambda expression or method reference for the messageSupplier will make it much easier to explain the benefits.

[ankitwasankar]

@sbrannen - thank you for the review comment, I have updated the code.
Please let me know if you think something needs to be added or removed.

[sbrannen]

Hi @ankitwasankar,

I think you misunderstood what I was requesting, so I'll restate that here.

I like the original text in the assertion failure messages (perhaps because I wrote them), and I think we should keep that content.

By "content" I mean the text/explanation which should retain mostly intact but in the "Assertions" section of the User Guide, not in the included AssertionsDemo code as inline comments.

So, let's move that text to a new paragraph before the example code in the User Guide, and let's incorporate some of the text you wrote in the same paragraph -- in other words, combine the existing text with your text to come up with something more comprehensive.

I'd still like to see this.

After doing that, let's go back to an example similar to the one you proposed in #3153 (comment). Having plain strings in both variants (String and Supplier) is what was wrong with the example to begin with.

That last part is the most important. There is no point in having a static string returned from a lambda expression.

The whole reason we support a messageSupplier is to avoid unnecessary creation of dynamic strings.

Please note as well that the concatenation of two static strings does not constitute a dynamic strings since the compiler will likely convert them to a single static string during compilation.

Using a lambda expression or method reference for the messageSupplier will make it much easier to explain the benefits.

Again, that's what we're trying to convey here, and your getMessage() example in #3153 (comment) achieves that.

I think we can also remove the assertWithMessageSupplier() test method and include all "standard assertions" in the existing standardAssertions() method.

Please make the necessary changes to achieve the above.

Thanks!

[marcphilipp]

Closing in favor of #3153.