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

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

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.apache.pekko.actor.typed.RecipientRef

    RecipientRef.RecipientRefOps<T>, RecipientRef.RecipientRefOps$

  • Method Summary

    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, 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, 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, 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 "pekko.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).

    Methods inherited from interface org.apache.pekko.actor.typed.RecipientRef

    tell

  • Method Details

    • settings

      TestKitSettings settings()

    • 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 "pekko.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 "pekko.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, 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 pekko.actor.testkit.typed.expect-no-message-default. That timeout is scaled using the configuration entry "pekko.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 "pekko.actor.testkit.typed.timefactor".

    • fishForMessage

      scala.collection.immutable.Seq<M> fishForMessage(scala.concurrent.duration.FiniteDuration max, 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 "pekko.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, 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 "pekko.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.

    • asJava

      TestProbe<M> asJava()
      INTERNAL API