class TestKit extends TestKitBase

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.

class Test extends TestKit(ActorSystem()) {
  try {

    val test = system.actorOf(Props[SomeActor])

      within (1.second) {
        test ! SomeWork
        expectMsg(Result1) // bounded to 1 second
        expectMsg(Result2) // bounded to the remainder of the 1 second
      }

    } finally {
      system.terminate()
    }

  } finally {
    system.terminate()
  }
}

Beware of two points:

  • the ActorSystem passed into the constructor needs to be shutdown, otherwise thread pools and memory will be leaked
  • this class is not thread-safe (only one actor with one queue, one stack of within blocks); it is expected that the code is executed from a constructor as shown above, which makes this a non-issue, otherwise 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 their Duration.dilated method, which uses the TestKitExtension.Settings.TestTimeFactor settable via akka.conf entry "akka.test.timefactor".

Annotations
@nowarn()
Source
TestKit.scala
Since

1.1

Linear Supertypes
TestKitBase, AnyRef, Any
Known Subclasses
MultiNodeSpec, TestProbe
Type Hierarchy
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. TestKit
  2. TestKitBase
  3. AnyRef
  4. Any
Implicitly
  1. by any2stringadd
  2. by StringFormat
  3. by Ensuring
  4. by ArrowAssoc
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Instance Constructors

  1. new TestKit(_system: ActorSystem)

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. def +(other: String): String
    Implicit
    This member is added by an implicit conversion from TestKit toany2stringadd[TestKit] performed by method any2stringadd in scala.Predef.
    Definition Classes
    any2stringadd
  4. def ->[B](y: B): (TestKit, B)
    Implicit
    This member is added by an implicit conversion from TestKit toArrowAssoc[TestKit] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc
    Annotations
    @inline()
  5. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  6. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  7. def assertForDuration[A](a: => A, max: FiniteDuration, interval: Duration = 100.millis): A

    Evaluate the given assert every interval until exception is thrown or max timeout is expired.

    Evaluate the given assert every interval until exception is thrown or max timeout is expired.

    Returns the result of last evaluation of the assertion.

    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 "akka.test.timefactor".

    Definition Classes
    TestKitBase
  8. def awaitAssert[A](a: => A, max: Duration = Duration.Undefined, interval: Duration = 100.millis): A

    Evaluate the given assert every interval until it does not throw an exception and return the result.

    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 "akka.test.timefactor".

    Definition Classes
    TestKitBase
  9. def awaitCond(p: => Boolean, max: Duration = Duration.Undefined, interval: Duration = 100.millis, message: String = ""): Unit

    Await until the given condition evaluates to true or the timeout expires, whichever comes first.

    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 "akka.test.timefactor".

    Definition Classes
    TestKitBase
  10. def childActorOf(props: Props): ActorRef

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

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

    props

    Props to create the child actor

    Definition Classes
    TestKitBase
  11. def childActorOf(props: Props, name: String): ActorRef

    Spawns an actor as a child of this test actor with a stopping supervisor strategy, and returns the child's ActorRef.

    Spawns an actor as a child of this test actor with a stopping supervisor strategy, and returns the child's ActorRef.

    props

    Props to create the child actor

    name

    Actor name for the child actor

    Definition Classes
    TestKitBase
  12. def childActorOf(props: Props, supervisorStrategy: SupervisorStrategy): ActorRef

    Spawns an actor as a child of this test actor with an auto-generated name, and returns the child's ActorRef.

    Spawns an actor as a child of this test actor with an auto-generated name, and returns the child's ActorRef.

    props

    Props to create the child actor

    supervisorStrategy

    Strategy should decide what to do with failures in the actor.

    Definition Classes
    TestKitBase
  13. def childActorOf(props: Props, name: String, supervisorStrategy: SupervisorStrategy): ActorRef

    Spawns an actor as a child of this test actor, and returns the child's ActorRef.

    Spawns an actor as a child of this test actor, and returns the child's ActorRef.

    props

    Props to create the child actor

    name

    Actor name for the child actor

    supervisorStrategy

    Strategy should decide what to do with failures in the actor.

    Definition Classes
    TestKitBase
  14. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @HotSpotIntrinsicCandidate() @native()
  15. def ensuring(cond: (TestKit) => Boolean, msg: => Any): TestKit
    Implicit
    This member is added by an implicit conversion from TestKit toEnsuring[TestKit] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  16. def ensuring(cond: (TestKit) => Boolean): TestKit
    Implicit
    This member is added by an implicit conversion from TestKit toEnsuring[TestKit] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  17. def ensuring(cond: Boolean, msg: => Any): TestKit
    Implicit
    This member is added by an implicit conversion from TestKit toEnsuring[TestKit] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  18. def ensuring(cond: Boolean): TestKit
    Implicit
    This member is added by an implicit conversion from TestKit toEnsuring[TestKit] performed by method Ensuring in scala.Predef.
    Definition Classes
    Ensuring
  19. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  20. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  21. def expectMsg[T](max: FiniteDuration, hint: String, obj: T): T

    Receive one message from the test actor and assert that it equals the given object.

    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

    Definition Classes
    TestKitBase
  22. def expectMsg[T](max: FiniteDuration, obj: T): T

    Receive one message from the test actor and assert that it equals the given object.

    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

    Definition Classes
    TestKitBase
  23. def expectMsg[T](obj: T): T

    Same as expectMsg(remainingOrDefault, obj), but correctly treating the timeFactor.

    Same as expectMsg(remainingOrDefault, obj), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  24. def expectMsgAllClassOf[T](max: FiniteDuration, obj: Class[_ <: T]*): Seq[T]

    Receive a number of messages from the test actor matching the given number of classes and assert that for each given class one is received which is of that class (equality, not conformance).

    Receive a number of messages from the test actor matching the given number of classes and assert that for each given class one is received which is of that class (equality, not conformance). 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.

    Definition Classes
    TestKitBase
  25. def expectMsgAllClassOf[T](obj: Class[_ <: T]*): Seq[T]

    Same as expectMsgAllClassOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Same as expectMsgAllClassOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  26. def expectMsgAllConformingOf[T](max: FiniteDuration, obj: Class[_ <: T]*): Seq[T]

    Receive a number of messages from the test actor matching the given number of classes and assert that for each given class one is received which conforms to that class (and vice versa).

    Receive a number of messages from the test actor matching the given number of classes and assert that for each given class one is received which conforms to that class (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.

    Beware that one object may satisfy all given class constraints, which may be counter-intuitive.

    Definition Classes
    TestKitBase
  27. def expectMsgAllConformingOf[T](obj: Class[_ <: T]*): Seq[T]

    Same as expectMsgAllConformingOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Same as expectMsgAllConformingOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  28. def expectMsgAllOf[T](max: FiniteDuration, obj: T*): Seq[T]

    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.

    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.

      dispatcher ! SomeWork1()
  dispatcher ! SomeWork2()
  expectMsgAllOf(1 second, Result1(), Result2())

    Definition Classes
    TestKitBase
  29. def expectMsgAllOf[T](obj: T*): Seq[T]

    Same as expectMsgAllOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Same as expectMsgAllOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  30. def expectMsgAnyClassOf[C](max: FiniteDuration, obj: Class[_ <: C]*): C

    Receive one message from the test actor and assert that it conforms to one of the given 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

    Definition Classes
    TestKitBase
  31. def expectMsgAnyClassOf[C](obj: Class[_ <: C]*): C

    Same as expectMsgAnyClassOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Same as expectMsgAnyClassOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  32. def expectMsgAnyOf[T](max: FiniteDuration, obj: T*): T

    Receive one message from the test actor and assert that it equals one of the given objects.

    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

    Definition Classes
    TestKitBase
  33. def expectMsgAnyOf[T](obj: T*): T

    Same as expectMsgAnyOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Same as expectMsgAnyOf(remainingOrDefault, obj...), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  34. def expectMsgClass[C](max: FiniteDuration, c: Class[C]): C

    Receive one message from the test actor and assert that it conforms to the given class.

    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

    Definition Classes
    TestKitBase
  35. def expectMsgClass[C](c: Class[C]): C

    Same as expectMsgClass(remainingOrDefault, c), but correctly treating the timeFactor.

    Same as expectMsgClass(remainingOrDefault, c), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  36. def expectMsgPF[T](max: Duration = Duration.Undefined, hint: String = "")(f: PartialFunction[Any, T]): T

    Receive one message from the test actor and assert that the given partial function accepts it.

    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.

    returns

    the received object as transformed by the partial function

    Definition Classes
    TestKitBase
  37. def expectMsgType[T](max: FiniteDuration)(implicit t: ClassTag[T]): T

    Receive one message from the test actor and assert that it conforms to the given type (after erasure).

    Receive one message from the test actor and assert that it conforms to the given type (after erasure). Wait time is bounded by the given duration, with an AssertionFailure being thrown in case of timeout.

    returns

    the received object

    Definition Classes
    TestKitBase
  38. def expectMsgType[T](implicit t: ClassTag[T]): T

    Same as expectMsgType[T](remainingOrDefault), but correctly treating the timeFactor.

    Same as expectMsgType[T](remainingOrDefault), but correctly treating the timeFactor.

    Definition Classes
    TestKitBase
  39. def expectNoMessage(): Unit

    Assert that no message is received.

    Assert that no message is received. Waits for the default period configured as akka.test.expect-no-message-default. That timeout is scaled using the configuration entry "akka.test.timefactor".

    Definition Classes
    TestKitBase
  40. def expectNoMessage(max: FiniteDuration): Unit

    Assert that no message is received for the specified time.

    Assert that no message is received for the specified time. Supplied value is not dilated.

    Definition Classes
    TestKitBase
  41. def expectTerminated(target: ActorRef, max: Duration = Duration.Undefined): Terminated

    Receive one message from the test actor and assert that it is the Terminated message of the given ActorRef.

    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.

    target

    the actor ref expected to be Terminated

    max

    wait no more than max time, otherwise throw AssertionFailure

    returns

    the received Terminated message

    Definition Classes
    TestKitBase
  42. def fishForMessage(max: Duration = Duration.Undefined, hint: String = "")(f: PartialFunction[Any, Boolean]): Any

    Hybrid of expectMsgPF and receiveWhile: receive messages while the partial function matches and returns false.

    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

    Definition Classes
    TestKitBase
  43. def fishForSpecificMessage[T](max: Duration = Duration.Undefined, hint: String = "")(f: PartialFunction[Any, T]): T

    Waits for specific message that partial function matches while ignoring all other messages coming in the meantime.

    Waits for specific message that partial function matches while ignoring all other messages coming in the meantime. Use it to ignore any number of messages while waiting for a specific one.

    returns

    result of applying partial function to the last received message, i.e. the first one for which the partial function is defined

    Definition Classes
    TestKitBase
  44. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @HotSpotIntrinsicCandidate() @native()
  45. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @HotSpotIntrinsicCandidate() @native()
  46. def ignoreMsg(f: PartialFunction[Any, Boolean]): Unit

    Ignore all messages in the test actor for which the given partial function returns true.

    Ignore all messages in the test actor for which the given partial function returns true.

    Definition Classes
    TestKitBase
  47. def ignoreNoMsg(): Unit

    Stop ignoring messages in the test actor.

    Stop ignoring messages in the test actor.

    Definition Classes
    TestKitBase
  48. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  49. def lastSender: ActorRef
    Definition Classes
    TestKitBase
  50. def msgAvailable: Boolean

    Query queue status.

    Query queue status.

    Definition Classes
    TestKitBase
  51. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  52. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @HotSpotIntrinsicCandidate() @native()
  53. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @HotSpotIntrinsicCandidate() @native()
  54. def now: FiniteDuration

    Obtain current time (System.nanoTime) as Duration.

    Obtain current time (System.nanoTime) as Duration.

    Definition Classes
    TestKitBase
  55. def receiveN(n: Int, max: FiniteDuration): Seq[AnyRef]

    Receive N messages in a row before the given deadline.

    Receive N messages in a row before the given deadline.

    Definition Classes
    TestKitBase
  56. def receiveN(n: Int): Seq[AnyRef]

    Same as receiveN(n, remaining) but correctly taking into account Duration.timeFactor.

    Same as receiveN(n, remaining) but correctly taking into account Duration.timeFactor.

    Definition Classes
    TestKitBase
  57. def receiveOne(max: Duration): AnyRef

    Receive one message from the internal queue of the TestActor.

    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!

    Definition Classes
    TestKitBase
  58. def receiveWhile[T](max: Duration = Duration.Undefined, idle: Duration = Duration.Inf, messages: Int = Int.MaxValue)(f: PartialFunction[AnyRef, T]): Seq[T]

    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.

    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:

    test ! ScheduleTicks(100 millis)
val series = receiveWhile(750 millis) {
    case Tick(count) => count
}
assert(series == (1 to 7).toList)
    Definition Classes
    TestKitBase
  59. def remaining: FiniteDuration

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

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

    Definition Classes
    TestKitBase
  60. def remainingOr(duration: FiniteDuration): FiniteDuration

    Obtain time remaining for execution of the innermost enclosing within block or missing that it returns the given duration.

    Obtain time remaining for execution of the innermost enclosing within block or missing that it returns the given duration.

    Definition Classes
    TestKitBase
  61. def remainingOrDefault: FiniteDuration

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

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

    Definition Classes
    TestKitBase
  62. def setAutoPilot(pilot: AutoPilot): Unit

    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.

    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.

    Definition Classes
    TestKitBase
  63. def shutdown(actorSystem: ActorSystem = system, duration: Duration = Duration.Undefined, verifySystemShutdown: Boolean = false): Unit

    Shut down an actor system and wait for termination.

    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.

    Definition Classes
    TestKitBase
  64. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  65. implicit val system: ActorSystem
    Definition Classes
    TestKit → TestKitBase
  66. lazy val testActor: ActorRef

    ActorRef of the test actor.

    ActorRef of the test actor. Access is provided to enable e.g. registration as message target.

    Definition Classes
    TestKitBase
  67. def testActorName: String

    Defines the testActor name.

    Defines the testActor name.

    Attributes
    protected
    Definition Classes
    TestKitBase
  68. def testKitSettings: TestKitSettings
    Definition Classes
    TestKitBase
  69. def toString(): String
    Definition Classes
    AnyRef → Any
  70. def unwatch(ref: ActorRef): ActorRef

    Have the testActor stop watching someone (i.e.

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

    Definition Classes
    TestKitBase
  71. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  72. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()
  73. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  74. def watch(ref: ActorRef): ActorRef

    Have the testActor watch someone (i.e.

    Have the testActor watch someone (i.e. context.watch(...)).

    Definition Classes
    TestKitBase
  75. def within[T](max: FiniteDuration)(f: => T): T

    Same as calling within(0 seconds, max)(f).

    Same as calling within(0 seconds, max)(f).

    Definition Classes
    TestKitBase
  76. def within[T](min: FiniteDuration, max: FiniteDuration)(f: => T): T

    Execute code block while bounding its execution time between min and max.

    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 "akka.test.timefactor", while the min Duration is not.

    val ret = within(50 millis) {
  test ! "ping"
  expectMsgClass(classOf[String])
}
    Definition Classes
    TestKitBase

Deprecated Value Members

  1. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable]) @Deprecated
    Deprecated

    (Since version 9)

  2. def formatted(fmtstr: String): String
    Implicit
    This member is added by an implicit conversion from TestKit toStringFormat[TestKit] performed by method StringFormat in scala.Predef.
    Definition Classes
    StringFormat
    Annotations
    @deprecated @inline()
    Deprecated

    (Since version 2.12.16) Use formatString.format(value) instead of value.formatted(formatString), or use the f"" string interpolator. In Java 15 and later, formatted resolves to the new method in String which has reversed parameters.

  3. def →[B](y: B): (TestKit, B)
    Implicit
    This member is added by an implicit conversion from TestKit toArrowAssoc[TestKit] performed by method ArrowAssoc in scala.Predef.
    Definition Classes
    ArrowAssoc
    Annotations
    @deprecated
    Deprecated

    (Since version 2.13.0) Use -> instead. If you still wish to display it as one character, consider using a font with programming ligatures such as Fira Code.

Inherited from TestKitBase

Inherited from AnyRef

Inherited from Any

Inherited by implicit conversion any2stringadd fromTestKit to any2stringadd[TestKit]

Inherited by implicit conversion StringFormat fromTestKit to StringFormat[TestKit]

Inherited by implicit conversion Ensuring fromTestKit to Ensuring[TestKit]

Inherited by implicit conversion ArrowAssoc fromTestKit to ArrowAssoc[TestKit]

Ungrouped