Improve beneathPath to work with multiple matches with common structure

Closes gh-473

spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/FieldPathPayloadSubsectionExtractorTests.java

@@ -17,7 +17,6 @@
 package org.springframework.restdocs.payload;
 
 import java.io.IOException;
-import java.util.List;
 import java.util.Map;
 
 import com.fasterxml.jackson.core.JsonParseException;
@@ -30,7 +29,6 @@ import org.junit.rules.ExpectedException;
 import org.springframework.http.MediaType;
 
 import static org.assertj.core.api.Assertions.assertThat;
-import static org.hamcrest.CoreMatchers.equalTo;
 
 /**
  * Tests for {@link FieldPathPayloadSubsectionExtractor}.
@@ -55,20 +53,6 @@ public class FieldPathPayloadSubsectionExtractorTests {
 		assertThat(extracted.get("c")).isEqualTo(5);
 	}
 
-	@Test
-	@SuppressWarnings("unchecked")
-	public void extractMultiElementArraySubsectionOfJsonMap()
-			throws JsonParseException, JsonMappingException, IOException {
-		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a")
-				.extractSubsection("{\"a\":[{\"b\":5},{\"b\":4}]}".getBytes(),
-						MediaType.APPLICATION_JSON);
-		List<Map<String, Object>> extracted = new ObjectMapper()
-				.readValue(extractedPayload, List.class);
-		assertThat(extracted.size()).isEqualTo(2);
-		assertThat(extracted.get(0).get("b")).isEqualTo(5);
-		assertThat(extracted.get(1).get("b")).isEqualTo(4);
-	}
-
 	@Test
 	@SuppressWarnings("unchecked")
 	public void extractSingleElementArraySubsectionOfJsonMap()
@@ -76,10 +60,23 @@ public class FieldPathPayloadSubsectionExtractorTests {
 		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a.[]")
 				.extractSubsection("{\"a\":[{\"b\":5}]}".getBytes(),
 						MediaType.APPLICATION_JSON);
-		List<Map<String, Object>> extracted = new ObjectMapper()
-				.readValue(extractedPayload, List.class);
+		Map<String, Object> extracted = new ObjectMapper().readValue(extractedPayload,
+				Map.class);
 		assertThat(extracted.size()).isEqualTo(1);
-		assertThat(extracted.get(0).get("b")).isEqualTo(5);
+		assertThat(extracted).containsOnlyKeys("b");
+	}
+
+	@Test
+	@SuppressWarnings("unchecked")
+	public void extractMultiElementArraySubsectionOfJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a")
+				.extractSubsection("{\"a\":[{\"b\":5},{\"b\":4}]}".getBytes(),
+						MediaType.APPLICATION_JSON);
+		Map<String, Object> extracted = new ObjectMapper().readValue(extractedPayload,
+				Map.class);
+		assertThat(extracted.size()).isEqualTo(1);
+		assertThat(extracted).containsOnlyKeys("b");
 	}
 
 	@Test
@@ -96,13 +93,26 @@ public class FieldPathPayloadSubsectionExtractorTests {
 	}
 
 	@Test
-	public void extractMapSubsectionFromMultiElementArrayInAJsonMap()
+	@SuppressWarnings("unchecked")
+	public void extractMapSubsectionWithCommonStructureFromMultiElementArrayInAJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a.[].b")
+				.extractSubsection(
+						"{\"a\":[{\"b\":{\"c\":5}},{\"b\":{\"c\":6}}]}".getBytes(),
+						MediaType.APPLICATION_JSON);
+		Map<String, Object> extracted = new ObjectMapper().readValue(extractedPayload,
+				Map.class);
+		assertThat(extracted.size()).isEqualTo(1);
+		assertThat(extracted).containsOnlyKeys("c");
+	}
+
+	@Test
+	public void extractMapSubsectionWithVaryingStructureFromMultiElementArrayInAJsonMap()
 			throws JsonParseException, JsonMappingException, IOException {
 		this.thrown.expect(PayloadHandlingException.class);
-		this.thrown.expectMessage(
-				equalTo("a.[].b does not uniquely identify a subsection of the payload"));
+		this.thrown.expectMessage("The following uncommon paths were found: [a.[].b.d]");
 		new FieldPathPayloadSubsectionExtractor("a.[].b").extractSubsection(
-				"{\"a\":[{\"b\":{\"c\":5}},{\"b\":{\"c\":6}}]}".getBytes(),
+				"{\"a\":[{\"b\":{\"c\":5}},{\"b\":{\"c\":6, \"d\": 7}}]}".getBytes(),
 				MediaType.APPLICATION_JSON);
 	}
 

spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/JsonFieldPathsTests.java

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2014-2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.restdocs.payload;
+
+import java.io.IOException;
+import java.util.Arrays;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link JsonFieldPaths}.
+ *
+ * @author Andy Wilkinson
+ */
+public class JsonFieldPathsTests {
+
+	@Test
+	public void noUncommonPathsForSingleItem() {
+		assertThat(JsonFieldPaths
+				.from(Arrays
+						.asList(json("{\"a\": 1, \"b\": [ { \"c\": 2}, {\"c\": 3} ]}")))
+				.getUncommon()).isEmpty();
+	}
+
+	@Test
+	public void noUncommonPathsForMultipleIdenticalItems() {
+		Object item = json("{\"a\": 1, \"b\": [ { \"c\": 2}, {\"c\": 3} ]}");
+		assertThat(JsonFieldPaths.from(Arrays.asList(item, item)).getUncommon())
+				.isEmpty();
+	}
+
+	@Test
+	public void noUncommonPathsForMultipleMatchingItemsWithDifferentScalarValues() {
+		assertThat(JsonFieldPaths
+				.from(Arrays.asList(
+						json("{\"a\": 1, \"b\": [ { \"c\": 2}, {\"c\": 3} ]}"),
+						json("{\"a\": 4, \"b\": [ { \"c\": 5}, {\"c\": 6} ]}")))
+				.getUncommon()).isEmpty();
+	}
+
+	@Test
+	public void missingEntryInMapIsIdentifiedAsUncommon() {
+		assertThat(JsonFieldPaths.from(Arrays.asList(json("{\"a\": 1}"),
+				json("{\"a\": 1}"), json("{\"a\": 1, \"b\": 2}"))).getUncommon())
+						.containsExactly("b");
+	}
+
+	@Test
+	public void missingEntryInNestedMapIsIdentifiedAsUncommon() {
+		assertThat(
+				JsonFieldPaths
+						.from(Arrays.asList(json("{\"a\": 1, \"b\": {\"c\": 1}}"),
+								json("{\"a\": 1, \"b\": {\"c\": 1}}"),
+								json("{\"a\": 1, \"b\": {\"c\": 1, \"d\": 2}}")))
+						.getUncommon()).containsExactly("b.d");
+	}
+
+	@Test
+	public void missingEntriesInNestedMapAreIdentifiedAsUncommon() {
+		assertThat(
+				JsonFieldPaths.from(Arrays.asList(json("{\"a\": 1, \"b\": {\"c\": 1}}"),
+						json("{\"a\": 1, \"b\": {\"c\": 1}}"),
+						json("{\"a\": 1, \"b\": {\"d\": 2}}"))).getUncommon())
+								.containsExactly("b.c", "b.d");
+	}
+
+	@Test
+	public void missingEntryBeneathArrayIsIdentifiedAsUncommon() {
+		assertThat(JsonFieldPaths.from(Arrays.asList(json("[{\"b\": 1}]"),
+				json("[{\"b\": 1}]"), json("[{\"b\": 1, \"c\": 2}]"))).getUncommon())
+						.containsExactly("[].c");
+	}
+
+	@Test
+	public void missingEntryBeneathNestedArrayIsIdentifiedAsUncommon() {
+		assertThat(JsonFieldPaths.from(Arrays.asList(json("{\"a\": [{\"b\": 1}]}"),
+				json("{\"a\": [{\"b\": 1}]}"), json("{\"a\": [{\"b\": 1, \"c\": 2}]}")))
+				.getUncommon()).containsExactly("a.[].c");
+	}
+
+	private Object json(String json) {
+		try {
+			return new ObjectMapper().readValue(json, Object.class);
+		}
+		catch (IOException ex) {
+			throw new RuntimeException(ex);
+		}
+	}
+
+}

spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/ResponseFieldsSnippetTests.java

@@ -94,6 +94,19 @@ public class ResponseFieldsSnippetTests extends AbstractSnippetTests {
 						.row("`b`", "`Number`", "one").row("`c`", "`String`", "two"));
 	}
 
+	@Test
+	public void subsectionOfMapResponseBeneathAnArray() throws IOException {
+		responseFields(beneathPath("a.b.[]"), fieldWithPath("c").description("one"),
+				fieldWithPath("d.[].e").description("two"))
+						.document(this.operationBuilder.response().content(
+								"{\"a\": {\"b\": [{\"c\": 1, \"d\": [{\"e\": 5}]}, {\"c\": 3, \"d\": [{\"e\": 4}]}]}}")
+								.build());
+		assertThat(this.generatedSnippets.snippet("response-fields-beneath-a.b.[]"))
+				.is(tableWithHeader("Path", "Type", "Description")
+						.row("`c`", "`Number`", "one")
+						.row("`d.[].e`", "`Number`", "two"));
+	}
+
 	@Test
 	public void subsectionOfMapResponseWithCommonsPrefix() throws IOException {
 		responseFields(beneathPath("a"))