Packages

package testkit

Source
package.scala
Linear Supertypes
Content Hierarchy
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. testkit
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Package Members

  1. package javadsl

Type Members

  1. class CallingThreadDispatcher extends MessageDispatcher

    Dispatcher which runs invocations on the current thread only.

    Dispatcher which runs invocations on the current thread only. This dispatcher does not create any new threads, but it can be used from different threads concurrently for the same actor. The dispatch strategy is to run on the current thread unless the target actor is either suspendSwitch or already running on the current thread (if it is running on a different thread, then this thread will block until that other invocation is finished); if the invocation is not run, it is queued in a thread-local queue to be executed once the active invocation further up the call stack finishes. This leads to completely deterministic execution order if only one thread is used.

    Suspending and resuming are global actions for one actor, meaning they can affect different threads, which leads to complications. If messages are queued (thread-locally) during the suspendSwitch period, the only thread to run them upon resume is the thread actually calling the resume method. Hence, all thread-local queues which are not currently being drained (possible, since suspend-queue-resume might happen entirely during an invocation on a different thread) are scooped up into the current thread-local queue which is then executed. It is possible to suspend an actor from within its call stack.

  2. class CallingThreadDispatcherConfigurator extends MessageDispatcherConfigurator
  3. class CallingThreadMailbox extends Mailbox with DefaultSystemMessageQueue
  4. final case class CustomEventFilter(test: PartialFunction[LogEvent, Boolean])(occurrences: Int) extends EventFilter with Product with Serializable

    Custom event filter when the others do not fit the bill.

    Custom event filter when the others do not fit the bill.

    If the partial function is defined and returns true, filter the event.

  5. final case class DeadLettersFilter(messageClass: Class[_])(occurrences: Int) extends EventFilter with Product with Serializable

    Filter which matches DeadLetter events, if the wrapped message conforms to the given type.

  6. final case class DebugFilter(source: Option[String], message: Either[String, Regex], complete: Boolean)(occurrences: Int) extends EventFilter with Product with Serializable

    Filter which matches Debug events, if they satisfy the given criteria:

    Filter which matches Debug events, if they satisfy the given criteria:

    • source, if given, applies a filter on the event’s origin
    • message applies a filter on the event’s message (either with String.startsWith or Regex.findFirstIn().isDefined)

    If you want to match all Debug events, the most efficient is to use Left("").

  7. trait DefaultTimeout extends AnyRef
  8. final case class ErrorFilter(throwable: Class[_], source: Option[String], message: Either[String, Regex], complete: Boolean)(occurrences: Int) extends EventFilter with Product with Serializable

    Filter which matches Error events, if they satisfy the given criteria:

    Filter which matches Error events, if they satisfy the given criteria:

    • throwable applies an upper bound on the type of exception contained in the Error event
    • source, if given, applies a filter on the event’s origin
    • message applies a filter on the event’s message (either with String.startsWith or Regex.findFirstIn().isDefined); if the message itself does not match, the match is retried with the contained Exception’s message; if both are null, the filter always matches if at the same time the Exception’s stack trace is empty (this catches JVM-omitted “fast-throw” exceptions)

    If you want to match all Error events, the most efficient is to use Left("").

  9. abstract class EventFilter extends AnyRef

    Facilities for selectively filtering out expected events from logging so that you can keep your test run’s console output clean and do not miss real error messages.

    Facilities for selectively filtering out expected events from logging so that you can keep your test run’s console output clean and do not miss real error messages.

    See the companion object for convenient factory methods.

    If the occurrences is set to Int.MaxValue, no tracking is done.

  10. class ExplicitlyTriggeredScheduler extends Scheduler

    For testing: scheduler that does not look at the clock, but must be progressed manually by calling timePasses.

    For testing: scheduler that does not look at the clock, but must be progressed manually by calling timePasses.

    This allows for faster and less timing-sensitive specs, as jobs will be executed on the test thread instead of using the original {ExecutionContext}. This means recreating specific scenario's becomes easier, but these tests might fail to catch race conditions that only happen when tasks are scheduled in parallel in 'real time'.

  11. trait ImplicitSender extends AnyRef
  12. final case class InfoFilter(source: Option[String], message: Either[String, Regex], complete: Boolean)(occurrences: Int) extends EventFilter with Product with Serializable

    Filter which matches Info events, if they satisfy the given criteria:

    Filter which matches Info events, if they satisfy the given criteria:

    • source, if given, applies a filter on the event’s origin
    • message applies a filter on the event’s message (either with String.startsWith or Regex.findFirstIn().isDefined)

    If you want to match all Info events, the most efficient is to use Left("").

  13. trait JavaSerializable extends Serializable

    Marker trait for test messages that will use Java serialization via org.apache.pekko.testkit.TestJavaSerializer

  14. class TestActor extends Actor
  15. class TestActorRef[T <: Actor] extends LocalActorRef

    This special ActorRef is exclusively for use during unit testing in a single-threaded environment.

    This special ActorRef is exclusively for use during unit testing in a single-threaded environment. Therefore, it overrides the dispatcher to CallingThreadDispatcher and sets the receiveTimeout to None. Otherwise, it acts just like a normal ActorRef. You may retrieve a reference to the underlying actor to test internal logic.

    Annotations
    @nowarn()
  16. class TestBarrier extends AnyRef
  17. class TestBarrierTimeoutException extends RuntimeException
  18. implicit final class TestDuration extends AnyVal

    Scala API.

    Scala API. Scale timeouts (durations) during tests with the configured 'pekko.test.timefactor'. Implicit class providing dilated method.

    import scala.concurrent.duration._
    import org.apache.pekko.testkit._
    10.milliseconds.dilated

    Corresponding Java API is available in JavaTestKit.dilated()

  19. sealed trait TestEvent extends AnyRef

    Implementation helpers of the EventFilter facilities: send Mute to the TestEventListener to install a filter, and UnMute to uninstall it.

    Implementation helpers of the EventFilter facilities: send Mute to the TestEventListener to install a filter, and UnMute to uninstall it.

    You should always prefer the filter methods in the package object (see org.apache.pekko.testkit filterEvents and filterException) or on the EventFilter implementations.

  20. class TestEventListener extends DefaultLogger

    EventListener for running tests, which allows selectively filtering out expected messages.

    EventListener for running tests, which allows selectively filtering out expected messages. To use it, include something like this into pekko.test.conf and run your tests with system property "pekko.mode" set to "test":

    
    pekko {
      loggers = ["org.apache.pekko.testkit.TestEventListener"]
    }
    
    

    Annotations
    @ccompatUsedUntil213()
  21. final case class TestException(message: String) extends RuntimeException with NoStackTrace with Product with Serializable

    A predefined exception that can be used in tests.

    A predefined exception that can be used in tests. It doesn't include a stack trace.

  22. class TestFSMRef[S, D, T <: Actor] extends TestActorRef[T]

    This is a specialized form of the TestActorRef with support for querying and setting the state of a FSM.

    This is a specialized form of the TestActorRef with support for querying and setting the state of a FSM. Use a LoggingFSM with this class if you also need to inspect event traces.

    
    val fsm = TestFSMRef(new Actor with LoggingFSM[Int, Null] {
        override def logDepth = 12
        startWith(1, null)
        when(1) {
          case Event("hello", _) => goto(2)
        }
        when(2) {
          case Event("world", _) => goto(1)
        }
      })
    assert (fsm.stateName == 1)
    fsm ! "hallo"
    assert (fsm.stateName == 2)
    assert (fsm.underlyingActor.getLog == IndexedSeq(FSMLogEntry(1, null, "hallo")))
    
    

  23. class TestJavaSerializer extends BaseSerializer

    This Serializer uses standard Java Serialization and is useful for tests where ad-hoc messages are created and sent between actor systems.

    This Serializer uses standard Java Serialization and is useful for tests where ad-hoc messages are created and sent between actor systems. It needs to be explicitly enabled in the config (or through ActorSystemSetup) like so:

    pekko.actor.serialization-bindings { "my.test.AdHocMessage" = java-test }

  24. class TestKit extends TestKitBase

    Test kit for testing actors.

    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 pekko.conf entry "pekko.test.timefactor".

    Annotations
    @nowarn()
  25. trait TestKitBase extends AnyRef

    Implementation trait behind the pekko.testkit.TestKit class: you may use this if inheriting from a concrete class is not possible.

    Implementation trait behind the pekko.testkit.TestKit class: you may use this if inheriting from a concrete class is not possible.

    This trait requires the concrete class mixing it in to provide an pekko.actor.ActorSystem which is available before this traits’s constructor is run. The recommended way is this:

    class MyTest extends TestKitBase {
      implicit lazy val system = ActorSystem() // may add arguments here
      ...
    }
  26. class TestKitSettings extends Extension
  27. class TestLatch extends Awaitable[Unit]
  28. class TestProbe extends TestKit

    TestKit-based probe which allows sending, reception and reply.

  29. final case class WarningFilter(source: Option[String], message: Either[String, Regex], complete: Boolean)(occurrences: Int) extends EventFilter with Product with Serializable

    Filter which matches Warning events, if they satisfy the given criteria:

    Filter which matches Warning events, if they satisfy the given criteria:

    • source, if given, applies a filter on the event’s origin
    • message applies a filter on the event’s message (either with String.startsWith or Regex.findFirstIn().isDefined)

    If you want to match all Warning events, the most efficient is to use Left("").

