akka.testkit
Class JavaTestKit

java.lang.Object
  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:

• the ActorSystem passed into the constructor needs to be shutdown, otherwise thread pools and memory will be leaked - this trait is not thread-safe (only one actor with one queue, one stack of Within blocks); take care not to run tests within a single test class instance in parallel.
• It should be noted that for CI servers and the like all maximum Durations are scaled using the dilated method, which uses the TestKitExtension.Settings.TestTimeFactor settable via akka.conf entry "akka.test.timefactor".

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)