=doc #13043 Adding section on testing parent-child relationships

akka-docs/rst/java/code/docs/testkit/ParentChildTest.java

@@ -0,0 +1,202 @@
+/**
+ * Copyright (C) 2014 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.testkit;
+
+import static org.junit.Assert.*;
+
+import akka.actor.*;
+import akka.japi.Creator;
+import akka.japi.Function;
+import akka.testkit.AkkaJUnitActorSystemResource;
+import akka.testkit.TestActorRef;
+import akka.testkit.TestProbe;
+import com.typesafe.config.ConfigFactory;
+import org.junit.ClassRule;
+import org.junit.Test;
+
+public class ParentChildTest {
+  @ClassRule
+  public static AkkaJUnitActorSystemResource actorSystemResource =
+    new AkkaJUnitActorSystemResource("TestKitDocTest",
+                                     ConfigFactory.parseString("akka.loggers = [akka.testkit.TestEventListener]"));
+
+
+  private final ActorSystem system = actorSystemResource.getSystem();
+
+  //#test-example
+  static class Parent extends UntypedActor {
+    final ActorRef child = context().actorOf(Props.create(Child.class), "child");
+    boolean ponged = false;
+
+    @Override public void onReceive(Object message) throws Exception {
+      if ("pingit".equals(message)) {
+        child.tell("ping", self());
+      } else if ("pong".equals(message)) {
+        ponged = true;
+      } else {
+        unhandled(message);
+      }
+    }
+  }
+
+  static class Child extends UntypedActor {
+    @Override public void onReceive(Object message) throws Exception {
+      if ("ping".equals(message)) {
+        context().parent().tell("pong", self());
+      } else {
+        unhandled(message);
+      }
+    }
+  }
+  //#test-example
+
+  static
+  //#test-dependentchild
+  class DependentChild extends UntypedActor {
+    private final ActorRef parent;
+
+    public DependentChild(ActorRef parent) {
+      this.parent = parent;
+    }
+
+    @Override public void onReceive(Object message) throws Exception {
+      if ("ping".equals(message)) {
+        parent.tell("pong", self());
+      } else {
+        unhandled(message);
+      }
+    }
+  }
+  //#test-dependentchild
+
+  static
+  //#test-dependentparent
+  class DependentParent extends UntypedActor {
+    final ActorRef child;
+    boolean ponged = false;
+
+    public DependentParent(Props childProps) {
+      child = context().actorOf(childProps, "child");
+    }
+
+    @Override public void onReceive(Object message) throws Exception {
+      if ("pingit".equals(message)) {
+        child.tell("ping", self());
+      } else if ("pong".equals(message)) {
+        ponged = true;
+      } else {
+        unhandled(message);
+      }
+    }
+  }
+  //#test-dependentparent
+
+  static
+  //#test-dependentparent-generic
+  class GenericDependentParent extends UntypedActor {
+    final ActorRef child;
+    boolean ponged = false;
+
+    public GenericDependentParent(Function<ActorRefFactory, ActorRef> childMaker)
+      throws Exception {
+      child = childMaker.apply(context());
+    }
+
+    @Override public void onReceive(Object message) throws Exception {
+      if ("pingit".equals(message)) {
+        child.tell("ping", self());
+      } else if ("pong".equals(message)) {
+        ponged = true;
+      } else {
+        unhandled(message);
+      }
+    }
+  }
+  //#test-dependentparent-generic
+
+  @Test
+  public void testingWithoutParent() {
+    TestProbe probe = new TestProbe(system);
+    ActorRef child = system.actorOf(Props.create(DependentChild.class, probe.ref()));
+    probe.send(child, "ping");
+    probe.expectMsg("pong");
+  }
+
+  @Test
+  public void testingWithCustomProps() {
+    TestProbe probe = new TestProbe(system);
+    Props childProps = Props.create(MockedChild.class);
+    TestActorRef<DependentParent> parent = TestActorRef.create(system, Props.create(DependentParent.class, childProps));
+
+    probe.send(parent, "pingit");
+
+    // test some parent state change
+    assertTrue(parent.underlyingActor().ponged == true || parent.underlyingActor().ponged == false);
+  }
+
+
+  @Test
+  public void testingWithChildProbe() throws Exception {
+    final TestProbe probe = new TestProbe(system);
+    //#child-maker-test
+    Function<ActorRefFactory, ActorRef> maker = new Function<ActorRefFactory, ActorRef>() {
+      @Override public ActorRef apply(ActorRefFactory param) throws Exception {
+        return probe.ref();
+      }
+    };
+    ActorRef parent = system.actorOf(Props.create(GenericDependentParent.class, maker));
+    //#child-maker-test
+    probe.send(parent, "pingit");
+    probe.expectMsg("ping");
+  }
+
+  public void exampleProdActorFactoryFunction() throws Exception {
+    //#child-maker-prod
+    Function<ActorRefFactory, ActorRef> maker = new Function<ActorRefFactory, ActorRef>() {
+      @Override public ActorRef apply(ActorRefFactory f) throws Exception {
+        return f.actorOf(Props.create(Child.class));
+      }
+    };
+    ActorRef parent = system.actorOf(Props.create(GenericDependentParent.class, maker));
+    //#child-maker-prod
+  }
+
+  static
+  //#test-fabricated-parent-creator
+  class FabricatedParentCreator implements Creator<Actor> {
+    private final TestProbe proxy;
+
+    public FabricatedParentCreator(TestProbe proxy) {
+      this.proxy = proxy;
+    }
+
+    @Override public Actor create() throws Exception {
+      return new UntypedActor() {
+        final ActorRef child = context().actorOf(Props.create(Child.class), "child");
+
+        @Override public void onReceive(Object x) throws Exception {
+          if (sender().equals(child)) {
+            proxy.ref().forward(x, context());
+          } else {
+            child.forward(x, context());
+          }
+        }
+      };
+    }
+  }
+  //#test-fabricated-parent-creator
+
+  @Test
+  public void fabricatedParentTestsItsChildResponses() throws Exception {
+    // didn't put final on these in order to make the parent fit in one line in the html docs
+    //#test-fabricated-parent
+    TestProbe proxy = new TestProbe(system);
+    ActorRef parent = system.actorOf(Props.create(new FabricatedParentCreator(proxy)));
+
+    proxy.send(parent, "ping");
+    proxy.expectMsg("pong");
+    //#test-fabricated-parent
+  }
+
+}

akka-docs/rst/java/testing.rst

@@ -462,6 +462,58 @@ do not react to each other's deadlines or to the deadline set in an enclosing
 
 Here, the ``expectMsgEquals`` call will use the default timeout.
 
+Testing parent-child relationships
+----------------------------------
+
+The parent of an actor is always the actor that created it. At times this leads to
+a coupling between the two that may not be straightforward to test.
+Broadly, there are three approaches to improve testability of parent-child
+relationships:
+
+1. when creating a child, pass an explicit reference to its parent
+2. when creating a parent, tell the parent how to create its child
+3. create a fabricated parent when testing
+
+For example, the structure of the code you want to test may follow this pattern:
+
+.. includecode:: code/docs/testkit/ParentChildTest.java#test-example
+
+Using dependency-injection
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first option is to avoid use of the :meth:`context.parent` function and create
+a child with a custom parent by passing an explicit reference to its parent instead.
+
+.. includecode:: code/docs/testkit/ParentChildTest.java#test-dependentchild
+
+Alternatively, you can tell the parent how to create its child. There are two ways
+to do this: by giving it a :class:`Props` object or by giving it a function which takes care of creating the child actor:
+
+.. includecode:: code/docs/testkit/ParentChildTest.java#test-dependentparent
+.. includecode:: code/docs/testkit/ParentChildTest.java#test-dependentparent-generic
+
+Creating the :class:`Actor` is straightforward and the function may look like this in your test code:
+
+.. includecode:: code/docs/testkit/ParentChildTest.java#child-maker-test
+
+And like this in your application code:
+
+.. includecode:: code/docs/testkit/ParentChildTest.java#child-maker-prod
+
+Using a fabricated parent
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you prefer to avoid modifying the parent or child constructor you can
+create a fabricated parent in your test. This, however, does not enable you to test
+the parent actor in isolation.
+
+.. includecode:: code/docs/testkit/ParentChildTest.java#test-fabricated-parent-creator
+.. includecode:: code/docs/testkit/ParentChildTest.java#test-fabricated-parent
+
+Which of these methods is the best depends on what is most important to test. The
+most generic option is to create the parent actor by passing it a function that is
+responsible for the Actor creation, but the fabricated parent is often sufficient.
+
 .. _Java-CallingThreadDispatcher:
 
 CallingThreadDispatcher