akka.testkit
Class JavaTestKit

java.lang.Object
  extended by akka.testkit.JavaTestKit

public class JavaTestKit
extends java.lang.Object

Java API: Test kit for testing actors. Inheriting from this class enables reception of replies from actors, which are queued by an internal actor and can be examined using the expectMsg... methods. Assertions and bounds concerning timing are available in the form of Within blocks.

Beware of two points:


Nested Class Summary
 class JavaTestKit.AwaitAssert
          Await until the given assert does not throw an exception or the timeout expires, whichever comes first.
 class JavaTestKit.AwaitCond
          Await until the given condition evaluates to true or the timeout expires, whichever comes first.
 class JavaTestKit.EventFilter<T>
          Facilities for selectively filtering out expected events from logging so that you can keep your test run‚Äôs console output clean and do not miss real error messages.
 class JavaTestKit.ExpectMsg<T>
          Receive one message from the test actor and assert that the given matching function accepts it.
 class JavaTestKit.IgnoreMsg
          Ignore all messages in the test actor for which the given function returns true.
 class JavaTestKit.ReceiveWhile<T>
          Receive a series of messages until one does not match the given match function or the idle timeout is met (disabled by default) or the overall maximum duration is elapsed.
 class JavaTestKit.Within
          Execute code block while bounding its execution time between min and max.
 
Constructor Summary
JavaTestKit(ActorSystem system)
           
 
Method Summary
 scala.concurrent.duration.Duration dilated(scala.concurrent.duration.Duration d)
           
static scala.concurrent.duration.FiniteDuration duration(java.lang.String s)
           
 java.lang.Object[] expectMsgAllOf(scala.concurrent.duration.FiniteDuration max, java.lang.Object... msgs)
          Receive a number of messages from the test actor matching the given number of objects and assert that for each given object one is received which equals it and vice versa.
 java.lang.Object[] expectMsgAllOf(java.lang.Object... msgs)
          Same as expectMsgAllOf(remaining(), obj...), but correctly treating the timeFactor.
<T> T
expectMsgAnyClassOf(java.lang.Class<? extends T>... classes)
          Same as expectMsgAnyClassOf(remaining(), obj...), but correctly treating the timeFactor.
 java.lang.Object expectMsgAnyClassOf(scala.concurrent.duration.FiniteDuration max, java.lang.Class<?>... classes)
          Receive one message from the test actor and assert that it conforms to one of the given classes.
 java.lang.Object expectMsgAnyOf(scala.concurrent.duration.FiniteDuration max, java.lang.Object... msgs)
          Receive one message from the test actor and assert that it equals one of the given objects.
 java.lang.Object expectMsgAnyOf(java.lang.Object... msgs)
          Same as expectMsgAnyOf(remaining(), obj...), but correctly treating the timeFactor.
<T> T
expectMsgClass(java.lang.Class<T> clazz)
          Same as expectMsgClass(remaining(), clazz), but correctly treating the timeFactor.
<T> T
expectMsgClass(scala.concurrent.duration.FiniteDuration max, java.lang.Class<T> clazz)
          Receive one message from the test actor and assert that it conforms to the given class.
<T> T
expectMsgEquals(scala.concurrent.duration.FiniteDuration max, T msg)
          Receive one message from the test actor and assert that it equals the given object.
