View Source LocalCluster (LocalCluster v2.0.0)

Easy local cluster handling for Elixir.

This library is a utility library to offer easier testing of distributed clusters for Elixir. It offers very minimal shimming above several built in Erlang features to provide seamless node creations, especially useful when testing distributed applications.

Summary

Functions

Retrieves a child specification for a cluster.

Retrieves the members within a cluster.

Retrieves the node names within a cluster.

Retrieves the process identifiers within a cluster.

Starts the current node as a distributed node.

Starts a number of child nodes under a supervising process.

Stops the current distributed node and turns it back into a local node.

Stops a previously started cluster.

Stops a member within a cluster.

Types

@type member() :: {:member, pid :: pid(), node :: node()}
@type t() :: pid() | atom()

Functions

@spec child_spec({integer(), Keyword.t()}) :: Supervisor.child_spec()

Retrieves a child specification for a cluster.

Link to this macro

member(args \\ [])

View Source (macro)
Link to this macro

member(record, args)

View Source (macro)
@spec members(cluster :: t()) :: {:ok, [member()]}

Retrieves the members within a cluster.

@spec nodes(cluster :: t()) :: {:ok, [node()]}

Retrieves the node names within a cluster.

@spec pids(cluster :: t()) :: [pid()]

Retrieves the process identifiers within a cluster.

@spec start() :: :ok

Starts the current node as a distributed node.

Link to this function

start_link(amount, opts \\ [])

View Source
@spec start_link(
  amount :: integer(),
  options :: Keyword.t()
) :: GenServer.on_start()

Starts a number of child nodes under a supervising process.

This will start the current runtime enviornment on a set of child nodes and return the process identifier of the parent process. All child nodes will be linked to this parent process, and so will terminate once the parent process does.

There are several options to provide when customizing the child nodes:

Options

  • :applications

    The :applications option allows the caller to provide an ordered list of applications to be started on child nodes. This is useful when you need to control startup sequences, or omit applications completely. If this option is not provided, all currently loaded applications on the local node will be used as a default.

  • :environment

    The :environment option allows the caller to override application environment variables loaded on a member (via Application.get_env/3).

  • :files

    The :files option can be used to load additional files onto remote nodes, which are then compiled on the remote node. This is necessary if you wish to spawn tasks from inside test code, as test code would not typically be loaded automatically.

  • :name

    The :name option allows the caller to register the name of a local cluster should they wish to, rather than calling by pid.

  • :prefix

    The :prefix option allows the caller to choose the prefix name for the indexed nodes in a cluster. This is randomly generated if not provided.

@spec stop() :: :ok | {:error, atom()}

Stops the current distributed node and turns it back into a local node.

@spec stop(cluster :: t()) :: :ok

Stops a previously started cluster.

@spec stop(cluster :: t(), member() | atom() | pid()) :: :ok

Stops a member within a cluster.

This will terminate the member node without terminating the rest of the cluster by unlinking it beforehand.