fix #679: Add on fail message builder for response specification

examples/rest-assured-itest-java/src/test/java/io/restassured/itest/java/ErrorMessageITest.java

@@ -92,6 +92,28 @@ public class ErrorMessageITest extends WithJetty {
                 get("/lotto");
     }
 
+    @Test public void
+    error_message_look_ok_with_on_fail_message() {
+        exception.expect(AssertionError.class);
+        exception.expectMessage("2 expectations failed.\n" +
+                "JSON path lotto.lottoId doesn't match.\n" +
+                "Expected: a value less than <2>\n" +
+                "  Actual: <5>\n" +
+                "\n" +
+                "JSON path lotto.winning-numbers doesn't match.\n" +
+                "Expected: a collection containing <21>\n" +
+                "  Actual: <[2, 45, 34, 23, 7, 5, 3]>\n" +
+                "\n" +
+                "On fail message: An additional information to find the cause of the error");
+
+        expect().
+                body("lotto.lottoId", lessThan(2)).
+                body("lotto.winning-numbers", hasItem(21)).
+                onFailMessage("An additional information to find the cause of the error").
+                when().
+                get("/lotto");
+    }
+
     @Test public void
     error_message_with_failed_xpath_expected_looks_ok() {
         exception.expect(AssertionError.class);

rest-assured/src/main/groovy/io/restassured/internal/ResponseSpecificationImpl.groovy

@@ -61,6 +61,7 @@ class ResponseSpecificationImpl implements FilterableResponseSpecification {
   private Tuple2<Matcher<Long>, TimeUnit> expectedResponseTime;
   private LogDetail responseLogDetail
   private boolean forceDisableEagerAssert = false
+  private String onFailMessage
 
   private contentParser
   LogRepository logRepository
@@ -311,6 +312,11 @@ class ResponseSpecificationImpl implements FilterableResponseSpecification {
     this
   }
 
+  ResponseSpecification onFailMessage(String message) {
+    this.onFailMessage = message
+    this
+  }
+
   LogDetail getLogDetail() {
     responseLogDetail
   }
@@ -490,11 +496,15 @@ class ResponseSpecificationImpl implements FilterableResponseSpecification {
           fireFailureListeners(response)
           def errorMessage = errors.collect { it.errorMessage }.join("\n")
           def s = numberOfErrors > 1 ? "s" : ""
-          throw new AssertionError("$numberOfErrors expectation$s failed.\n$errorMessage")
+          throw new AssertionError("$numberOfErrors expectation$s failed.\n$errorMessage$formattedOnFailMessage")
         }
       }
     }
 
+    private String getFormattedOnFailMessage() {
+      onFailMessage ? "\nOn fail message: $onFailMessage" : ""
+    }
+
     private void fireFailureListeners(Response response) {
       config.getFailureConfig().getFailureListeners().each {
         it.onFailure(

rest-assured/src/main/java/io/restassured/specification/ResponseSpecification.java

@@ -1011,4 +1011,16 @@ default ResponseSpecification detachRoot(String pathToDetach) {
      * @param logDetail The log detail
      */
     ResponseSpecification logDetail(LogDetail logDetail);
+
+    /**
+     * Add user message to final mismatch description.
+     * <p/>
+     * This is useful when you need to associate a mismatch description with additional user information. For example, in parallel execution.
+     * <p/>
+     * Note, if you want to add a description for certain matching, not for all, you should use something like
+     * Hamcrest wrapper matcher - {@link org.hamcrest.CoreMatchers#describedAs}.
+     *
+     * @param message The user message
+     */
+    ResponseSpecification onFailMessage(String message);
 }