NodeItemTest: use val and Assert.assertThat()

* Lombok's val simplfies the local variable declarations
* Assert.assertThat() gives better error messages
* javadoc tidy

Signed-off-by: Paul Campbell <pcampbell@kemitix.net>

src/test/java/net/kemitix/node/NodeItemTest.java

@@ -1,18 +1,17 @@
 package net.kemitix.node;
 
+import lombok.val;
+import org.junit.Assert;
 import org.junit.Test;
 
+import static org.hamcrest.CoreMatchers.hasItem;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.nullValue;
+
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.Optional;
 
-import static org.hamcrest.CoreMatchers.hasItem;
-import static org.hamcrest.CoreMatchers.is;
-import static org.junit.Assert.assertFalse;
-import static org.junit.Assert.assertNull;
-import static org.junit.Assert.assertThat;
-import static org.junit.Assert.assertTrue;
-
 /**
  * Test for {@link NodeItem}.
  *
@@ -26,22 +25,21 @@ public class NodeItemTest {
     private Node<String> node;
 
     /**
-     * Test {@link NodeItem#Node(java.lang.Object) } that node data is
-     * recoverable.
+     * Test that node data is recoverable.
      */
     @Test
     public void shouldReturnNodeData() {
         //given
-        final String data = "this node data";
+        val data = "this node data";
         //when
         node = new NodeItem<>(data);
         //then
-        assertThat(node.getData(), is(data));
+        Assert.assertThat("can get the data from a node", node.getData(),
+                is(data));
     }
 
     /**
-     * Test {@link NodeItem#Node(java.lang.Object) } that passing null as node
-     * data throws exception.
+     * Test that passing null as node data throws exception.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNPEWhenDataIsNull() {
@@ -50,78 +48,79 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#Node(java.lang.Object) } that default node parent is
-     * null.
+     * Test that default node parent is null.
      */
     @Test
