Move all doc examples out of the akka-package to avoid use of private APIs. See #2092

akka-docs/scala/code/docs/testkit/PlainWordSpec.scala

@@ -0,0 +1,47 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.testkit
+
+//#plain-spec
+import akka.actor.ActorSystem
+import akka.actor.Actor
+import akka.actor.Props
+import akka.testkit.TestKit
+import org.scalatest.WordSpec
+import org.scalatest.matchers.MustMatchers
+import org.scalatest.BeforeAndAfterAll
+import akka.testkit.ImplicitSender
+
+object MySpec {
+  class EchoActor extends Actor {
+    def receive = {
+      case x ⇒ sender ! x
+    }
+  }
+}
+
+//#implicit-sender
+class MySpec(_system: ActorSystem) extends TestKit(_system) with ImplicitSender
+  with WordSpec with MustMatchers with BeforeAndAfterAll {
+  //#implicit-sender
+
+  def this() = this(ActorSystem("MySpec"))
+
+  import MySpec._
+
+  override def afterAll {
+    system.shutdown()
+  }
+
+  "An Echo actor" must {
+
+    "send back messages unchanged" in {
+      val echo = system.actorOf(Props[EchoActor])
+      echo ! "hello world"
+      expectMsg("hello world")
+    }
+
+  }
+}
+//#plain-spec

akka-docs/scala/code/docs/testkit/TestKitUsageSpec.scala

@@ -0,0 +1,156 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.testkit
+
+//#testkit-usage
+import scala.util.Random
+
+import org.scalatest.BeforeAndAfterAll
+import org.scalatest.WordSpec
+import org.scalatest.matchers.ShouldMatchers
+
+import com.typesafe.config.ConfigFactory
+
+import akka.actor.Actor
+import akka.actor.ActorRef
+import akka.actor.ActorSystem
+import akka.actor.Props
+import akka.testkit.DefaultTimeout
+import akka.testkit.ImplicitSender
+import akka.testkit.TestKit
+import akka.util.duration._
+
+/**
+ * a Test to show some TestKit examples
+ */
+class TestKitUsageSpec
+  extends TestKit(ActorSystem("TestKitUsageSpec",
+    ConfigFactory.parseString(TestKitUsageSpec.config)))
+  with DefaultTimeout with ImplicitSender
+  with WordSpec with ShouldMatchers with BeforeAndAfterAll {
+  import TestKitUsageSpec._
+
+  val echoRef = system.actorOf(Props(new EchoActor))
+  val forwardRef = system.actorOf(Props(new ForwardingActor(testActor)))
+  val filterRef = system.actorOf(Props(new FilteringActor(testActor)))
+  val randomHead = Random.nextInt(6)
+  val randomTail = Random.nextInt(10)
+  val headList = Seq().padTo(randomHead, "0")
+  val tailList = Seq().padTo(randomTail, "1")
+  val seqRef = system.actorOf(Props(new SequencingActor(testActor, headList, tailList)))
+
+  override def afterAll {
+    system.shutdown()
+  }
+
+  "An EchoActor" should {
+    "Respond with the same message it receives" in {
+      within(500 millis) {
+        echoRef ! "test"
+        expectMsg("test")
+      }
+    }
+  }
+  "A ForwardingActor" should {
+    "Forward a message it receives" in {
+      within(500 millis) {
+        forwardRef ! "test"
+        expectMsg("test")
+      }
+    }
+  }
+  "A FilteringActor" should {
+    "Filter all messages, except expected messagetypes it receives" in {
+      var messages = Seq[String]()
+      within(500 millis) {
+        filterRef ! "test"
+        expectMsg("test")
+        filterRef ! 1
+        expectNoMsg
+        filterRef ! "some"
+        filterRef ! "more"
+        filterRef ! 1
+        filterRef ! "text"
+        filterRef ! 1
+
+        receiveWhile(500 millis) {
+          case msg: String ⇒ messages = msg +: messages
+        }
+      }
+      messages.length should be(3)
+      messages.reverse should be(Seq("some", "more", "text"))
+    }
+  }
+  "A SequencingActor" should {
+    "receive an interesting message at some point " in {
+      within(500 millis) {
+        ignoreMsg {
+          case msg: String ⇒ msg != "something"
+        }
+        seqRef ! "something"
+        expectMsg("something")
+        ignoreMsg {
+          case msg: String ⇒ msg == "1"
+        }
+        expectNoMsg
+        ignoreNoMsg
+      }
+    }
+  }
+}
+
+object TestKitUsageSpec {
+  // Define your test specific configuration here
+  val config = """
+    akka {
+      loglevel = "WARNING"
+    }
+    """
+
+  /**
+   * An Actor that echoes everything you send to it
+   */
+  class EchoActor extends Actor {
+    def receive = {
+      case msg ⇒ sender ! msg
+    }
+  }
+
+  /**
+   * An Actor that forwards every message to a next Actor
+   */
+  class ForwardingActor(next: ActorRef) extends Actor {
+    def receive = {
+      case msg ⇒ next ! msg
+    }
+  }
+
+  /**
+   * An Actor that only forwards certain messages to a next Actor
+   */
+  class FilteringActor(next: ActorRef) extends Actor {
+    def receive = {
+      case msg: String ⇒ next ! msg
+      case _           ⇒ None
+    }
+  }
+
+  /**
+   * An actor that sends a sequence of messages with a random head list, an
+   * interesting value and a random tail list. The idea is that you would
+   * like to test that the interesting value is received and that you cant
+   * be bothered with the rest
+   */
+  class SequencingActor(next: ActorRef, head: Seq[String], tail: Seq[String])
+    extends Actor {
+    def receive = {
+      case msg ⇒ {
+        head foreach { next ! _ }
+        next ! msg
+        tail foreach { next ! _ }
+      }
+    }
+  }
+}
+//#testkit-usage

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