Value Members

  1. def filterEvents[T](eventFilters: EventFilter*)(block: => T)(implicit system: ActorSystem): T
  2. def filterEvents[T](eventFilters: Iterable[EventFilter])(block: => T)(implicit system: ActorSystem): T
    Annotations
    @ccompatUsedUntil213()
  3. def filterException[T <: Throwable](block: => Unit)(implicit system: ActorSystem, t: ClassTag[T]): Unit
  4. object CallingThreadDispatcher
  5. object DeadLettersFilter extends Serializable
  6. object EventFilter

    Facilities for selectively filtering out expected events from logging so that you can keep your test run’s console output clean and do not miss real error messages.

    Facilities for selectively filtering out expected events from logging so that you can keep your test run’s console output clean and do not miss real error messages.

    Also have a look at the org.apache.pekko.testkit package object’s filterEvents and filterException methods.

    The source filters do accept Class[_] arguments, matching any object which is an instance of the given class, e.g.

    EventFilter.info(source = classOf[MyActor]) // will match Info events from any MyActor instance

    The message object will be converted to a string before matching ("null" if it is null).

  7. object SocketUtil

    Utilities to get free socket address.

  8. object TestActor
  9. object TestActorRef extends Serializable
  10. object TestActors

    A collection of common actor patterns used in tests.

  11. object TestBarrier

    A cyclic barrier wrapper for use in testing.

    A cyclic barrier wrapper for use in testing. It always uses a timeout when waiting and timeouts are specified as durations. Timeouts will always throw an exception. The default timeout is 5 seconds. Timeouts are multiplied by the testing time factor for Jenkins builds.

  12. object TestEvent

    Implementation helpers of the EventFilter facilities: send Mute to the TestEventFilter to install a filter, and UnMute to uninstall it.

    Implementation helpers of the EventFilter facilities: send Mute to the TestEventFilter to install a filter, and UnMute to uninstall it.

    You should always prefer the filter methods in the package object (see org.apache.pekko.testkit filterEvents and filterException) or on the EventFilter implementations.

  13. object TestFSMRef extends Serializable
  14. object TestKit
  15. object TestKitExtension extends ExtensionId[TestKitSettings]
  16. object TestLatch

    A count down latch wrapper for use in testing.

    A count down latch wrapper for use in testing. It always uses a timeout when waiting and timeouts are specified as durations. There's a default timeout of 5 seconds and the default count is 1. Timeouts will always throw an exception (no need to wrap in assert in tests). Timeouts are multiplied by the testing time factor for Jenkins builds.

  17. object TestProbe

Inherited from AnyRef

Inherited from Any

Ungrouped