Document benefits of MessageSupplier in Assertions Issue: junit-team#…

…3153

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

@@ -39,6 +39,16 @@ class AssertionsDemo {
 	@Test
 	void standardAssertions() {
 		assertEquals(2, calculator.add(1, 1));
+		assertEquals(4, calculator.multiply(2, 2),
+				"The optional failure message is now the last parameter");
+		// When third parameter is used as message supplier (lambda expression)
+		// it will be lazily evaluated, only when the assertion fails.
+		assertTrue('a' < 'b', () -> "Assertion messages can be lazily evaluated -- "
+				+ "to avoid constructing complex messages unnecessarily.");
+	}
+
+	@Test
+	void assertWithMessageSupplier() {
 		// When assertion failure message is used as a plain expression,
 		// the expression will be evaluated irrespective of the assertion result.
 		assertEquals(4, calculator.multiply(2, 2),