pekko/akka-docs/dev/multi-jvm-testing.rst

Multi-JVM Testing
=================

Included in the example is an sbt trait for multi-JVM testing which will fork
JVMs for multi-node testing. There is support for running applications (objects
with main methods) and running ScalaTest tests.

Using the multi-JVM testing is straight-forward. First, mix the ``MultiJvmTests``
trait into your sbt project::

    class SomeProject(info: ProjectInfo) extends DefaultProject(info) with MultiJvmTests

You can specify JVM options for the forked JVMs::

    class SomeProject(info: ProjectInfo) extends DefaultProject(info) with MultiJvmTests {
      override def multiJvmOptions = Seq("-Xmx256M")
    }

There are two sbt commands: ``multi-jvm-run`` for running applications and
``multi-jvm-test`` for running ScalaTest tests.

The ``MultiJvmTests`` trait resides in the ``project/build`` directory.

Creating application tests
~~~~~~~~~~~~~~~~~~~~~~~~~~

The tests are discovered through a naming convention. A test is named with the
following pattern:

.. code-block:: none

    {TestName}MultiJvm{NodeName}

That is, each test has ``MultiJvm`` in the middle of its name. The part before
it groups together tests/applications under a single ``TestName`` that will run
together. The part after, the ``NodeName``, is a distinguishing name for each
forked JVM.

So to create a 3-node test called ``Test``, you can create three applications
like the following::

    package example

    object SampleMultiJvmNode1 {
      def main(args: Array[String]) {
        println("Hello from node 1")
      }
    }

    object SampleMultiJvmNode2 {
      def main(args: Array[String]) {
        println("Hello from node 2")
      }
    }

    object SampleMultiJvmNode3 {
      def main(args: Array[String]) {
        println("Hello from node 3")
      }
    }

When you call ``multi-jvm-run Test`` at the sbt prompt, three JVMs will be
spawned, one for each node. It will look like this:

.. code-block:: shell

    > multi-jvm-run Test
    ...
    [info] == multi-jvm-run ==
    [info] == multi-jvm / Test ==
    [info] Starting JVM-Node1 for example.SampleMultiJvmNode1
    [info] Starting JVM-Node2 for example.SampleMultiJvmNode2
    [info] Starting JVM-Node3 for example.SampleMultiJvmNode3
    [JVM-Node1] Hello from node 1
    [JVM-Node2] Hello from node 2
    [JVM-Node3] Hello from node 3
    [info] == multi-jvm / Test ==
    [info] == multi-jvm-run ==
    [success] Successful.


Naming
~~~~~~

You can change what the ``MultiJvm`` identifier is. For example, to change it to
``ClusterTest`` override the ``multiJvmTestName`` method::

    class SomeProject(info: ProjectInfo) extends DefaultProject(info) with MultiJvmTests {
      override def multiJvmTestName = "ClusterSpec"
    }

Your tests should now be named ``{TestName}ClusterTest{NodeName}``.

Configuration of the JVM instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Setting JVM options
-------------------

You can define specific JVM options for each of the spawned JVMs. You do that by creating
a file named after the node in the test with suffix ``.opts`` and put them in the same
directory as the test.

For example, to feed the JVM options ``-Dakka.cluster.nodename=node1`` and
``-Dakka.cluster.port=9991`` to the ``SampleMultiJvmNode1`` let's create three ``*.opts`` files
and add the options to them.

``SampleMultiJvmNode1.opts``::

    -Dakka.cluster.nodename=node1 -Dakka.cluster.port=9991

``SampleMultiJvmNode2.opts``::

    -Dakka.cluster.nodename=node2 -Dakka.cluster.port=9992

``SampleMultiJvmNode3.opts``::

    -Dakka.cluster.nodename=node3 -Dakka.cluster.port=9993

Overriding akka.conf options
----------------------------

You can also override the options in the ``akka.conf`` file with different options for each
spawned JVM. You do that by creating a file named after the node in the test with suffix
``.conf`` and put them in the same  directory as the test .

For example, to override the configuration option ``akka.cluster.name`` let's create three
``*.conf`` files and add the option to them.

