ExUnit.ClusteredCase.Cluster (ex_unit_clustered_case v0.5.0)

This module is responsible for managing the setup and lifecycle of a single cluster.

Link to this section Summary

Functions

Invoke a function on a specific member of the cluster

Invoke a function on a specific member of the cluster

Applies a function on all nodes in the cluster.

Applies a function on all nodes in the cluster.

Heals all partitions in the cluster.

Kills a running node in a cluster. Expects the cluster and node to stop.

Get the captured log for a specific node in the cluster

Maps a function across all nodes in the cluster.

Maps a function across all nodes in the cluster.

Retrieve a list of nodes in the given cluster

Partition the cluster based on the provided specification.

Retrieve the partitions this cluster is composed of

Retrieve the name of a random node in the given cluster

Repartitions the cluster based on the provided specification.

Starts a new cluster with the given specification

Stops a running cluster. Expects the pid of the cluster manager process.

Stops a running node in a cluster. Expects the cluster and node to stop.

Link to this section Types

@type callback() :: {module(), atom(), [term()]} | (() -> term())
Link to this type

cluster_opt()

@type cluster_opt() ::
  {:nodes, [node_spec()]}
  | {:cluster_size, pos_integer()}
  | {:partitions, pos_integer() | [pos_integer()] | [[atom()]]}
  | {:env, [{String.t(), String.t()}]}
  | {:erl_flags, [String.t()]}
  | {:config, Keyword.t()}
  | {:boot_timeout, pos_integer()}
  | {:init_timeout, pos_integer()}
  | {:post_start_functions, [callback()]}
  | {:stdout, atom() | pid()}
  | {:capture_log, boolean()}
Link to this type

cluster_opts()

@type cluster_opts() :: [cluster_opt()]
@type node_spec() :: ExUnit.ClusteredCase.Node.node_opts()

Link to this section Functions

Link to this function

call(node, callback)

@spec call(node(), callback()) :: term() | {:error, term()}

Invoke a function on a specific member of the cluster

Link to this function

call(node, m, f, a)

@spec call(node(), module(), atom(), [term()]) :: term() | {:error, term()}

Invoke a function on a specific member of the cluster

Link to this function

each(pid, callback)

@spec each(pid(), callback()) :: :ok | {:error, term()}

Applies a function on all nodes in the cluster.

Link to this function

each(pid, m, f, a)

@spec each(pid(), module(), atom(), [term()]) :: :ok | {:error, term()}

Applies a function on all nodes in the cluster.

@spec heal(pid()) :: :ok

Heals all partitions in the cluster.

Link to this function

kill_node(pid, node)

@spec kill_node(pid(), node()) :: :ok

Kills a running node in a cluster. Expects the cluster and node to stop.

@spec log(node()) :: {:ok, binary()}

Get the captured log for a specific node in the cluster

@spec map(pid(), callback()) :: [term()] | {:error, term()}

Maps a function across all nodes in the cluster.

Returns a list of results, where each element is the result from one node.

Link to this function

map(pid, m, f, a)

@spec map(pid(), module(), atom(), [term()]) :: [term()] | {:error, term()}

Maps a function across all nodes in the cluster.

Returns a list of results, where each element is the result from one node.

@spec members(pid()) :: [node()]

Retrieve a list of nodes in the given cluster

Link to this function

partition(pid, n)

@spec partition(pid(), ExUnit.ClusteredCase.Cluster.Partition.opts()) ::
  :ok | {:error, term()}

Partition the cluster based on the provided specification.

You can specify partitions in one of the following ways:

  • As an integer representing the number of partitions
  • As a list of integers representing the number of nodes in each partition
  • As a list of lists, where each sub-list contains the nodes in that partition

If your partitioning specification cannot be complied with, an error is returned

examples

Examples

test "partition by number of partitions", %{cluster: c} do
   Cluster.partition(c, 2)
end

test "partition by number of nodes per partition", %{cluster: c} do
   Cluster.partition(c, [2, 2])
end

test "partition by list of nodes in each partition", %{cluster: c} do
   Cluster.partition(c, [[:a, :b], [:c, :d]])
end
Link to this function

partitions(pid)

@spec partitions(pid()) :: [[node()]]

Retrieve the partitions this cluster is composed of

Link to this function

random_member(pid)

@spec random_member(pid()) :: node()

Retrieve the name of a random node in the given cluster

Link to this function

repartition(pid, n)

@spec repartition(pid(), ExUnit.ClusteredCase.Cluster.Partition.opts()) ::
  :ok | {:error, term()}

Repartitions the cluster based on the provided specification.

See partition/2 for specification details.

Repartitioning performs the minimal set of changes required to converge on the partitioning scheme in an attempt to minimize the amount of churn. That said, some churn is expected, so bear that in mind when writing tests with partitioning events involved.

@spec start(cluster_opts()) :: {:ok, pid()} | {:error, term()}

Starts a new cluster with the given specification

@spec stop(pid()) :: :ok

Stops a running cluster. Expects the pid of the cluster manager process.

Link to this function

stop_node(pid, node)

@spec stop_node(pid(), node()) :: :ok

Stops a running node in a cluster. Expects the cluster and node to stop.