ExUnit Cluster

Spin up dynamic clusters in ExUnit tests with no special setup necessary.

Provides helpers for writing tests on nodes in isolated clusters, you can run normal tests alongside clustered tests.

This library relies on the :peer module which was introduced in OTP 25 and is first supported in elixir version 1.13.4.

Examples

The most straightforward way to start using ExUnitCluster for a distributed test, is to start ExUnitCluster.Manager inside the test.

defmodule SimpleTest do
  use ExUnit.Case, async: true

  test "start node in test case", ctx do
    # 1) Start the cluster manager under the test supervisor
    cluster = start_supervised!({ExUnitCluster.Manager, ctx})
    # 2) Start a node linked to the given manager
    node = ExUnitCluster.start_node(cluster)

    # 3) Make an RPC to the node
    node_name = ExUnitCluster.call(cluster, node, Node, :self, [])
    refute Node.self() == node_name
  end
end

If you want all tests in a module to use a cluster you can start ExUnitCluster.Manager in ExUnit.Callbacks.setup/1.

defmodule ClusterTest do
  use ExUnit.Case, async: true

  setup ctx do
    # 1) Start a cluster manager under the test supervisor for each test
    cluster = start_supervised!({ExUnitCluster.Manager, ctx})
    [cluster: cluster]
  end

  test "start node in test", %{cluster: cluster} do
    # 2) Start a node in this test
    node = ExUnitCluster.start_node(cluster)

    # 3) Make an RPC to the node
    node_name = ExUnitCluster.call(cluster, node, Node, :self, [])
    refute Node.self() == node_name
  end
end

Which is exactly what ExUnitCluster.Case does

defmodule ReadmeClusterTest do
  use ExUnitCluster.Case, async: true

  test "start node in test", %{cluster: cluster} do
    node = ExUnitCluster.start_node(cluster)

    node_name = ExUnitCluster.call(cluster, node, Node, :self, [])
    refute Node.self() == node_name
  end
end

Installation

Add ex_unit_cluster to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_unit_cluster, "~> 0.7.0"}
  ]
end