From cc0214488a429ed5bbdb97b4967c4e3b860bf1e5 Mon Sep 17 00:00:00 2001 From: kalle Date: Mon, 24 Jan 2011 21:11:52 +0100 Subject: [PATCH] Improved documentation --- .../jayway/jsonassert/impl/JSONAsserter.java | 67 +++++++++++++++++-- .../jayway/jsonassert/impl/JSONReader.java | 2 +- .../jayway/jsonassert/JSONAsserterTest.java | 14 +++- .../com/jayway/jsonassert/JSONReaderTest.java | 9 ++- 4 files changed, 83 insertions(+), 9 deletions(-) diff --git a/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONAsserter.java b/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONAsserter.java index 29837790..dacde631 100644 --- a/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONAsserter.java +++ b/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONAsserter.java @@ -17,34 +17,93 @@ public class JSONAsserter { private final JSONReader reader; + /** + * Creates a new instance of a JSONAsserter that can be used to make + * assertions on the provided JSON document or array. + * + * @param json the JSON document to create a JSONAsserter for + * @return a JSON asserter initialized with the provided document + * @throws ParseException + */ public static JSONAsserter with(String json) throws ParseException { return new JSONAsserter(JSONReader.parse(json)); } + /** + * Instantiates a new JSONAsserter + * + * @param reader initialized with the JSON document to be asserted upon + */ private JSONAsserter(JSONReader reader) { this.reader = reader; } + /** + * Asserts that object specified by path satisfies the condition specified by matcher. + * If not, an AssertionError is thrown with information about the matcher + * and failing value. Example: + *

+ * + * with(json).assertThat("items[0].name", equalTo("Bobby")) + * .assertThat("items[0].age" , equalTo(24L)) + * + * + * @param path the json path specifying the value being compared + * @param matcher an expression, built of Matchers, specifying allowed values + * @param the static type accepted by the matcher + * @return this to allow fluent assertion chains + */ public JSONAsserter assertThat(String path, Matcher matcher) { - MatcherAssert.assertThat((T) reader.get(path), matcher); - return this; } + /** + * Asserts that object specified by path is equal to the expected value. + * If they are not, an AssertionError is thrown with the given message. + * + * @param path the json path specifying the value being compared + * @param expected the expected value + * @param the static type that should be returned by the path + * @return this to allow fluent assertion chains + */ public JSONAsserter assertEquals(String path, T expected) { return assertThat(path, equalTo(expected)); } - public JSONAsserter assertNull(String path) { + /** + * Asserts that object specified by path is null. If it is not, an AssertionError + * is thrown with the given message. + * + * @param path the json path specifying the value that should be null + * @return this to allow fluent assertion chains + */ + public JSONAsserter assertNull(String path) { return assertThat(path, nullValue()); } + /** + * Asserts that object specified by path is NOT null. If it is, an AssertionError + * is thrown with the given message. + * + * @param path the json path specifying the value that should be NOT null + * @return this to allow fluent assertion chains + */ public JSONAsserter assertNotNull(String path) { return assertThat(path, notNullValue()); } - public JSONAsserter and(){ + /** + * Syntactic sugar to allow chaining assertions with a separating and() statement + *

+ *

+ * + * with(json).assertThat("firstName", is(equalTo("Bobby"))).and().assertThat("lastName", is(equalTo("Ewing"))) + * + * + * @return this to allow fluent assertion chains + */ + public JSONAsserter and() { return this; } diff --git a/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONReader.java b/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONReader.java index 735db905..57a07b4e 100644 --- a/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONReader.java +++ b/json-assert/src/main/java/com/jayway/jsonassert/impl/JSONReader.java @@ -63,7 +63,7 @@ public class JSONReader { return getByPath(Boolean.class, path); } - public List getList(String path) { + public List getList(String path) { return getByPath(List.class, path); } diff --git a/json-assert/src/test/java/com/jayway/jsonassert/JSONAsserterTest.java b/json-assert/src/test/java/com/jayway/jsonassert/JSONAsserterTest.java index 1f77d22a..c47f1348 100644 --- a/json-assert/src/test/java/com/jayway/jsonassert/JSONAsserterTest.java +++ b/json-assert/src/test/java/com/jayway/jsonassert/JSONAsserterTest.java @@ -21,6 +21,18 @@ public class JSONAsserterTest { JSONAsserter.with(TEST_DOCUMENT).assertThat("stringField", equalTo("string-field")); } + @Test + public void array_content_can_be_asserted_with_matcher() throws Exception { + + JSONAsserter.with(TEST_DOCUMENT).assertThat("stringList", hasItems("ONE", "TWO")); + } + + @Test + public void map_content_can_be_asserted_with_matcher() throws Exception { + + JSONAsserter.with(TEST_DOCUMENT).assertThat("subDocument", hasEntry("subField", "sub-field")); + } + @Test public void a_path_can_be_asserted_equal_to() throws Exception { @@ -54,6 +66,4 @@ public class JSONAsserterTest { } - - } diff --git a/json-assert/src/test/java/com/jayway/jsonassert/JSONReaderTest.java b/json-assert/src/test/java/com/jayway/jsonassert/JSONReaderTest.java index 992ef5af..a9de5c80 100644 --- a/json-assert/src/test/java/com/jayway/jsonassert/JSONReaderTest.java +++ b/json-assert/src/test/java/com/jayway/jsonassert/JSONReaderTest.java @@ -4,6 +4,7 @@ import com.jayway.jsonassert.impl.JSONReader; import org.junit.Test; import java.text.ParseException; +import java.util.List; import static org.junit.Assert.*; @@ -87,7 +88,9 @@ public class JSONReaderTest { public void a_list_can_be_accessed_in_a_document() throws Exception { JSONReader reader = JSONReader.parse(TEST_DOCUMENT); - assertEquals(2, reader.getList("stringList").size()); + List l = reader.getList("stringList"); + + assertEquals(2, l.size()); } @Test @@ -189,7 +192,9 @@ public class JSONReaderTest { public void array_wildcard_property_extract() throws Exception { JSONReader reader = JSONReader.parse(TEST_DOCUMENT); - assertEquals(2, reader.getList("objectList[*].subField").size()); + List l = reader.getList("objectList[*].subField"); + + assertEquals(2, l.size()); /*