-    public void shouldHaveNullForDefaulParent() {
+    public void shouldHaveNullForDefaultParent() {
         //given
         node = new NodeItem<>("data");
         //then
-        assertNull(node.getParent());
+        Assert.assertThat("node created without a parent has null as parent",
+                node.getParent(), nullValue());
     }
 
     /**
-     * Test {@link NodeItem#Node(java.lang.Object, net.kemitix.node.Node) } that
-     * provided node parent is returned.
+     * Test that provided node parent is returned.
      */
     @Test
     public void shouldReturnNodeParent() {
         //given
-        Node<String> parent = new NodeItem<>("parent");
+        val parent = new NodeItem<String>("parent");
         //when
         node = new NodeItem<>("subject", parent);
         //then
-        assertThat(node.getParent(), is(parent));
+        Assert.assertThat("node created with a parent can return the parent",
+                node.getParent(), is(parent));
     }
 
     /**
-     * Test {@link NodeItem#Node(java.lang.Object, net.kemitix.node.Node) } that
-     * setting the parent on a node where the proposed parent is a child of the
-     * node throws an exception.
+     * Test that setting the parent on a node where the proposed parent is a
+     * child of the node throws an exception.
      */
     @Test(expected = NodeException.class)
     public void shouldThrowNEWhenSettingParentToAChild() {
         //given
         node = new NodeItem<>("subject");
-        Node<String> child = new NodeItem<>("child", node);
+        val child = new NodeItem<String>("child", node);
         //when
         node.setParent(child);
     }
 
     /**
-     * Test {@link NodeItem#Node(java.lang.Object, net.kemitix.node.Node) } that
-     * when parent is added to created node, the created node is now a child of
-     * the parent.
+     * Test that when parent is added to created node, the created node is now a
+     * child of the parent.
      */
     @Test
     public void shouldAddNewNodeAsChildToParent() {
         //given
-        Node<String> parent = new NodeItem<>("parent");
+        val parent = new NodeItem<String>("parent");
         //when
         node = new NodeItem<>("subject", parent);
         //then
-        assertThat(parent.getChildren(), hasItem(node));
+        Assert.assertThat(
+                "when a node is created with a parent, the parent has the new"
+                        + " node among it's children", parent.getChildren(),
+                hasItem(node));
     }
 
     /**
-     * Test {@link NodeItem#setParent(net.kemitix.node.Node) } that we return
-     * the same parent when set.
+     * Test that we return the same parent when set.
      */
     @Test
     public void shouldReturnSetParent() {
         //given
         node = new NodeItem<>("subject");
-        Node<String> parent = new NodeItem<>("parent");
+        val parent = new NodeItem<String>("parent");
         //when
         node.setParent(parent);
         //then
-        assertThat(node.getParent(), is(parent));
+        Assert.assertThat(
+                "when a node is assigned a new parent that parent can be "
+                        + "returned", node.getParent(), is(parent));
     }
 
     /**
-     * Test {@link NodeItem#setParent(net.kemitix.node.Node) } that we throw an
-     * exception when passed null.
+     * Test that we throw an exception when passed null.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNPEWhenSetParentNull() {
@@ -132,8 +131,8 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#setParent(net.kemitix.node.Node) } that we throw an
-     * exceptions when attempting to node as its own parent.
+     * Test that we throw an exceptions when attempting to node as its own
+     * parent.
      */
     @Test(expected = NodeException.class)
     public void shouldThrowNEWhenSetParentSelf() {
@@ -144,44 +143,53 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#setParent(net.kemitix.node.Node) } that when a node
-     * with an existing parent is assigned a new parent, that the old parent no
-     * longer sees it as one of its children.
+     * Test that when a node with an existing parent is assigned a new parent,
+     * that the old parent no longer sees it as one of its children.
      */
     @Test
     public void shouldUpdateOldParentWhenNodeSetToNewParent() {
         //given
         node = new NodeItem<>("subject");
-        Node<String> child = node.createChild("child");
-        Node<String> newParent = new NodeItem<>("newParent");
+        val child = node.createChild("child");
+        val newParent = new NodeItem<String>("newParent");
         //when
         child.setParent(newParent);
         //then
-        assertThat(child.getParent(), is(newParent));
-        assertFalse(node.getChild("child").isPresent());
+        Assert.assertThat(
+                "when a node is assigned a new parent, the old parent is "
+                        + "replaced", child.getParent(), is(newParent));
+        Assert.assertThat(
+                "when a node is assigned a new parent, the old parent no "
+                        + "longer has the node among it's children",
+                node.getChild("child").isPresent(), is(false));
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that when a node
-     * is added as a child to another node, that it's previous parent no longer
-     * has it as a child.
+     * Test that when a node is added as a child to another node, that it's
+     * previous parent no longer has it as a child.
      */
     @Test
     public void shouldRemoveNodeFromOldParentWhenAddedAsChildToNewParent() {
         //given
         node = new NodeItem<>("subject");
-        Node<String> child = node.createChild("child");
-        Node<String> newParent = new NodeItem<>("newParent");
+        val child = node.createChild("child");
+        val newParent = new NodeItem<String>("newParent");
         //when
         newParent.addChild(child);
         //then
-        assertThat(child.getParent(), is(newParent));
-        assertFalse(node.getChild("child").isPresent());
+        Assert.assertThat(
+                "when a node with an existing parent is added as a child "
+                        + "to another node, then the old parent is replaced",
+                child.getParent(), is(newParent));
+        Assert.assertThat(
+                "when a node with an existing parent is added as a child to "
+                        + "another node, then the old parent no longer has "
+                        + "the node among it's children",
+                node.getChild("child").isPresent(), is(false));
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding null
-     * as a child throws an exception.
+     * Test that adding null as a child throws an exception.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNPEWhenAddingNullAsChild() {
@@ -192,23 +200,23 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding a
-     * child is returned.
+     * Test that adding a child is returned.
      */
     @Test
     public void shouldReturnAddedChild() {
         //given
-        Node<String> child = new NodeItem<>("child");
         node = new NodeItem<>("subject");
+        val child = new NodeItem<String>("child");
         //when
         node.addChild(child);
         //then
-        assertThat(node.getChildren(), hasItem(child));
+        Assert.assertThat(
+                "when a node is added as a child, the node is among the "
+                        + "children", node.getChildren(), hasItem(child));
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding a node
-     * as it's own child throws an exception.
+     * Test that adding a node as it's own child throws an exception.
      */
     @Test(expected = NodeException.class)
     public void shouldThrowNEWhenAddingANodeAsOwnChild() {
@@ -219,8 +227,7 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding a node
-     * to itself as a child causes an exception.
+     * Test that adding a node to itself as a child causes an exception.
      */
     @Test(expected = NodeException.class)
     public void shouldThrowWhenAddingSelfAsChild() {
@@ -231,89 +238,93 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding the
-     * parent to node causes an exception.
+     * Test that adding the parent of a node to the node as a child causes an
+     * exception.
      */
     @Test(expected = NodeException.class)
     public void shouldThrowWhenAddingParentAsChild() {
         //given
-        Node<String> parent = new NodeItem<>("parent");
+        val parent = new NodeItem<String>("parent");
         node = new NodeItem<>("subject", parent);
         //when
         node.addChild(parent);
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding the
-     * grandparent to node causes an exception.
+     * Test that adding the grandparent to a node as a child causes an
+     * exception.
      */
     @Test(expected = NodeException.class)
     public void shouldThrowWhenAddingGrandParentAsChild() {
         //given
-        Node<String> grandParent = new NodeItem<>("grandparent");
-        Node<String> parent = new NodeItem<>("parent", grandParent);
+        val grandParent = new NodeItem<String>("grandparent");
+        val parent = new NodeItem<String>("parent", grandParent);
         node = new NodeItem<>("subject", parent);
         //when
         node.addChild(grandParent);
     }
 
     /**
-     * Test {@link NodeItem#addChild(net.kemitix.node.Node) } that adding a
-     * child to a node, sets the child's parent node.
+     * Test that adding a child to a node, sets the child's parent node.
      */
     @Test
     public void shouldSetParentOnChildWhenAddedAsChild() {
         //given
-        Node<String> child = new NodeItem<>("child");
+        val child = new NodeItem<String>("child");
         node = new NodeItem<>("subject");
         //when
         node.addChild(child);
         //then
-        assertThat(child.getParent(), is(node));
+        Assert.assertThat(
+                "when a node is added as a child, the child has the node as "
+                        + "its parent", child.getParent(), is(node));
     }
 
     /**
-     * Test {@link NodeItem#walkTree(java.util.List) } that we can walk a tree
-     * to the target node.
+     * Test that we can walk a tree to the target node.
      */
     @Test
     public void shouldWalkTreeToNode() {
         //given
-        final String grandparent = "grandparent";
-        Node<String> grandParentNode = new NodeItem<>(grandparent);
-        final String parent = "parent";
-        Node<String> parentNode = new NodeItem<>(parent, grandParentNode);
-        final String subject = "subject";
+        val grandparent = "grandparent";
+        val grandParentNode = new NodeItem<String>(grandparent);
+        val parent = "parent";
+        val parentNode = new NodeItem<String>(parent, grandParentNode);
+        val subject = "subject";
         node = new NodeItem<>(subject, parentNode);
         //when
-        Optional<Node<String>> result = grandParentNode.walkTree(Arrays.asList(
-                parent, subject));
+        val result = grandParentNode.walkTree(Arrays.asList(parent, subject));
         //then
-        assertTrue(result.isPresent());
-        assertThat(result.get(), is(node));
+        Assert.assertThat("when we walk the tree to a node it is found",
+                result.isPresent(), is(true));
+        if (result.isPresent()) {
+            Assert.assertThat(
+                    "when we walk the tree to a node the correct node is found",
+                    result.get(), is(node));
+        }
     }
 
     /**
-     * Test {@link NodeItem#walkTree(java.util.List) } that we get an empty
-     * {@link Optional} when walking a path that doesn't exist.
+     * Test that we get an empty {@link Optional} when walking a path that
+     * doesn't exist.
      */
     @Test
-    public void shouldNotFindNonExistantChildNode() {
+    public void shouldNotFindNonExistentChildNode() {
         //given
-        final String parent = "parent";
-        Node<String> parentNode = new NodeItem<>(parent);
-        final String subject = "subject";
+        val parent = "parent";
+        val parentNode = new NodeItem<String>(parent);
+        val subject = "subject";
         node = new NodeItem<>(subject, parentNode);
         //when
-        Optional<Node<String>> result = parentNode.walkTree(Arrays.asList(
-                subject, "no child"));
+        val result = parentNode.walkTree(Arrays.asList(subject, "no child"));
         //then
-        assertFalse(result.isPresent());
+        Assert.assertThat(
+                "when we walk the tree to a node that doesn't exists, nothing"
+                        + " is found", result.isPresent(), is(false));
     }
 
     /**
-     * Test {@link NodeItem#walkTree(java.util.List) } that when we pass null we
-     * get an exception.
+     * Test that when we pass null we get an exception.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNEWhenWalkTreeNull() {
@@ -324,8 +335,8 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#walkTree(java.util.List) } that when we pass an
-     * empty path we get and empty {@link Optional} as a result.
+     * Test that when we pass an empty path we get and empty {@link Optional} as
+     * a result.
      */
     @Test
     public void shouldReturnEmptyForEmptyWalkTreePath() {
@@ -336,37 +347,58 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#createDescendantLine(java.util.List) } that we can
-     * create a chain of descendant nodes.
+     * Test that we can create a chain of descendant nodes.
      */
     @Test
     public void shouldCreateDescendantNodes() {
         //given
         node = new NodeItem<>("subject");
-        final String alphaData = "alpha";
-        final String betaData = "beta";
-        final String gammaData = "gamma";
+        val alphaData = "alpha";
+        val betaData = "beta";
+        val gammaData = "gamma";
         //when
         node.createDescendantLine(
                 Arrays.asList(alphaData, betaData, gammaData));
         //then
-        final Optional<Node<String>> alphaOptional = node.getChild(alphaData);
-        assertTrue(alphaOptional.isPresent());
-        Node<String> alpha = alphaOptional.get();
-        assertThat(alpha.getParent(), is(node));
-        final Optional<Node<String>> betaOptional = alpha.getChild(betaData);
-        assertTrue(betaOptional.isPresent());
-        Node<String> beta = betaOptional.get();
-        assertThat(beta.getParent(), is(alpha));
-        final Optional<Node<String>> gammaOptional = beta.getChild(gammaData);
-        assertTrue(gammaOptional.isPresent());
-        Node<String> gamma = gammaOptional.get();
-        assertThat(gamma.getParent(), is(beta));
+        val alphaOptional = node.getChild(alphaData);
+        Assert.assertThat(
+                "when creating a descendant line, the first element is found",
+                alphaOptional.isPresent(), is(true));
+        if (alphaOptional.isPresent()) {
+            val alpha = alphaOptional.get();
+            Assert.assertThat(
+                    "when creating a descendant line, the first element has "
+                            + "the current node as its parent",
+                    alpha.getParent(), is(node));
+            val betaOptional = alpha.getChild(betaData);
+            Assert.assertThat(
+                    "when creating a descendant line, the second element is "
+                            + "found", betaOptional.isPresent(), is(true));
+            if (betaOptional.isPresent()) {
+                val beta = betaOptional.get();
+                Assert.assertThat(
+                        "when creating a descendant line, the second element "
+                                + "has the first as its parent",
+                        beta.getParent(), is(alpha));
+                val gammaOptional = beta.getChild(gammaData);
+                Assert.assertThat(
+                        "when creating a descendant line, the third element "
+                                + "is found", gammaOptional.isPresent(),
+                        is(true));
+                if (gammaOptional.isPresent()) {
+                    val gamma = gammaOptional.get();
+                    Assert.assertThat(
+                            "when creating a descendant line, the third "
+                                    + "element has the second as its parent",
+                            gamma.getParent(), is(beta));
+                }
+            }
+        }
     }
 
     /**
-     * Test {@link NodeItem#createDescendantLine(java.util.List) } that if we
-     * pass null to create a chain of descendant nodes we get an exception.
+     * Test that if we pass null to create a chain of descendant nodes we get an
+     * exception.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNPEWhenCreateDescendantNull() {
@@ -377,8 +409,7 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#createDescendantLine(java.util.List) } that if we
-     * pass an empty list nothing is changed.
+     * Test that if we pass an empty list nothing is changed.
      */
     @Test
     public void shouldChangeNothingWhenCreateDescendantEmpty() {
@@ -387,43 +418,46 @@ public class NodeItemTest {
         //when
         node.createDescendantLine(Collections.emptyList());
         //then
-        assertThat(node.getChildren().size(), is(0));
+        Assert.assertThat(
+                "when creating a descendant line from an empty list, nothing "
+                        + "is created", node.getChildren().size(), is(0));
     }
 
     /**
-     * Test {@link NodeItem#findOrCreateChild(java.lang.Object) } that we can
-     * find a child of a node.
+     * Test that we can find a child of a node.
      */
     @Test
     public void shouldFindExistingChildNode() {
         //given
         node = new NodeItem<>("subject");
-        final String childData = "child";
-        Node<String> child = new NodeItem<>(childData, node);
+        val childData = "child";
+        val child = new NodeItem<String>(childData, node);
         //when
-        Node<String> found = node.findOrCreateChild(childData);
+        val found = node.findOrCreateChild(childData);
         //then
-        assertThat(found, is(child));
+        Assert.assertThat(
+                "when searching for a child by data, the matching child is "
+                        + "found", found, is(child));
     }
 
     /**
-     * Test {@link NodeItem#findOrCreateChild(java.lang.Object) } that we create
-     * a missing child of a node.
+     * Test that we create a missing child of a node.
      */
     @Test
     public void shouldFindCreateNewChildNode() {
         //given
         node = new NodeItem<>("subject");
-        final String childData = "child";
+        val childData = "child";
         //when
-        Node<String> found = node.findOrCreateChild(childData);
+        val found = node.findOrCreateChild(childData);
         //then
-        assertThat(found.getData(), is(childData));
+        Assert.assertThat(
+                "when searching for a child by data, a new node is created",
+                found.getData(), is(childData));
     }
 
     /**
-     * Test {@link NodeItem#findOrCreateChild(java.lang.Object) } that if we
-     * pass null we get an exception.
+     * Test that if we pass null we get an exception.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNPEFWhenFindOrCreateChildNull() {
@@ -434,26 +468,29 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#getChild(java.lang.Object) } that we can get the
-     * node for a child.
+     * Test that we can get the node for a child.
      */
     @Test
     public void shouldGetChild() {
         //given
         node = new NodeItem<>("subject");
-        final String childData = "child";
-        Node<String> child = new NodeItem<>(childData);
+        val childData = "child";
+        val child = new NodeItem<String>(childData);
         node.addChild(child);
         //when
-        Optional<Node<String>> found = node.getChild(childData);
+        val found = node.getChild(childData);
         //then
-        assertTrue(found.isPresent());
-        assertThat(found.get(), is(child));
+        Assert.assertThat("when retrieving a child by its data, it is found",
+                found.isPresent(), is(true));
+        if (found.isPresent()) {
+            Assert.assertThat(
+                    "when retrieving a child by its data, it is the expected "
+                            + "node", found.get(), is(child));
+        }
     }
 
     /**
-     * Test {@link NodeItem#getChild(java.lang.Object) } that we throw an
-     * exception when passed null.
+     * Test that we throw an exception when passed null.
      */
     @Test(expected = NullPointerException.class)
     public void shouldThrowNPEWhenGetChildNull() {
@@ -464,22 +501,29 @@ public class NodeItemTest {
     }
 
     /**
-     * Test {@link NodeItem#createChild(java.lang.Object) } that we create a
-     * child as a child of the current node and with the current node as its
-     * parent.
+     * Test that we create a child as a child of the current node and with the
+     * current node as its parent.
      */
     @Test
-    public void shoudCreateChild() {
+    public void shouldCreateChild() {
         //given
         node = new NodeItem<>("subject");
-        final String childData = "child";
+        val childData = "child";
         //when
-        Node<String> child = node.createChild(childData);
+        val child = node.createChild(childData);
         //then
-        assertThat(child.getParent(), is(node));
-        final Optional<Node<String>> foundChild = node.getChild(childData);
-        assertTrue(foundChild.isPresent());
-        assertThat(foundChild.get(), is(child));
+        Assert.assertThat(
+                "when creating a child node, the child has the current node "
+                        + "as its parent", child.getParent(), is(node));
+        val foundChild = node.getChild(childData);
+        Assert.assertThat(
+                "when creating a child node, the child can be found by its "
+                        + "data", foundChild.isPresent(), is(true));
+        if (foundChild.isPresent()) {
+            Assert.assertThat(
+                    "when creating a child node, the correct child can be "
+                            + "found by its data", foundChild.get(), is(child));
+        }
     }
 
     /**