* Added Javadoc to CollectionMatcher and MapMatcher

* Null values can now be passed to CollectionMatcher and MapMatcher
* Added generic type parameters to MapMatcher
* Added CollectionMatcher, MapMatcher and DateMatcher documentation to README.md

oleaster-matcher/README.md

@@ -136,6 +136,42 @@ expect("foobar").toMatch("fo+\\w*");
 
 For comparing Strings [StringMatcher](https://github.com/mscharhag/oleaster/blob/master/oleaster-matcher/src/main/java/com/mscharhag/oleaster/matcher/matchers/StringMatcher.java) will be used.
 
+## Collections
+
+```
+// check if a collection contains a specific item
+expect(myList).toContain("my item");
+expect(mySet).toNotContain(42);
+
+// check the size of a collection
+expect(myList).toBeEmpty();
+expect(mySet).toHaveSize(15);
+```
+
+### Maps
+
+```
+// check if a map contains a specific key
+expect(myMap).toContainKey("key");
+
+// check if a map contains a specific value
+expect(myMap).toContainValue("value");
+```
+
+## Date and Time
+
+```
+// check if a date is before or after another date
+expect(date).toBeAfter(otherDate);
+expect(date).toBeBefore(otherDate);
+
+// check if a date is between two other dates
+expect(date).toBeBetween(firstDate, otherDate);
+
+// check if a date is close to another date
+expect(date).toBeCloseTo(otherDate, deltaInMillis );
+```
+
 ## Exceptions
 To test exceptions you just have to wrap the code that throws the expected exception into a lambda expression and pass
 it to `expect()`. The lambda expression will be executed and thrown exceptions will be caught.

oleaster-matcher/src/main/java/com/mscharhag/oleaster/matcher/Matchers.java

@@ -210,15 +210,16 @@ public static CollectionMatcher expect(Collection value) {
 	 * <p>The returned matcher can be used to check {@code Map} values.
 	 * <pre>
 	 *     expect(map).toContainValue("foo");
-	 *     expect(map).toHaveLength(3);
+	 *     expect(map).toHaveSize(3);
 	 * </pre>
 	 * @see com.mscharhag.oleaster.matcher.matchers.MapMatcher
 	 * @param value the value that should be checked
 	 * @return a new {@code MapMatcher} initialized with {@code value}
 	 */
-	public static MapMatcher expect(Map value) {
-		return new MapMatcher(value);
+	public static <K, V> MapMatcher<K, V> expect(Map<K, V> value) {
+		return new MapMatcher<>(value);
 	}
+
 	/**
 	 * Creates a new {@link com.mscharhag.oleaster.matcher.matchers.ObjectMatcher} initialized with
 	 * the passed {@code value}.

oleaster-matcher/src/main/java/com/mscharhag/oleaster/matcher/matchers/CollectionMatcher.java

@@ -4,43 +4,88 @@
 
 import java.util.Collection;
 
+import static com.mscharhag.oleaster.matcher.util.Expectations.expectNotNull;
 import static com.mscharhag.oleaster.matcher.util.Expectations.expectTrue;
 
 /**
  * Matcher class to validate Collections
  */
 public class CollectionMatcher extends ObjectMatcher<Collection> {
+
     public CollectionMatcher(final Collection value) {
         super(value);
-        Arguments.ensureNotNull(value, "Collection cannot be null");
     }
 
     /**
      * Checks if the stored {@code Collection} contains the provided item.
      * <p>This method throws an {@code AssertionError} if
      * <ul>
      *     <li>the stored {@code Collection} does not contain the passed {@code item}</li>
+     *     <li>the given {@code Collection} is {@code null}</li>
      * </ul>
      * </p>
      * @param item the {@code Object} which the {@code Collection} should contain.
      */
     public void toContain(final Object item) {
+        expectNotNull(this.getValue(), "Expected null to contain '%s'", item);
         expectTrue(this.getValue().contains(item), "Expected '%s' to contain '%s'", this.getValue(), item);
     }
 
+    /**
+     * Checks if the stored {@code Collection} does not contain the provided item.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Collection} does contain the passed {@code item}</li>
+     *     <li>the given {@code Collection} is {@code null}</li>
+     * </ul>
+     * </p>
+     * @param item the {@code Object} which the {@code Collection} should not contain.
+     */
     public void toNotContain(final Object item) {
+        expectNotNull(this.getValue(), "Expected null to not contain '%s'", item);
         expectTrue(!this.getValue().contains(item), "Expected '%s' to not contain '%s'", this.getValue(), item);
     }
 
+    /**
+     * Checks if the given {@code Collection} is empty
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Collection} is not empty</li>
+     *     <li>the given {@code Collection} is {@code null}</li>
+     * </ul>
+     */
     public void toBeEmpty() {
-        expectTrue(this.getValue().size() == 0, "Expected '%s' to be empty", this.getValue());
+        expectNotNull(this.getValue(), "Expected null to be empty");
+        expectTrue(this.getValue().isEmpty(), "Expected '%s' to be empty", this.getValue());
     }
 
+    /**
+     * Checks if the given {@code Collection} is not empty
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Collection} is empty</li>
+     *     <li>the given {@code Collection} is {@code null}</li>
+     * </ul>
+     */
     public void toNotBeEmpty() {
-        expectTrue(this.getValue().size() > 0, "Expected '%s' to not be empty", this.getValue());
+        expectNotNull(this.getValue(), "Expected null to not be empty");
+        expectTrue(!this.getValue().isEmpty(), "Expected '%s' to not be empty", this.getValue());
     }
 
-    public void toHaveLength(final int length) {
-        expectTrue(this.getValue().size() == length, "Expected '%s' to have a length of %d, instead has a length of %d", this.getValue(), length, this.getValue().size());
+    /**
+     * Checks if the given {@code Collection} has the expected size
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Collection} has a different size than the passed value</li>
+     *     <li>the stored {@code Collection} is {@code null}</li>
+     * </ul>
+     *
+     * </p>
+     * @param size The expected size of the collection
+     */
+    public void toHaveSize(final int size) {
+        expectNotNull(this.getValue(), "Expected null to have size '%d'", size);
+        expectTrue(this.getValue().size() == size, "Expected '%s' to have a size of %d, " +
+                "instead has a size of %d", this.getValue(), size, this.getValue().size());
     }
 }

oleaster-matcher/src/main/java/com/mscharhag/oleaster/matcher/matchers/MapMatcher.java

@@ -4,39 +4,106 @@
 
 import com.mscharhag.oleaster.matcher.util.Arguments;
 
+import static com.mscharhag.oleaster.matcher.util.Expectations.expectNotNull;
 import static com.mscharhag.oleaster.matcher.util.Expectations.expectTrue;
 
-public class MapMatcher extends ObjectMatcher<Map> {
-	public MapMatcher(final Map value) {
+/**
+ * Matcher class to validate {@link Map}s
+ */
+public class MapMatcher<K, V> extends ObjectMatcher<Map<K, V>> {
+
+	public MapMatcher(final Map<K, V> value) {
 		super(value);
-		Arguments.ensureNotNull(value, "Map cannot be null");
 	}
 
+    /**
+     * Checks if the stored {@code Map} is empty.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} is not empty</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
 	public void toBeEmpty() {
-	  expectTrue(this.getValue().size() == 0, "Expected '%s' to be empty", this.getValue());
+	    expectNotNull(this.getValue(), "Expected null to be empty");
+	    expectTrue(this.getValue().isEmpty(), "Expected '%s' to be empty", this.getValue());
 	}
 
+    /**
+     * Checks if the stored {@code Map} is not empty.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} is empty</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
 	public void toNotBeEmpty() {
-		expectTrue(this.getValue().size() > 0, "Expected '%s' to not be empty", this.getValue());
+        expectNotNull(this.getValue(), "Expected null to not be empty");
+		expectTrue(!this.getValue().isEmpty(), "Expected '%s' to not be empty", this.getValue());
 	}
 
-	public void toContainKey(final Object key) {
+    /**
+     * Checks if the stored {@code Map} contains the given {@code key}.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} does not contain the given {@code key}</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
+	public void toContainKey(final K key) {
+        expectNotNull(this.getValue(), "Expected null to contain the key '%s'", key);
 		expectTrue(this.getValue().containsKey(key), "Expected '%s' to contain key '%s'", this.getValue(), key);
 	}
 
-	public void toNotContainKey(final Object key) {
+    /**
+     * Checks if the stored {@code Map} does not contain the given {@code key}.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} contains the given {@code key}</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
+	public void toNotContainKey(final K key) {
+        expectNotNull(this.getValue(), "Expected null to not contain the key '%s'", key);
 		expectTrue(!this.getValue().containsKey(key), "Expected '%s' to not contain key '%s'", this.getValue(), key);
 	}
 
-	public void toContainValue(final Object value) {
+    /**
+     * Checks if the stored {@code Map} contains the given {@code value}.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} does not contain the given {@code value}</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
+	public void toContainValue(final V value) {
+        expectNotNull(this.getValue(), "Expected null to contain the value '%s'", value);
 		expectTrue(this.getValue().containsValue(value), "Expected '%s' to contain value '%s'", this.getValue(), value);
 	}
 
-	public void toNotContainValue(final Object value) {
+    /**
+     * Checks if the stored {@code Map} does not contain the given {@code value}.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} does not contain the given {@code value}</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
+	public void toNotContainValue(final V value) {
+        expectNotNull(this.getValue(), "Expected null to not contain the value '%s'", value);
 		expectTrue(!this.getValue().containsValue(value), "Expected '%s' to not contain value '%s'", this.getValue(), value);
 	}
 
-	public void toHaveLength(final int length) {
-		expectTrue(this.getValue().size() == length, "Expected '%s' to have a length of %d, instead has a length of %d", this.getValue(), length, this.getValue().size());
+    /**
+     * Checks if the stored {@code Map} has a given {@code size}.
+     * <p>This method throws an {@code AssertionError} if
+     * <ul>
+     *     <li>the stored {@code Map} does not have the given {@code size}</li>
+     *     <li>the stored {@code Map} is {@code null}</li>
+     * </ul>
+     */
+	public void toHaveSize(final int size) {
+        expectNotNull(this.getValue(), "Expected null to have size '%s'", size);
+		expectTrue(this.getValue().size() == size, "Expected '%s' to have a size of %d, instead has a size of %d", this.getValue(), size, this.getValue().size());
 	}
 }

oleaster-matcher/src/test/java/com/mscharhag/oleaster/matcher/matchers/CollectionMatcherTest.java

@@ -27,20 +27,30 @@ public class CollectionMatcherTest {{
                         "Expected '[one, two]' to contain 'four'");
             });
 
+            it("fails if the stored collection is null", () -> {
+                expectAssertionError(() -> new CollectionMatcher(null).toContain("one"),
+                        "Expected null to contain 'one'");
+            });
+
             it("is ok if the stored collection contains the expected value", () -> {
                 new CollectionMatcher(list).toContain("one");
                 new CollectionMatcher(set).toContain("two");
             });
         });
 
         describe("when toNotContain() is called", () -> {
-            it("fails if hte stored collection does contain the expected value", () -> {
+            it("fails if the stored collection does contain the expected value", () -> {
                 expectAssertionError(() -> new CollectionMatcher(list).toNotContain("one"),
                         "Expected '[one, two]' to not contain 'one'");
                 expectAssertionError(() -> new CollectionMatcher(set).toNotContain("one"),
                         "Expected '[one, two]' to not contain 'one'");
             });
 
+            it("fails if the stored collection is null", () -> {
+                expectAssertionError(() -> new CollectionMatcher(null).toNotContain("one"),
+                        "Expected null to not contain 'one'");
+            });
+
             it("is ok if the stored collection not contains the expected value", () -> {
                new CollectionMatcher(list).toNotContain("three");
                new CollectionMatcher(set).toNotContain("three");
@@ -55,6 +65,11 @@ public class CollectionMatcherTest {{
                         "Expected '[one, two]' to be empty");
             });
 
+            it("fails if the stored collection is null", () -> {
+                expectAssertionError(() -> new CollectionMatcher(null).toBeEmpty(),
+                        "Expected null to be empty");
+            });
+
             it("is ok if the stored collection is empty", () -> {
                 new CollectionMatcher(new LinkedList()).toBeEmpty();
                 new CollectionMatcher(new HashSet()).toBeEmpty();
@@ -69,23 +84,32 @@ public class CollectionMatcherTest {{
                         "Expected '[]' to not be empty");
             });
 
+            it("fails if the stored collection is null", () -> {
+                expectAssertionError(() -> new CollectionMatcher(null).toNotBeEmpty(),
+                        "Expected null to not be empty");
+            });
+
             it("is ok if the stored collection is not empty", () -> {
                 new CollectionMatcher(list).toNotBeEmpty();
                 new CollectionMatcher(set).toNotBeEmpty();
             });
         });
 
-        describe("when toHaveLength() is called", () -> {
-            it("fails if the stored collection does not have the provided length", () -> {
-                expectAssertionError(() -> new CollectionMatcher(list).toHaveLength(1),
-                        "Expected '[one, two]' to have a length of 1, instead has a length of 2");
-                expectAssertionError(() -> new CollectionMatcher(set).toHaveLength(-1),
-                        "Expected '[one, two]' to have a length of -1, instead has a length of 2");
+        describe("when toHaveSize() is called", () -> {
+            it("fails if the stored collection does not have the provided size", () -> {
+                expectAssertionError(() -> new CollectionMatcher(list).toHaveSize(1),
+                        "Expected '[one, two]' to have a size of 1, instead has a size of 2");
+                expectAssertionError(() -> new CollectionMatcher(set).toHaveSize(-1),
+                        "Expected '[one, two]' to have a size of -1, instead has a size of 2");
+            });
+
+            it("fails if the stored collection is null", () -> {
+                expectAssertionError(() -> new CollectionMatcher(null).toHaveSize(1));
             });
 
-            it("is ok if hte stored collection has the provided length", () -> {
-               new CollectionMatcher(list).toHaveLength(2);
-               new CollectionMatcher(set).toHaveLength(2);
+            it("is ok if hte stored collection has the provided size", () -> {
+               new CollectionMatcher(list).toHaveSize(2);
+               new CollectionMatcher(set).toHaveSize(2);
             });
         });
     });