Replace Hamcrest example with AssertJ in User Guide

This commit also adds a "tip" about using AssertJ's Assumptions support.

Closes #5050

Author: sbrannen

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

@@ -513,33 +513,22 @@ include::{kotlinTestDir}/example/KotlinAssertionsDemo.kt[tags=user_guide]
 ==== Third-party Assertion Libraries
 
 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.
+testing scenarios, there are times when more power and additional functionality 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.
 
-For example, the combination of _matchers_ and a fluent API can be used to make
-assertions more descriptive and readable. However, JUnit Jupiter's `{Assertions}` class
-does not provide an
-https://junit.org/junit4/javadoc/latest/org/junit/Assert.html#assertThat[`assertThat()`]
-method like the one found in JUnit 4's `org.junit.Assert` class which accepts a Hamcrest
-https://junit.org/junit4/javadoc/latest/org/hamcrest/Matcher.html[`Matcher`]. Instead,
-developers are encouraged to use the built-in support for matchers provided by third-party
-assertion libraries.
-
-The following example demonstrates how to use the `assertThat()` support from Hamcrest in
-a JUnit Jupiter test. As long as the Hamcrest library has been added to the classpath,
-you can statically import methods such as `assertThat()`, `is()`, and `equalTo()` and
-then use them in tests like in the `assertWithHamcrestMatcher()` method below.
+For example, the following demonstrates how to use the `assertThat()` support from AssertJ
+in a JUnit Jupiter test. As long as the AssertJ library has been added to the classpath,
+you can statically import methods such as `assertThat()`, `assertThatException()`, etc.
+from `org.assertj.core.api.Assertions` and then use them in tests like in the
+`assertWithAssertJ()` method below.
 
 [source,java,indent=0]
 ----
-include::{testDir}/example/HamcrestAssertionsDemo.java[tags=user_guide]
+include::{testDir}/example/AssertJAssertionsDemo.java[tags=user_guide]
 ----
 
-Naturally, legacy tests based on the JUnit 4 programming model can continue using
-`org.junit.Assert#assertThat`.
-
 [TIP]
 .Excluding Jupiter’s Assertions From a Project’s Classpath
 ====
@@ -594,6 +583,11 @@ NOTE: It is also possible to use methods from JUnit 4's `org.junit.Assume` class
 assumptions. Specifically, JUnit Jupiter supports JUnit 4's `AssumptionViolatedException`
 to signal that a test should be aborted instead of marked as a failure.
 
+TIP: If you use AssertJ for assertions, you may also wish to use AssertJ for assumptions.
+To do so, you can statically import the `assumeThat()` method from
+`org.assertj.core.api.Assumptions` and then use AssertJ's fluent API to specify your
+assumptions.
+
 [[writing-tests-exceptions]]
 === Exception Handling
 

documentation/src/test/java/example/HamcrestAssertionsDemo.java renamed to documentation/src/test/java/example/AssertJAssertionsDemo.java

@@ -11,21 +11,19 @@
 package example;
 
 // tag::user_guide[]
-import static org.hamcrest.CoreMatchers.equalTo;
-import static org.hamcrest.CoreMatchers.is;
-import static org.hamcrest.MatcherAssert.assertThat;
+import static org.assertj.core.api.Assertions.assertThat;
 
 import example.util.Calculator;
 
 import org.junit.jupiter.api.Test;
 
-class HamcrestAssertionsDemo {
+class AssertJAssertionsDemo {
 
 	private final Calculator calculator = new Calculator();
 
 	@Test
-	void assertWithHamcrestMatcher() {
-		assertThat(calculator.subtract(4, 1), is(equalTo(3)));
+	void assertWithAssertJ() {
+		assertThat(calculator.subtract(4, 1)).isEqualTo(3);
 	}
 
 }