Interface TestProbe<M>

  • All Superinterfaces:
    RecipientRef<M>

    public interface TestProbe<M>
    extends RecipientRef<M>
    Create instances through the factories in the TestProbe companion.

    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

    Not for user extension

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      TestProbe<M> asJava()
      INTERNAL API
      <A> A awaitAssert​(scala.Function0<A> a)
      Evaluate the given assert every 100 ms until it does not throw an exception and return the result.
      <A> A awaitAssert​(scala.Function0<A> a, scala.concurrent.duration.FiniteDuration max)
      Evaluate the given assert every 100 ms until it does not throw an exception and return the result.
      <A> A awaitAssert​(scala.Function0<A> a, scala.concurrent.duration.FiniteDuration max, scala.concurrent.duration.FiniteDuration interval)
      Evaluate the given assert every interval until it does not throw an exception and return the result.
      <T extends M>
      T
      expectMessage​(scala.concurrent.duration.FiniteDuration max, java.lang.String hint, T obj)
      Receive one message from the test actor and assert that it equals the given object.
      <T extends M>
      T
      expectMessage​(scala.concurrent.duration.FiniteDuration max, T obj)
      Receive one message from the test actor and assert that it equals the given object.
      <T extends M>
      T
      expectMessage​(T obj)
      Same as expectMessage(remainingOrDefault, obj), but using the default timeout as deadline.
      <T extends M>
      T
      expectMessageType​(scala.concurrent.duration.FiniteDuration max, scala.reflect.ClassTag<T> t)
      Expect a message of type T to arrive within max or fail.
      <T extends M>
      T
      expectMessageType​(scala.reflect.ClassTag<T> t)
      Same as expectMessageType[T](remainingOrDefault), but using the default timeout as deadline.
      void expectNoMessage()
      Assert that no message is received.
      void expectNoMessage​(scala.concurrent.duration.FiniteDuration max)
      Assert that no message is received for the specified time.
      <U> void expectTerminated​(ActorRef<U> actorRef)
      Expect the given actor to be stopped or stop within the default timeout.
      <U> void expectTerminated​(ActorRef<U> actorRef, scala.concurrent.duration.FiniteDuration max)
      Expect the given actor to be stopped or stop within the given timeout or throw an AssertionError.
      scala.collection.immutable.Seq<M> fishForMessage​(scala.concurrent.duration.FiniteDuration max, java.lang.String hint, scala.Function1<M,​FishingOutcome> fisher)
      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:
      scala.collection.immutable.Seq<M> fishForMessage​(scala.concurrent.duration.FiniteDuration max, scala.Function1<M,​FishingOutcome> fisher)
      Same as the other fishForMessage but with no hint
      scala.collection.immutable.Seq<M> fishForMessagePF​(scala.concurrent.duration.FiniteDuration max, java.lang.String hint, scala.PartialFunction<M,​FishingOutcome> fisher)
      Same as fishForMessage but accepting a partial function and failing for non-matches
      scala.collection.immutable.Seq<M> fishForMessagePF​(scala.concurrent.duration.FiniteDuration max, scala.PartialFunction<M,​FishingOutcome> fisher)
      Same as fishForMessage but with no hint, accepting a partial function and failing for non-matches
      M receiveMessage()
      Receive one message of type M within the default timeout as deadline.
      M receiveMessage​(scala.concurrent.duration.FiniteDuration max)
      Receive one message of type M.
      scala.collection.immutable.Seq<M> receiveMessages​(int n)
      Same as receiveMessages(n, remaining) but using the default timeout as deadline.
      scala.collection.immutable.Seq<M> receiveMessages​(int n, scala.concurrent.duration.FiniteDuration max)
      Receive n messages in a row before the given deadline.
      ActorRef<M> ref()
      ActorRef for this TestProbe
      scala.concurrent.duration.FiniteDuration remaining()
      Obtain time remaining for execution of the innermost enclosing within block or throw an AssertionError if no within block surrounds this call.
      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.
      scala.concurrent.duration.FiniteDuration remainingOrDefault()
      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.actor.testkit.typed.single-expect-default").
      TestKitSettings settings()  
      void stop()
      Stops the TestProbe.ref, which is useful when testing watch and termination.
      <T> T within​(scala.concurrent.duration.FiniteDuration min, scala.concurrent.duration.FiniteDuration max, scala.Function0<T> f)
      Execute code block while bounding its execution time between min and max.
      <T> T within​(scala.concurrent.duration.FiniteDuration max, scala.Function0<T> f)
      Same as calling within(0 seconds, max)(f).
    • Method Detail

      • ref

        ActorRef<M> ref()
        ActorRef for this TestProbe
      • remainingOrDefault

        scala.concurrent.duration.FiniteDuration remainingOrDefault()
        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.actor.testkit.typed.single-expect-default").
      • remaining

        scala.concurrent.duration.FiniteDuration remaining()
        Obtain time remaining for execution of the innermost enclosing within block or throw an AssertionError if no within block surrounds this call.
      • remainingOr

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

        <T> T within​(scala.concurrent.duration.FiniteDuration min,
                     scala.concurrent.duration.FiniteDuration max,
                     scala.Function0<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 "akka.actor.testkit.typed.timefactor", while the min Duration is not.

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

        <T> T within​(scala.concurrent.duration.FiniteDuration max,
                     scala.Function0<T> f)
        Same as calling within(0 seconds, max)(f).
      • expectMessage

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

        <T extends M> T expectMessage​(scala.concurrent.duration.FiniteDuration 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

        <T extends M> T expectMessage​(scala.concurrent.duration.FiniteDuration 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

        void expectNoMessage​(scala.concurrent.duration.FiniteDuration max)
        Assert that no message is received for the specified time. Supplied value is not dilated.
      • expectNoMessage

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

        <T extends M> T expectMessageType​(scala.reflect.ClassTag<T> t)
        Same as expectMessageType[T](remainingOrDefault), but using the default timeout as deadline.
      • expectMessageType

        <T extends M> T expectMessageType​(scala.concurrent.duration.FiniteDuration max,
                                          scala.reflect.ClassTag<T> t)
        Expect a message of type T to arrive within max or fail. max is dilated.
      • receiveMessage

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

        M receiveMessage​(scala.concurrent.duration.FiniteDuration max)
        Receive one message of type M. Wait time is bounded by the max duration, with an AssertionError raised in case of timeout.
      • receiveMessages

        scala.collection.immutable.Seq<M> receiveMessages​(int n)
        Same as receiveMessages(n, remaining) but using the default timeout as deadline.
      • receiveMessages

        scala.collection.immutable.Seq<M> receiveMessages​(int n,
                                                          scala.concurrent.duration.FiniteDuration max)
        Receive n messages in a row before the given deadline.

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

      • fishForMessage

        scala.collection.immutable.Seq<M> fishForMessage​(scala.concurrent.duration.FiniteDuration max,
                                                         java.lang.String hint,
                                                         scala.Function1<M,​FishingOutcome> fisher)
        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:

        * {@link FishingOutcomes.continue} - continue with the next message given that the timeout has not been reached * FishingOutcomes.continueAndIgnore - continue and do not save the message in the returned list * 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 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 "akka.actor.testkit.typed.timefactor".
        Returns:
        The messages accepted in the order they arrived
      • fishForMessagePF

        scala.collection.immutable.Seq<M> fishForMessagePF​(scala.concurrent.duration.FiniteDuration max,
                                                           java.lang.String hint,
                                                           scala.PartialFunction<M,​FishingOutcome> fisher)
        Same as fishForMessage but accepting a partial function and failing for non-matches
      • fishForMessage

        scala.collection.immutable.Seq<M> fishForMessage​(scala.concurrent.duration.FiniteDuration max,
                                                         scala.Function1<M,​FishingOutcome> fisher)
        Same as the other fishForMessage but with no hint
      • fishForMessagePF

        scala.collection.immutable.Seq<M> fishForMessagePF​(scala.concurrent.duration.FiniteDuration max,
                                                           scala.PartialFunction<M,​FishingOutcome> fisher)
        Same as fishForMessage but with no hint, accepting a partial function and failing for non-matches
      • expectTerminated

        <U> void expectTerminated​(ActorRef<U> actorRef,
                                  scala.concurrent.duration.FiniteDuration max)
        Expect the given actor to be stopped or stop within the given timeout or throw an AssertionError.
      • expectTerminated

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

        <A> A awaitAssert​(scala.Function0<A> a,
                          scala.concurrent.duration.FiniteDuration max,
                          scala.concurrent.duration.FiniteDuration interval)
        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 "akka.actor.testkit.typed.timefactor".

      • awaitAssert

        <A> A awaitAssert​(scala.Function0<A> a,
                          scala.concurrent.duration.FiniteDuration max)
        Evaluate the given assert every 100 ms until it does not throw an exception and return the result.

        If the max timeout expires the last exception is thrown.

      • awaitAssert

        <A> A awaitAssert​(scala.Function0<A> a)
        Evaluate the given assert every 100 ms until it does not throw an exception and return the result.

        If the default timeout expires the last exception is thrown.

      • stop

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