Merge pull request #1053 from akka/wip-2916-CTD-warning-∂π

document deadlock risk of TestProbe.watch(TestActorRef), see #2916

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

@@ -17,6 +17,7 @@ import akka.actor.ActorRef;
 import akka.actor.ActorSystem;
 import akka.actor.Kill;
 import akka.actor.Props;
+import akka.actor.Terminated;
 import akka.actor.UntypedActor;
 import akka.actor.UntypedActorFactory;
 import scala.concurrent.Await;
@@ -300,6 +301,19 @@ public class TestKitDocTest {
     //#test-special-probe
   }
   
+  @Test
+  public void demonstrateWatch() {
+    final ActorRef target = system.actorFor("/buh");
+    //#test-probe-watch
+    new JavaTestKit(system) {{
+      final JavaTestKit probe = new JavaTestKit(system);
+      probe.watch(target);
+      final Terminated msg = probe.expectMsgClass(Terminated.class);
+      assertEquals(msg.getActor(), target);
+    }};
+    //#test-probe-watch
+  }
+  
   @Test
   public void demonstrateReply() {
     //#test-probe-reply

akka-docs/rst/java/testing.rst

@@ -387,6 +387,23 @@ You have complete flexibility here in mixing and matching the
 name for it. In real life your code will probably be a bit more complicated
 than the example given above; just use the power!
 
+.. warning::
+
+  Any message send from a ``TestProbe`` to another actor which runs on the
+  CallingThreadDispatcher runs the risk of dead-lock, if that other actor might
+  also send to this probe. The implementation of :meth:`TestProbe.watch` and
+  :meth:`TestProbe.unwatch` will also send a message to the watchee, which
+  means that it is dangerous to try watching e.g. :class:`TestActorRef` from a
+  :meth:`TestProbe`.
+
+Watching Other Actors from Probes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A :class:`JavaTestKit` can register itself for DeathWatch of any other actor:
+
+.. includecode:: code/docs/testkit/TestKitDocTest.java
+   :include: test-probe-watch
+
 Replying to Messages Received by Probes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

akka-docs/rst/scala/code/docs/testkit/TestkitDocSpec.scala

@@ -206,6 +206,16 @@ class TestkitDocSpec extends AkkaSpec with DefaultTimeout with ImplicitSender {
     //#test-special-probe
   }
 
+  "demonstrate probe watch" in {
+    import akka.testkit.TestProbe
+    val target = system.actorFor("/buh")
+    //#test-probe-watch
+    val probe = TestProbe()
+    probe watch target
+    probe.expectMsgType[Terminated].actor must be(target)
+    //#test-probe-watch
+  }
+
   "demonstrate probe reply" in {
     import akka.testkit.TestProbe
     import scala.concurrent.duration._

akka-docs/rst/scala/testing.rst

@@ -446,6 +446,23 @@ facilities with your own checks and choosing an intuitive name for it. In real
 life your code will probably be a bit more complicated than the example given
 above; just use the power!
 
+.. warning::
+
+  Any message send from a ``TestProbe`` to another actor which runs on the
+  CallingThreadDispatcher runs the risk of dead-lock, if that other actor might
+  also send to this probe. The implementation of :meth:`TestProbe.watch` and
+  :meth:`TestProbe.unwatch` will also send a message to the watchee, which
+  means that it is dangerous to try watching e.g. :class:`TestActorRef` from a
+  :meth:`TestProbe`.
+
+Watching Other Actors from Probes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A :class:`TestKit` can register itself for DeathWatch of any other actor:
+
+.. includecode:: code/docs/testkit/TestkitDocSpec.scala
+   :include: test-probe-watch
+
 Replying to Messages Received by Probes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^