Document benefits of messageSupplier in Assertions (#3938)

Resolves #3153.

Author: chris-carneiro

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -293,6 +293,13 @@ JUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds
 that lend themselves well to being used with Java 8 lambdas. All JUnit Jupiter assertions
 are `static` methods in the `{Assertions}` class.
 
+Assertion methods optionally accept the assertion message as their third parameter, which
+can be either a `String` or a `Supplier<String>`.
+
+When using a `Supplier<String>` (e.g., a lambda expression), the message is evaluated
+lazily. This can provide a performance benefit, especially if message construction is
+complex or time-consuming, as it is only evaluated when the assertion fails.
+
 [source,java,indent=0]
 ----
 include::{testDir}/example/AssertionsDemo.java[tags=user_guide]

documentation/src/test/java/example/AssertionsDemo.java

@@ -41,8 +41,9 @@ void standardAssertions() {
 		assertEquals(2, calculator.add(1, 1));
 		assertEquals(4, calculator.multiply(2, 2),
 				"The optional failure message is now the last parameter");
-		assertTrue('a' < 'b', () -> "Assertion messages can be lazily evaluated -- "
-				+ "to avoid constructing complex messages unnecessarily.");
+
+		// Lazily evaluates generateFailureMessage('a','b').
+		assertTrue('a' < 'b', () -> generateFailureMessage('a','b'));
 	}
 
 	@Test
@@ -160,6 +161,10 @@ private static String greeting() {
 		return "Hello, World!";
 	}
 
+	private static String generateFailureMessage(char a, char b) {
+		return "Assertion messages can be lazily evaluated -- "
+				+ "to avoid constructing complex messages unnecessarily." + (a < b);
+	}
 }
 // end::user_guide[]
 // @formatter:on