<T> T
expectMsgEquals(T msg)
          Same as expectMsgEquals(remaining(), obj), but correctly treating the timeFactor.
 void expectNoMsg()
          Same as expectNoMsg(remaining()), but correctly treating the timeFactor.
 void expectNoMsg(scala.concurrent.duration.FiniteDuration max)
          Assert that no message is received for the specified time.
 Terminated expectTerminated(ActorRef target)
          Same as expectTerminated(remaining(), target), but correctly treating the timeFactor.
 Terminated expectTerminated(scala.concurrent.duration.Duration max, ActorRef target)
          Assert that the given ActorRef is Terminated within the specified time.
 void forward(ActorRef actor)
           
 ActorRef getLastSender()
           
 ActorRef getRef()
          Shorthand to get the testActor.
 scala.concurrent.duration.FiniteDuration getRemainingTime()
           
 scala.concurrent.duration.FiniteDuration getRemainingTimeOr(scala.concurrent.duration.FiniteDuration def)
           
 ActorSystem getSystem()
           
 ActorRef getTestActor()
          ActorRef of the test actor.
 void ignoreNoMsg()
          Stop ignoring messages in the test actor.
 boolean msgAvailable()
          Query queue status.
 java.lang.Object[] receiveN(int n)
          Same as receiveN(n, remaining()), but correctly treating the timeFactor.
 java.lang.Object[] receiveN(int n, scala.concurrent.duration.FiniteDuration max)
          Receive N messages in a row before the given deadline.
 java.lang.Object receiveOne(scala.concurrent.duration.Duration max)
          Receive one message from the internal queue of the TestActor.
 scala.concurrent.duration.FiniteDuration remaining()
          Obtain time remaining for execution of the innermost enclosing Within block or missing that it returns the properly dilated default for this case from settings (key "akka.test.single-expect-default").
 scala.concurrent.duration.FiniteDuration remainingOr(scala.concurrent.duration.FiniteDuration duration)
          Obtain time remaining for execution of the innermost enclosing Within block or missing that it returns the given duration.
 void reply(java.lang.Object msg)
           
 void send(ActorRef actor, java.lang.Object msg)
           
 void setAutoPilot(TestActor.AutoPilot pilot)
          Install an AutoPilot to drive the testActor: the AutoPilot will be run for each received message and can be used to send or forward messages, etc.
 void shutdown(ActorSystem actorSystem)
           
 void shutdown(ActorSystem actorSystem, java.lang.Boolean verifySystemShutdown)
           
 void shutdown(ActorSystem actorSystem, scala.concurrent.duration.Duration duration)
           
 void shutdown(ActorSystem actorSystem, scala.concurrent.duration.Duration duration, java.lang.Boolean verifySystemShutdown)
          Shut down an actor system and wait for termination.
static void shutdownActorSystem(ActorSystem actorSystem)
           
 void shutdownActorSystem(ActorSystem actorSystem, java.lang.Boolean verifySystemShutdown)
           
 void shutdownActorSystem(ActorSystem actorSystem, scala.concurrent.duration.Duration duration)
           
