Class ActorTestKit


  • public final class ActorTestKit
    extends java.lang.Object
    Java API: Test kit for asynchronous testing of typed actors. Provides a typed actor system started on creation, that can be used for multiple test cases and is shut down when shutdown is called.

    The actor system has a custom guardian that allows for spawning arbitrary actors using the spawn methods.

    Designed to work with any test framework, but framework glue code that calls shutdownTestKit after all tests has run needs to be provided by the user or with TestKitJunitResource.

    Use TestKit.create factories to construct manually or TestKitJunitResource to use together with JUnit tests

    For synchronous testing of a Behavior see BehaviorTestKit

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static ActorTestKit create()
      Create a testkit named from the class that is calling this method.
      static ActorTestKit create​(java.lang.String name)
      Create a named testkit.
      static ActorTestKit create​(java.lang.String name, com.typesafe.config.Config customConfig)
      Create a named testkit, and use a custom config for the actor system.
      static ActorTestKit create​(java.lang.String name, com.typesafe.config.Config customConfig, TestKitSettings settings)
      Create a named testkit, and use a custom config for the actor system, and a custom TestKitSettings
      <M> TestProbe<M> createTestProbe()
      Shortcut for creating a new test probe for the testkit actor system
      <M> TestProbe<M> createTestProbe​(java.lang.Class<M> clazz)
      Shortcut for creating a new test probe for the testkit actor system
      <M> TestProbe<M> createTestProbe​(java.lang.String name)
      Shortcut for creating a new named test probe for the testkit actor system
      <M> TestProbe<M> createTestProbe​(java.lang.String name, java.lang.Class<M> clazz)
      Shortcut for creating a new named test probe for the testkit actor system
      Scheduler scheduler()
      The scheduler of the testkit actor system
      static void shutdown​(ActorSystem<?> system)
      Shutdown the given ActorSystem and block until it shuts down, if more time than system-shutdown-default passes an exception is thrown (can be configured with throw-on-shutdown-timeout).
      static void shutdown​(ActorSystem<?> system, java.time.Duration duration)
      Shutdown the given ActorSystem and block until it shuts down, if more time than system-shutdown-default passes an exception is thrown (can be configured with throw-on-shutdown-timeout).
      static void shutdown​(ActorSystem<?> system, java.time.Duration duration, boolean throwIfShutdownTimesOut)
      Shutdown the given actor system and wait up to duration for shutdown to complete.
      void shutdownTestKit()
      Terminate the actor system and the testkit
      <T> ActorRef<T> spawn​(Behavior<T> behavior)
      Spawn a new auto-named actor under the testkit user guardian and return the ActorRef for the spawned actor
      <T> ActorRef<T> spawn​(Behavior<T> behavior, Props props)
      Spawn a new auto-named actor under the testkit user guardian with the given props and return the ActorRef for the spawned actor
      <T> ActorRef<T> spawn​(Behavior<T> behavior, java.lang.String name)
      Spawn a new named actor under the testkit user guardian and return the ActorRef for the spawned actor, note that spawning actors with the same name in multiple test cases will cause failures.
      <T> ActorRef<T> spawn​(Behavior<T> behavior, java.lang.String name, Props props)
      Spawn a new named actor under the testkit user guardian with the given props and return the ActorRef for the spawned actor, note that spawning actors with the same name in multiple test cases will cause failures.
      <T> void stop​(ActorRef<T> ref)
      Stop the actor under test and wait until it terminates.
      <T> void stop​(ActorRef<T> ref, java.time.Duration max)
      Stop the actor under test and wait max until it terminates.
      ActorSystem<java.lang.Void> system()
      The actor system running for this testkit.
      TestKitSettings testKitSettings()  
      Timeout timeout()
      The default timeout as specified with the config/TestKitSettings
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ActorTestKit

        public ActorTestKit​(ActorTestKit delegate)
    • Method Detail

      • create

        public static ActorTestKit create()
        Create a testkit named from the class that is calling this method.

        It will create an ActorSystem with this name, e.g. threads will include the name. When the test has completed you should terminate the ActorSystem and the testkit with shutdownTestKit().

        Returns:
        (undocumented)
      • create

        public static ActorTestKit create​(java.lang.String name)
        Create a named testkit.

        It will create an ActorSystem with this name, e.g. threads will include the name. When the test has completed you should terminate the ActorSystem and the testkit with shutdownTestKit().

        Parameters:
        name - (undocumented)
        Returns:
        (undocumented)
      • create

        public static ActorTestKit create​(java.lang.String name,
                                          com.typesafe.config.Config customConfig)
        Create a named testkit, and use a custom config for the actor system.

        It will create an ActorSystem with this name, e.g. threads will include the name. When the test has completed you should terminate the ActorSystem and the testkit with shutdownTestKit().

        Parameters:
        name - (undocumented)
        customConfig - (undocumented)
        Returns:
        (undocumented)
      • create

        public static ActorTestKit create​(java.lang.String name,
                                          com.typesafe.config.Config customConfig,
                                          TestKitSettings settings)
        Create a named testkit, and use a custom config for the actor system, and a custom TestKitSettings

        It will create an ActorSystem with this name, e.g. threads will include the name. When the test has completed you should terminate the ActorSystem and the testkit with shutdownTestKit().

        Parameters:
        name - (undocumented)
        customConfig - (undocumented)
        settings - (undocumented)
        Returns:
        (undocumented)
      • shutdown

        public static void shutdown​(ActorSystem<?> system,
                                    java.time.Duration duration,
                                    boolean throwIfShutdownTimesOut)
        Shutdown the given actor system and wait up to duration for shutdown to complete.
        Parameters:
        throwIfShutdownTimesOut - Fail the test if the system fails to shut down, if false an error is printed to stdout when the system did not shutdown but no exception is thrown.
        system - (undocumented)
        duration - (undocumented)
      • shutdown

        public static void shutdown​(ActorSystem<?> system,
                                    java.time.Duration duration)
        Shutdown the given ActorSystem and block until it shuts down, if more time than system-shutdown-default passes an exception is thrown (can be configured with throw-on-shutdown-timeout).
        Parameters:
        system - (undocumented)
        duration - (undocumented)
      • shutdown

        public static void shutdown​(ActorSystem<?> system)
        Shutdown the given ActorSystem and block until it shuts down, if more time than system-shutdown-default passes an exception is thrown (can be configured with throw-on-shutdown-timeout).
        Parameters:
        system - (undocumented)
      • timeout

        public Timeout timeout()
        The default timeout as specified with the config/TestKitSettings
        Returns:
        (undocumented)
      • system

        public ActorSystem<java.lang.Void> system()
        The actor system running for this testkit. Interaction with the user guardian is done through methods on the testkit which is why it is typed to Void.
        Returns:
        (undocumented)
      • scheduler

        public Scheduler scheduler()
        The scheduler of the testkit actor system
        Returns:
        (undocumented)
      • spawn

        public <T> ActorRef<T> spawn​(Behavior<T> behavior)
        Spawn a new auto-named actor under the testkit user guardian and return the ActorRef for the spawned actor
        Parameters:
        behavior - (undocumented)
        Returns:
        (undocumented)
      • spawn

        public <T> ActorRef<T> spawn​(Behavior<T> behavior,
                                     java.lang.String name)
        Spawn a new named actor under the testkit user guardian and return the ActorRef for the spawned actor, note that spawning actors with the same name in multiple test cases will cause failures.
        Parameters:
        behavior - (undocumented)
        name - (undocumented)
        Returns:
        (undocumented)
      • spawn

        public <T> ActorRef<T> spawn​(Behavior<T> behavior,
                                     Props props)
        Spawn a new auto-named actor under the testkit user guardian with the given props and return the ActorRef for the spawned actor
        Parameters:
        behavior - (undocumented)
        props - (undocumented)
        Returns:
        (undocumented)
      • spawn

        public <T> ActorRef<T> spawn​(Behavior<T> behavior,
                                     java.lang.String name,
                                     Props props)
        Spawn a new named actor under the testkit user guardian with the given props and return the ActorRef for the spawned actor, note that spawning actors with the same name in multiple test cases will cause failures.
        Parameters:
        behavior - (undocumented)
        name - (undocumented)
        props - (undocumented)
        Returns:
        (undocumented)
      • stop

        public <T> void stop​(ActorRef<T> ref)
        Stop the actor under test and wait until it terminates. It can only be used for actors that were spawned by this ActorTestKit. Other actors will not be stopped by this method.
        Parameters:
        ref - (undocumented)
      • stop

        public <T> void stop​(ActorRef<T> ref,
                             java.time.Duration max)
        Stop the actor under test and wait max until it terminates. It can only be used for actors that were spawned by this ActorTestKit. Other actors will not be stopped by this method.
        Parameters:
        ref - (undocumented)
        max - (undocumented)
      • createTestProbe

        public <M> TestProbe<M> createTestProbe()
        Shortcut for creating a new test probe for the testkit actor system
        Returns:
        (undocumented)
      • createTestProbe

        public <M> TestProbe<M> createTestProbe​(java.lang.Class<M> clazz)
        Shortcut for creating a new test probe for the testkit actor system
        Parameters:
        clazz - (undocumented)
        Returns:
        (undocumented)
      • createTestProbe

        public <M> TestProbe<M> createTestProbe​(java.lang.String name)
        Shortcut for creating a new named test probe for the testkit actor system
        Parameters:
        name - (undocumented)
        Returns:
        (undocumented)
      • createTestProbe

        public <M> TestProbe<M> createTestProbe​(java.lang.String name,
                                                java.lang.Class<M> clazz)
        Shortcut for creating a new named test probe for the testkit actor system
        Parameters:
        name - (undocumented)
        clazz - (undocumented)
        Returns:
        (undocumented)
      • shutdownTestKit

        public void shutdownTestKit()
        Terminate the actor system and the testkit