Package org.apache.pekko.testkit.javadsl

Class TestKit

java.lang.Object
org.apache.pekko.testkit.javadsl.TestKit
public class TestKit extends 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 pekko.conf entry "pekko.test.timefactor".

  • Constructor Details

  • Method Details

    • shutdownActorSystem

      public static void shutdownActorSystem(ActorSystem actorSystem, scala.concurrent.duration.Duration duration, 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)
      Shut down an actor system and wait for termination. On failure debug output will be logged about the remaining actors in the system.

    • shutdownActorSystem

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

    • shutdownActorSystem

      public static void shutdownActorSystem(ActorSystem actorSystem, 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, Duration duration)
      Shut down an actor system and wait for termination. On failure debug output will be logged about the remaining actors in the system.

      The duration is dilated by the timefactor. This overloaded method accepts java.time.Duration.

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

      Since:
      1.3.0

    • shutdownActorSystem

      public static void shutdownActorSystem(ActorSystem actorSystem, Duration duration, 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.

      The duration is dilated by the timefactor. This overloaded method accepts java.time.Duration.

      Since:
      1.3.0

    • expectMsgAnyOf

      public <T> T expectMsgAnyOf(T first, Object... objs)
      Same as expectMsgAnyOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    • expectMsgAnyOfWithin

      public <T> T expectMsgAnyOfWithin(Duration max, Object... objs)
      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.

    • expectMsgAllOf

      public <T> List<T> expectMsgAllOf(Object... objs)
      Same as expectMsgAllOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    • expectMsgAllOfWithin

      public <T> List<T> expectMsgAllOfWithin(Duration max, Object... objs)
      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(Class<?>... objs)
      Same as expectMsgAnyClassOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    • expectMsgAnyClassOf

      public <T> T expectMsgAnyClassOf(Duration max, Class<?>... objs)
      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.

    • 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 scala.concurrent.duration.FiniteDuration duration(String s)

    • dilated

      public Duration dilated(Duration duration)
      Java timeouts (durations) during tests with the configured

    • msgAvailable

      public boolean msgAvailable()
      Query queue status.

    • getLastSender

      public ActorRef getLastSender()
      Get the last sender of the TestProbe

    • send

      public void send(ActorRef actor, Object msg)
      Send message to an actor while using the probe's TestActor as the sender. Replies will be available for inspection with all of TestKit's assertion methods.

    • forward

      public void forward(ActorRef actor)
      Forward this message as if in the TestActor's receive method with self.forward.

    • reply

      public void reply(Object msg)
      Send message to the sender of the last dequeued message.

    • watch

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

    • unwatch

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

    • ignoreMsg

      public void ignoreMsg(Function<Object,Object> pf)
      Ignore all messages in the test actor for which the given partial function returns true.

    • 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.

    • getRemaining

      public Duration getRemaining()
      Obtain time remaining for execution of the innermost enclosing within block or throw an AssertionError if no within block surrounds this call.

    • getRemainingOr

      public Duration getRemainingOr(Duration duration)
      Obtain time remaining for execution of the innermost enclosing within block or missing that it returns the given duration.

    • getRemainingOrDefault

      public Duration getRemainingOrDefault()
      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 "pekko.test.single-expect-default").

    • within

      public <T> T within(Duration min, Duration max, Supplier<T> f)
      Execute code block while bounding its execution time between min and max. within blocks may be nested. All methods in this trait which take maximum wait times are available in a version which implicitly uses the remaining time governed by the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor", while the min Duration is not. 

      

  within(java.time.Duration.ofMillis(50), () -> {
    test.tell("ping");
    return expectMsgClass(String.class);
  });

    • within

      public <T> T within(Duration max, Supplier<T> f)
      Execute code block while bounding its execution time between min and max. within blocks may be nested. All methods in this trait which take maximum wait times are available in a version which implicitly uses the remaining time governed by the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor", while the min Duration is not. 

      

  within(java.time.Duration.ofMillis(50), () -> {
    test.tell("ping");
    return expectMsgClass(String.class);
  });

    • awaitCond

      public void awaitCond(Supplier<Object> p)
      Await until the given condition evaluates to true or the timeout expires, whichever comes first.

      If no timeout is given, take it from the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

    • awaitCond

      public void awaitCond(Duration max, Supplier<Object> p)
      Await until the given condition evaluates to true or the timeout expires, whichever comes first.

      If no timeout is given, take it from the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

    • awaitCond

      public void awaitCond(Duration max, Duration interval, Supplier<Object> p)
      Await until the given condition evaluates to true or the timeout expires, whichever comes first.

      If no timeout is given, take it from the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

    • awaitCond

      public void awaitCond(Duration max, Duration interval, String message, Supplier<Object> p)
      Await until the given condition evaluates to true or the timeout expires, whichever comes first.

      If no timeout is given, take it from the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

    • awaitAssert

      public <A> A awaitAssert(Supplier<A> a)
      Evaluate the given assert every interval until it does not throw an exception and return the result.

      If the max timeout expires the last exception is thrown.

      If no timeout is given, take it from the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

    • awaitAssert

      public <A> A awaitAssert(Duration max, Supplier<A> a)
      Evaluate the given assert every interval until it does not throw an exception and return the result.

      If the max timeout expires the last exception is thrown.

      If no timeout is given, take it from the innermost enclosing within block.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

    • awaitAssert

      public <A> A awaitAssert(Duration max, Duration interval, Supplier<A> a)
      Evaluate the given assert every interval until it does not throw an exception. If the max timeout expires the last exception is thrown.

      Note that the timeout is scaled using Duration.dilated, which uses the configuration entry "pekko.test.timefactor".

      Returns:
      an arbitrary value that would be returned from awaitAssert if successful, if not interested in such value you can return null.

    • expectMsgEquals

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

    • expectMsgEquals

      public <T> T expectMsgEquals(Duration max, T obj)
      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

    • expectMsg

      public <T> T expectMsg(T obj)
      Same as expectMsg(remainingOrDefault, obj), but correctly treating the timeFactor.

    • expectMsg

      public <T> T expectMsg(Duration max, T obj)
      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.

    • expectMsg

      public <T> T expectMsg(Duration max, T obj, String hint)
      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.

    • expectMsgPF

      public <T> T expectMsgPF(String hint, Function<Object,T> f)
      Receive one message from the test actor and assert that the given partial function accepts it. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

      Use this variant to implement more complicated or conditional processing.

    • expectMsgPF

      public <T> T expectMsgPF(Duration max, String hint, Function<Object,T> f)
      Receive one message from the test actor and assert that the given partial function accepts it. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

      Use this variant to implement more complicated or conditional processing.

    • expectMsgClass

      public <T> T expectMsgClass(Class<T> c)
      Same as expectMsgClass(remainingOrDefault, c), but correctly treating the timeFactor.

    • expectMsgClass

      public <T> T expectMsgClass(Duration max, Class<T> c)
      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.

    • expectMsgAnyOf

      public <T> T expectMsgAnyOf(T first, scala.collection.immutable.Seq<T> objs)
      Same as expectMsgAnyOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    • expectMsgAnyOfWithin

      public <T> T expectMsgAnyOfWithin(Duration max, scala.collection.immutable.Seq<T> objs)
      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.

    • expectMsgAllOf

      public <T> List<T> expectMsgAllOf(scala.collection.immutable.Seq<T> objs)
      Same as expectMsgAllOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    • expectMsgAllOfWithin

      public <T> List<T> expectMsgAllOfWithin(Duration max, scala.collection.immutable.Seq<T> objs)
      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(scala.collection.immutable.Seq<Class<?>> objs)
      Same as expectMsgAnyClassOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    • expectMsgAnyClassOf

      public <T> T expectMsgAnyClassOf(Duration max, scala.collection.immutable.Seq<Class<?>> objs)
      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.

    • expectNoMessage

      public void expectNoMessage()
      Assert that no message is received. Waits for the default period configured as pekko.actor.testkit.expect-no-message-default. That timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".

    • expectNoMessage

      public void expectNoMessage(Duration max)
      Assert that no message is received for the specified time. Supplied value is not dilated.

    • expectTerminated

      public Terminated expectTerminated(Duration max, ActorRef target)
      Receive one message from the test actor and assert that it is the Terminated message of the given ActorRef. Before calling this method, you have to watch the target actor ref. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

      Parameters:
      max - wait no more than max time, otherwise throw AssertionFailure
      target - the actor ref expected to be Terminated
      Returns:
      the received Terminated message

    • expectTerminated

      public Terminated expectTerminated(ActorRef target)
      Receive one message from the test actor and assert that it is the Terminated message of the given ActorRef. Before calling this method, you have to watch the target actor ref. Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

      Parameters:
      target - the actor ref expected to be Terminated
      Returns:
      the received Terminated message

    • fishForMessage

      public Object fishForMessage(Duration max, String hint, Function<Object,Object> f)
      Hybrid of expectMsgPF and receiveWhile: receive messages while the partial function matches and returns false. Use it to ignore certain messages while waiting for a specific message.

      Returns:
      the last received message, i.e. the first one for which the partial function returned true

    • fishForSpecificMessage

      public <T> T fishForSpecificMessage(Duration max, String hint, Function<Object,T> f)
      Same as fishForMessage, but gets a different partial function and returns properly typed message.

    • receiveN

      public List<Object> receiveN(int n)
      Same as receiveN(n, remaining) but correctly taking into account Duration.timeFactor.

    • receiveN

      public List<Object> receiveN(int n, Duration max)
      Receive N messages in a row before the given deadline.

    • receiveOne

      public Object receiveOne(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!

    • receiveWhile

      public <T> List<T> receiveWhile(Duration max, Duration idle, int messages, Function<Object,T> f)
      Receive a series of messages until one does not match the given partial function or the idle timeout is met (disabled by default) or the overall maximum duration is elapsed or expected messages count is reached. Returns the sequence of messages.

      Note that it is not an error to hit the max duration in this case.

      One possible use of this method is for testing whether messages of certain characteristics are generated at a certain rate:

    • receiveWhile

      public <T> List<T> receiveWhile(Duration max, Function<Object,T> f)

    • childActorOf

      public ActorRef childActorOf(Props props, String name, SupervisorStrategy supervisorStrategy)
      Spawns an actor as a child of this test actor, and returns the child's ActorRef.

    • childActorOf

      public ActorRef childActorOf(Props props, SupervisorStrategy supervisorStrategy)
      Spawns an actor as a child of this test actor with an auto-generated name, and returns the child's ActorRef.

    • childActorOf

      public ActorRef childActorOf(Props props, String name)
      Spawns an actor as a child of this test actor with a stopping supervisor strategy, and returns the child's ActorRef.

    • childActorOf

      public ActorRef childActorOf(Props props)
      Spawns an actor as a child of this test actor with an auto-generated name and stopping supervisor strategy, returning the child's ActorRef.