@@ -0,0 +1,255 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.testkit
+
+//#imports-test-probe
+import akka.testkit.TestProbe
+import akka.util.duration._
+import akka.actor._
+import akka.dispatch.Futures
+
+//#imports-test-probe
+
+import akka.testkit.AkkaSpec
+import akka.testkit.DefaultTimeout
+import akka.testkit.ImplicitSender
+object TestkitDocSpec {
+  case object Say42
+  case object Unknown
+
+  class MyActor extends Actor {
+    def receive = {
+      case Say42       ⇒ sender ! 42
+      case "some work" ⇒ sender ! "some result"
+    }
+  }
+
+  //#my-double-echo
+  class MyDoubleEcho extends Actor {
+    var dest1: ActorRef = _
+    var dest2: ActorRef = _
+    def receive = {
+      case (d1: ActorRef, d2: ActorRef) ⇒
+        dest1 = d1
+        dest2 = d2
+      case x ⇒
+        dest1 ! x
+        dest2 ! x
+    }
+  }
+
+  //#my-double-echo
+
+  import akka.testkit.TestProbe
+
+  //#test-probe-forward-actors
+  class Source(target: ActorRef) extends Actor {
+    def receive = {
+      case "start" ⇒ target ! "work"
+    }
+  }
+
+  class Destination extends Actor {
+    def receive = {
+      case x ⇒ // Do something..
+    }
+  }
+
+  //#test-probe-forward-actors
+
+  class LoggingActor extends Actor {
+    //#logging-receive
+    import akka.event.LoggingReceive
+    def receive = LoggingReceive {
+      case msg ⇒ // Do something...
+    }
+    //#logging-receive
+  }
+}
+
+class TestkitDocSpec extends AkkaSpec with DefaultTimeout with ImplicitSender {
+  import TestkitDocSpec._
+
+  "demonstrate usage of TestActorRef" in {
+    //#test-actor-ref
+    import akka.testkit.TestActorRef
+
+    val actorRef = TestActorRef[MyActor]
+    val actor = actorRef.underlyingActor
+    //#test-actor-ref
+  }
+
+  "demonstrate usage of TestFSMRef" in {
+    //#test-fsm-ref
+    import akka.testkit.TestFSMRef
+    import akka.actor.FSM
+    import akka.util.duration._
+
+    val fsm = TestFSMRef(new Actor with FSM[Int, String] {
+      startWith(1, "")
+      when(1) {
+        case Event("go", _) ⇒ goto(2) using "go"
+      }
+      when(2) {
+        case Event("back", _) ⇒ goto(1) using "back"
+      }
+    })
+
+    assert(fsm.stateName == 1)
+    assert(fsm.stateData == "")
+    fsm ! "go" // being a TestActorRef, this runs also on the CallingThreadDispatcher
+    assert(fsm.stateName == 2)
+    assert(fsm.stateData == "go")
+
+    fsm.setState(stateName = 1)
+    assert(fsm.stateName == 1)
+
+    assert(fsm.timerActive_?("test") == false)
+    fsm.setTimer("test", 12, 10 millis, true)
+    assert(fsm.timerActive_?("test") == true)
+    fsm.cancelTimer("test")
+    assert(fsm.timerActive_?("test") == false)
+    //#test-fsm-ref
+  }
+
+  "demonstrate testing of behavior" in {
+
+    //#test-behavior
+    import akka.testkit.TestActorRef
+    import akka.util.duration._
+    import akka.dispatch.Await
+    import akka.pattern.ask
+
+    val actorRef = TestActorRef(new MyActor)
+    // hypothetical message stimulating a '42' answer
+    val result = Await.result((actorRef ? Say42), 5 seconds).asInstanceOf[Int]
+    result must be(42)
+    //#test-behavior
+  }
+
+  "demonstrate unhandled message" in {
+    //#test-unhandled
+    import akka.testkit.TestActorRef
+    system.eventStream.subscribe(testActor, classOf[UnhandledMessage])
+    val ref = TestActorRef[MyActor]
+    ref.receive(Unknown)
+    expectMsg(1 second, UnhandledMessage(Unknown, system.deadLetters, ref))
+    //#test-unhandled
+  }
+
+  "demonstrate expecting exceptions" in {
+    //#test-expecting-exceptions
+    import akka.testkit.TestActorRef
+
+    val actorRef = TestActorRef(new Actor {
+      def receive = {
+        case boom ⇒ throw new IllegalArgumentException("boom")
+      }
+    })
+    intercept[IllegalArgumentException] { actorRef.receive("hello") }
+    //#test-expecting-exceptions
+  }
+
+  "demonstrate within" in {
+    type Worker = MyActor
+    //#test-within
+    import akka.actor.Props
+    import akka.util.duration._
+
+    val worker = system.actorOf(Props[Worker])
+    within(200 millis) {
+      worker ! "some work"
+      expectMsg("some result")
+      expectNoMsg // will block for the rest of the 200ms
+      Thread.sleep(300) // will NOT make this block fail
+    }
+    //#test-within
+  }
+
+  "demonstrate dilated duration" in {
+    //#duration-dilation
+    import akka.util.duration._
+    import akka.testkit._
+    10.milliseconds.dilated
+    //#duration-dilation
+  }
+
+  "demonstrate usage of probe" in {
+    //#test-probe
+    val probe1 = TestProbe()
+    val probe2 = TestProbe()
+    val actor = system.actorOf(Props[MyDoubleEcho])
+    actor ! (probe1.ref, probe2.ref)
+    actor ! "hello"
+    probe1.expectMsg(500 millis, "hello")
+    probe2.expectMsg(500 millis, "hello")
+    //#test-probe
+
+    //#test-special-probe
+    case class Update(id: Int, value: String)
+
+    val probe = new TestProbe(system) {
+      def expectUpdate(x: Int) = {
+        expectMsgPF() {
+          case Update(id, _) if id == x ⇒ true
+        }
+        sender ! "ACK"
+      }
+    }
+    //#test-special-probe
+  }
+
+  "demonstrate probe reply" in {
+    import akka.testkit.TestProbe
+    import akka.util.duration._
+    import akka.pattern.ask
+    //#test-probe-reply
+    val probe = TestProbe()
+    val future = probe.ref ? "hello"
+    probe.expectMsg(0 millis, "hello") // TestActor runs on CallingThreadDispatcher
+    probe.sender ! "world"
+    assert(future.isCompleted && future.value == Some(Right("world")))
+    //#test-probe-reply
+  }
+
+  "demonstrate probe forward" in {
+    import akka.testkit.TestProbe
+    import akka.actor.Props
+    //#test-probe-forward
+    val probe = TestProbe()
+    val source = system.actorOf(Props(new Source(probe.ref)))
+    val dest = system.actorOf(Props[Destination])
+    source ! "start"
+    probe.expectMsg("work")
+    probe.forward(dest)
+    //#test-probe-forward
+  }
+
+  "demonstrate " in {
+    //#calling-thread-dispatcher
+    import akka.testkit.CallingThreadDispatcher
+    val ref = system.actorOf(Props[MyActor].withDispatcher(CallingThreadDispatcher.Id))
+    //#calling-thread-dispatcher
+  }
+
+  "demonstrate EventFilter" in {
+    //#event-filter
+    import akka.testkit.EventFilter
+    import com.typesafe.config.ConfigFactory
+
+    implicit val system = ActorSystem("testsystem", ConfigFactory.parseString("""
+      akka.event-handlers = ["akka.testkit.TestEventListener"]
+      """))
+    try {
+      val actor = system.actorOf(Props.empty)
+      EventFilter[ActorKilledException](occurrences = 1) intercept {
+        actor ! Kill
+      }
+    } finally {
+      system.shutdown()
+    }
+    //#event-filter
+  }
+
+}