``SampleMultiJvmNode1.conf``::

    akka.cluster.name = "test-cluster"

``SampleMultiJvmNode2.conf``::

    akka.cluster.name = "test-cluster"

``SampleMultiJvmNode3.conf``::

    akka.cluster.name = "test-cluster"

ScalaTest
~~~~~~~~~

There is also support for creating ScalaTest tests rather than applications. To
do this use the same naming convention as above, but create ScalaTest suites
rather than objects with main methods. You need to have ScalaTest on the
classpath. Here is a similar example to the one above but using ScalaTest::

    package example

    import org.scalatest.WordSpec
    import org.scalatest.matchers.MustMatchers

    class SpecMultiJvmNode1 extends WordSpec with MustMatchers {
      "A node" should {
        "be able to say hello" in {
          val message = "Hello from node 1"
          message must be("Hello from node 1")
        }
      }
    }

    class SpecMultiJvmNode2 extends WordSpec with MustMatchers {
      "A node" should {
        "be able to say hello" in {
          val message = "Hello from node 2"
          message must be("Hello from node 2")
        }
      }
    }

To run these tests you would call ``multi-jvm-test Spec`` at the sbt prompt.


Zookeeper Barrier
~~~~~~~~~~~~~~~~~

When running multi-JVM tests it's common to need to coordinate timing across
nodes. To do this there is a ZooKeeper-based double-barrier (there is both an
entry barrier and an exit barrier). ClusterNodes also have support for creating
barriers easily. To wait at the entry use the ``enter`` method. To wait at the
exit use the ``leave`` method. It's also possible t pass a block of code which
will be run between the barriers.

When creating a barrier you pass it a name and the number of nodes that are
expected to arrive at the barrier. You can also pass a timeout. The default
timeout is 60 seconds.

Here is an example of coordinating the starting of two nodes and then running
something in coordination::

    import org.scalatest.WordSpec
    import org.scalatest.matchers.MustMatchers
    import org.scalatest.BeforeAndAfterAll

    import akka.cluster._

    object SampleMultiJvmSpec {
      val NrOfNodes = 2
    }

    class SampleMultiJvmNode1 extends WordSpec with MustMatchers with BeforeAndAfterAll {
      import SampleMultiJvmSpec._

      override def beforeAll() = {
        Cluster.startLocalCluster()
      }

      override def afterAll() = {
        Cluster.shutdownLocalCluster()
      }

      "A cluster" must {

        "have jvm options" in {
          System.getProperty("akka.cluster.nodename", "") must be("node1")
          System.getProperty("akka.cluster.port", "") must be("9991")
          akka.config.Config.config.getString("test.name", "") must be("node1")
        }

        "be able to start all nodes" in {
          Cluster.barrier("start", NrOfNodes) {
            Cluster.node.start()
          }
          Cluster.node.isRunning must be(true)
          Cluster.node.shutdown()
        }
      }
    }

    class SampleMultiJvmNode2 extends WordSpec with MustMatchers {
      import SampleMultiJvmSpec._

      "A cluster" must {

        "have jvm options" in {
          System.getProperty("akka.cluster.nodename", "") must be("node2")
          System.getProperty("akka.cluster.port", "") must be("9992")
          akka.config.Config.config.getString("test.name", "") must be("node2")
        }

        "be able to start all nodes" in {
          Cluster.barrier("start", NrOfNodes) {
            Cluster.node.start()
          }
          Cluster.node.isRunning must be(true)
          Cluster.node.shutdown()
        }
      }
    }

An example output from this would be:

.. code-block:: shell

    > multi-jvm-run Test
    ...
    [info] == multi-jvm-run ==
    [info] == multi-jvm / Test ==
    [info] Starting JVM-Node1 for example.SampleMultiJvmNode1
    [info] Starting JVM-Node2 for example.SampleMultiJvmNode2
    [JVM-Node1] Loading config [akka.conf] from the application classpath.
    [JVM-Node2] Loading config [akka.conf] from the application classpath.
    ...
    [JVM-Node2] Hello from node 2
    [JVM-Node1] Hello from node 1
    [info] == multi-jvm / Test ==
    [info] == multi-jvm-run ==
    [success] Successful.