Package org.apache.pekko.actor.testkit.typed.javadsl

Class TestProbe<M>

  • All Implemented Interfaces:
    RecipientRef<M>
    public abstract class TestProbe<M>
extends java.lang.Object
implements RecipientRef<M>
    Java API: * Create instances through the create factories in the TestProbe companion or via ActorTestKit.createTestProbe().

    A test probe is essentially a queryable mailbox which can be used in place of an actor and the received messages can then be asserted etc.

    Not for user extension

    • Constructor Summary

      Constructors 
      Constructor Description
      TestProbe()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract <A> A awaitAssert​(java.time.Duration max, java.time.Duration interval, Creator<A> creator)
      Evaluate the given assert every interval until it does not throw an exception and return the result.
      abstract <A> A awaitAssert​(java.time.Duration max, Creator<A> creator)
      Evaluate the given assert every 100 milliseconds until it does not throw an exception and return the result.
      abstract <A> A awaitAssert​(Creator<A> creator)
      Evaluate the given assert every 100 milliseconds until it does not throw an exception and return the result.
      static <M> TestProbe<M> create​(java.lang.Class<M> clazz, ActorSystem<?> system)  
      static <M> TestProbe<M> create​(java.lang.String name, java.lang.Class<M> clazz, ActorSystem<?> system)  
      static <M> TestProbe<M> create​(java.lang.String name, ActorSystem<?> system)  
      static <M> TestProbe<M> create​(ActorSystem<?> system)  
      abstract <T extends M>
      T      		 expectMessage​(java.time.Duration max, java.lang.String hint, T obj)
      Receive one message from the test actor and assert that it equals the given object.
      abstract <T extends M>
      T      		 expectMessage​(java.time.Duration max, T obj)
      Receive one message from the test actor and assert that it equals the given object.
      abstract <T extends M>
      T      		 expectMessage​(T obj)
      Same as expectMessage(remainingOrDefault, obj), but using the default timeout as deadline.
      abstract <T extends M>
      T      		 expectMessageClass​(java.lang.Class<T> clazz)
      Same as expectMessageType(clazz, remainingOrDefault),but using the default timeout as deadline.
      abstract <T extends M>
      T      		 expectMessageClass​(java.lang.Class<T> clazz, java.time.Duration max)
      Wait for a message of type M and return it when it arrives, or fail if the max timeout is hit.
      abstract void expectNoMessage()
      Assert that no message is received.
      abstract void expectNoMessage​(java.time.Duration max)
      Assert that no message is received for the specified time.
      abstract <U> void expectTerminated​(ActorRef<U> actorRef)
      Expect the given actor to be stopped or stop within the default timeout.
      abstract <U> void expectTerminated​(ActorRef<U> actorRef, java.time.Duration max)
      Expect the given actor to be stopped or stop within the given timeout or throw an AssertionError.
      abstract java.util.List<M> fishForMessage​(java.time.Duration max, java.lang.String hint, java.util.function.Function<M,​FishingOutcome> fisher)
      Same as the other fishForMessage but includes the provided hint in all error messages
      abstract java.util.List<M> fishForMessage​(java.time.Duration max, java.util.function.Function<M,​FishingOutcome> fisher)
      Java API: Allows for flexible matching of multiple messages within a timeout, the fisher function is fed each incoming message, and returns one of the following effects to decide on what happens next:
      ActorRef<M> getRef()
      ActorRef for this TestProbe
      abstract java.time.Duration getRemaining()
      Obtain time remaining for execution of the innermost enclosing within block or throw an AssertionError if no within block surrounds this call.
      abstract java.time.Duration getRemainingOr​(java.time.Duration duration)
      Obtain time remaining for execution of the innermost enclosing within block or missing that it returns the given duration.
      abstract java.time.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.actor.testkit.typed.single-expect-default").
      abstract M receiveMessage()
      Receive one message of type M within the default timeout as deadline.
      abstract M receiveMessage​(java.time.Duration max)
      Receive one message of type M.
      abstract java.util.List<M> receiveSeveralMessages​(int n)
      Same as receiveSeveralMessages(n, remaining) but using the default timeout as deadline.
      abstract java.util.List<M> receiveSeveralMessages​(int n, java.time.Duration max)
      Receive n messages in a row before the given deadline.
      abstract ActorRef<M> ref()
      ActorRef for this TestProbe
      protected abstract TestKitSettings settings()  
      abstract void stop()
      Stops the TestProbe.getRef, which is useful when testing watch and termination.
      abstract <T> T within​(java.time.Duration min, java.time.Duration max, java.util.function.Supplier<T> f)
      Execute code block while bounding its execution time between min and max.
      abstract <T> T within​(java.time.Duration max, java.util.function.Supplier<T> f)
      Same as calling within(0 seconds, max)(f).

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • TestProbe

        public TestProbe()

    • Method Detail

      • create

        public static <M> TestProbe<M> create​(java.lang.Class<M> clazz,
                                      ActorSystem<?> system)

      • create

        public static <M> TestProbe<M> create​(java.lang.String name,
                                      ActorSystem<?> system)

      • create

        public static <M> TestProbe<M> create​(java.lang.String name,
                                      java.lang.Class<M> clazz,
                                      ActorSystem<?> system)

      • ref

        public abstract ActorRef<M> ref()
        ActorRef for this TestProbe

      • getRef

        public ActorRef<M> getRef()
        ActorRef for this TestProbe

      • getRemainingOrDefault

        public abstract java.time.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.actor.testkit.typed.single-expect-default").

      • getRemaining

        public abstract java.time.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 abstract java.time.Duration getRemainingOr​(java.time.Duration duration)
        Obtain time remaining for execution of the innermost enclosing within block or missing that it returns the given duration.

      • within

        public abstract <T> T within​(java.time.Duration min,
                             java.time.Duration max,
                             java.util.function.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 max timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor", while the min Duration is not. 

        
 val ret = within(50 millis) {
   test ! Ping
   expectMessageType[Pong]
 }

      • within

        public abstract <T> T within​(java.time.Duration max,
                             java.util.function.Supplier<T> f)
        Same as calling within(0 seconds, max)(f).

      • expectMessage

        public abstract <T extends M> T expectMessage​(T obj)
        Same as expectMessage(remainingOrDefault, obj), but using the default timeout as deadline.

      • expectMessage

        public abstract <T extends M> T expectMessage​(java.time.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 AssertionError being thrown in case of timeout.

        Returns:
        the received object

      • expectMessage

        public abstract <T extends M> T expectMessage​(java.time.Duration max,
                                              java.lang.String hint,
                                              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 AssertionError being thrown in case of timeout.

        Returns:
        the received object

      • expectNoMessage

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

      • expectNoMessage

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

      • expectMessageClass

        public abstract <T extends M> T expectMessageClass​(java.lang.Class<T> clazz)
        Same as expectMessageType(clazz, remainingOrDefault),but using the default timeout as deadline.

      • expectMessageClass

        public abstract <T extends M> T expectMessageClass​(java.lang.Class<T> clazz,
                                                   java.time.Duration max)
        Wait for a message of type M and return it when it arrives, or fail if the max timeout is hit.

        Note that the timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".

      • receiveMessage

        public abstract M receiveMessage()
        Receive one message of type M within the default timeout as deadline.

      • receiveMessage

        public abstract M receiveMessage​(java.time.Duration max)
        Receive one message of type M. Wait time is bounded by the max duration, with an AssertionError raised in case of timeout.

      • receiveSeveralMessages

        public abstract java.util.List<M> receiveSeveralMessages​(int n)
        Same as receiveSeveralMessages(n, remaining) but using the default timeout as deadline.

      • receiveSeveralMessages

        public abstract java.util.List<M> receiveSeveralMessages​(int n,
                                                         java.time.Duration max)
        Receive n messages in a row before the given deadline.

        Note that the timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".

      • fishForMessage

        public abstract java.util.List<M> fishForMessage​(java.time.Duration max,
                                                 java.util.function.Function<M,​FishingOutcome> fisher)
        Java API: Allows for flexible matching of multiple messages within a timeout, the fisher function is fed each incoming message, and returns one of the following effects to decide on what happens next:

        * FishingOutcomes.continueAndCollect - continue with the next message given that the timeout has not been reached * FishingOutcomes.complete - successfully complete and return the message * FishingOutcomes.fail - fail the test with a custom message

        Additionally failures includes the list of messages consumed. If a message of type M but not of type T is received this will also fail the test, additionally if the fisher function throws a match error the error is decorated with some fishing details and the test is failed (making it convenient to use this method with a partial function).

        Parameters:
        max - Max total time without the fisher function returning CompleteFishing before failing. The timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".
        Returns:
        The messages accepted in the order they arrived

      • fishForMessage

        public abstract java.util.List<M> fishForMessage​(java.time.Duration max,
                                                 java.lang.String hint,
                                                 java.util.function.Function<M,​FishingOutcome> fisher)
        Same as the other fishForMessage but includes the provided hint in all error messages

      • expectTerminated

        public abstract <U> void expectTerminated​(ActorRef<U> actorRef,
                                          java.time.Duration max)
        Expect the given actor to be stopped or stop within the given timeout or throw an AssertionError.

        Note that the timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".

      • expectTerminated

        public abstract <U> void expectTerminated​(ActorRef<U> actorRef)
        Expect the given actor to be stopped or stop within the default timeout.

      • awaitAssert

        public abstract <A> A awaitAssert​(java.time.Duration max,
                                  java.time.Duration interval,
                                  Creator<A> creator)
        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.

        Note that the timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".

      • awaitAssert

        public abstract <A> A awaitAssert​(java.time.Duration max,
                                  Creator<A> creator)
        Evaluate the given assert every 100 milliseconds until it does not throw an exception and return the result.

        If the max timeout expires the last exception is thrown.

        Note that the timeout is scaled using the configuration entry "pekko.actor.testkit.typed.timefactor".

      • awaitAssert

        public abstract <A> A awaitAssert​(Creator<A> creator)
        Evaluate the given assert every 100 milliseconds until it does not throw an exception and return the result. A max time is taken it from the innermost enclosing within block.

      • stop

        public abstract void stop()
        Stops the TestProbe.getRef, which is useful when testing watch and termination.