static void shutdownActorSystem(ActorSystem actorSystem, scala.concurrent.duration.Duration duration, java.lang.Boolean verifySystemShutdown)
          Shut down an actor system and wait for termination.
 ActorRef unwatch(ActorRef ref)
          Have the testActor stop watching someone (i.e.
 ActorRef watch(ActorRef ref)
          Have the testActor watch someone (i.e.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JavaTestKit

public JavaTestKit(ActorSystem system)
Method Detail

shutdownActorSystem

public static void shutdownActorSystem(ActorSystem actorSystem,
                                       scala.concurrent.duration.Duration duration,
                                       java.lang.Boolean verifySystemShutdown)
Shut down an actor system and wait for termination. On failure debug output will be logged about the remaining actors in the system.

If verifySystemShutdown is true, then an exception will be thrown on failure.


shutdownActorSystem

public static void shutdownActorSystem(ActorSystem actorSystem)

shutdownActorSystem

public void shutdownActorSystem(ActorSystem actorSystem,
                                scala.concurrent.duration.Duration duration)

shutdownActorSystem

public void shutdownActorSystem(ActorSystem actorSystem,
                                java.lang.Boolean verifySystemShutdown)

getTestActor

public ActorRef getTestActor()
ActorRef of the test actor. Access is provided to enable e.g. registration as message target.


getRef

public ActorRef getRef()
Shorthand to get the testActor.


getSystem

public ActorSystem getSystem()

duration

public static scala.concurrent.duration.FiniteDuration duration(java.lang.String s)

dilated

public scala.concurrent.duration.Duration dilated(scala.concurrent.duration.Duration d)

msgAvailable

public boolean msgAvailable()
Query queue status.


getLastSender

public ActorRef getLastSender()

send

public void send(ActorRef actor,
                 java.lang.Object msg)

forward

public void forward(ActorRef actor)

reply

public void reply(java.lang.Object msg)

getRemainingTime

public scala.concurrent.duration.FiniteDuration getRemainingTime()

getRemainingTimeOr

public scala.concurrent.duration.FiniteDuration getRemainingTimeOr(scala.concurrent.duration.FiniteDuration def)

watch

public ActorRef watch(ActorRef ref)
Have the testActor watch someone (i.e. getContext().getWatch(...) ).


unwatch

public ActorRef unwatch(ActorRef ref)
Have the testActor stop watching someone (i.e. getContext.unwatch(...)).


ignoreNoMsg

public void ignoreNoMsg()
Stop ignoring messages in the test actor.


setAutoPilot

public void setAutoPilot(TestActor.AutoPilot pilot)
Install an AutoPilot to drive the testActor: the AutoPilot will be run for each received message and can be used to send or forward messages, etc. Each invocation must return the AutoPilot for the next round.


remaining

public scala.concurrent.duration.FiniteDuration remaining()
Obtain time remaining for execution of the innermost enclosing Within block or missing that it returns the properly dilated default for this case from settings (key "akka.test.single-expect-default").


remainingOr

public scala.concurrent.duration.FiniteDuration remainingOr(scala.concurrent.duration.FiniteDuration duration)
Obtain time remaining for execution of the innermost enclosing Within block or missing that it returns the given duration.


expectMsgEquals

public <T> T expectMsgEquals(T msg)
Same as expectMsgEquals(remaining(), obj), but correctly treating the timeFactor.


expectMsgEquals

public <T> T expectMsgEquals(scala.concurrent.duration.FiniteDuration max,
                             T msg)
Receive one message from the test actor and assert that it equals the given object. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

Returns:
the received object

expectMsgClass

public <T> T expectMsgClass(java.lang.Class<T> clazz)
Same as expectMsgClass(remaining(), clazz), but correctly treating the timeFactor.


expectMsgClass

public <T> T expectMsgClass(scala.concurrent.duration.FiniteDuration max,
                            java.lang.Class<T> clazz)
Receive one message from the test actor and assert that it conforms to the given class. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

Returns:
the received object

expectMsgAnyOf

public java.lang.Object expectMsgAnyOf(java.lang.Object... msgs)
Same as expectMsgAnyOf(remaining(), obj...), but correctly treating the timeFactor.


expectMsgAnyOf

public java.lang.Object expectMsgAnyOf(scala.concurrent.duration.FiniteDuration max,
                                       java.lang.Object... msgs)
Receive one message from the test actor and assert that it equals one of the given objects. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

Returns:
the received object

expectMsgAllOf

public java.lang.Object[] expectMsgAllOf(java.lang.Object... msgs)
Same as expectMsgAllOf(remaining(), obj...), but correctly treating the timeFactor.


expectMsgAllOf

public java.lang.Object[] expectMsgAllOf(scala.concurrent.duration.FiniteDuration max,
                                         java.lang.Object... msgs)
Receive a number of messages from the test actor matching the given number of objects and assert that for each given object one is received which equals it and vice versa. This construct is useful when the order in which the objects are received is not fixed. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.


expectMsgAnyClassOf

public <T> T expectMsgAnyClassOf(java.lang.Class<? extends T>... classes)
Same as expectMsgAnyClassOf(remaining(), obj...), but correctly treating the timeFactor.


expectMsgAnyClassOf

public java.lang.Object expectMsgAnyClassOf(scala.concurrent.duration.FiniteDuration max,
                                            java.lang.Class<?>... classes)
Receive one message from the test actor and assert that it conforms to one of the given classes. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

Returns:
the received object

expectNoMsg

public void expectNoMsg()
Same as expectNoMsg(remaining()), but correctly treating the timeFactor.


expectNoMsg

public void expectNoMsg(scala.concurrent.duration.FiniteDuration max)
Assert that no message is received for the specified time.


expectTerminated

public Terminated expectTerminated(scala.concurrent.duration.Duration max,
                                   ActorRef target)
Assert that the given ActorRef is Terminated within the specified time. Don't forget to 'watch' it first!


expectTerminated

public Terminated expectTerminated(ActorRef target)
Same as expectTerminated(remaining(), target), but correctly treating the timeFactor. Don't forget to 'watch' it first!


receiveN

public java.lang.Object[] receiveN(int n)
Same as receiveN(n, remaining()), but correctly treating the timeFactor.


receiveN

public java.lang.Object[] receiveN(int n,
                                   scala.concurrent.duration.FiniteDuration max)
Receive N messages in a row before the given deadline.


receiveOne

public java.lang.Object receiveOne(scala.concurrent.duration.Duration max)
Receive one message from the internal queue of the TestActor. If the given duration is zero, the queue is polled (non-blocking).

This method does NOT automatically scale its Duration parameter!


shutdown

public void shutdown(ActorSystem actorSystem,
                     scala.concurrent.duration.Duration duration,
                     java.lang.Boolean verifySystemShutdown)
Shut down an actor system and wait for termination. On failure debug output will be logged about the remaining actors in the system.

If verifySystemShutdown is true, then an exception will be thrown on failure.


shutdown

public void shutdown(ActorSystem actorSystem)

shutdown

public void shutdown(ActorSystem actorSystem,
                     scala.concurrent.duration.Duration duration)

shutdown

public void shutdown(ActorSystem actorSystem,
                     java.lang.Boolean verifySystemShutdown)