multiverses v0.5.2 Multiverses View Source

Elixir introduces into the world of programming, the "multiverse testing" pattern. This is a pattern where integration tests are run concurrently and each test sees a shard of global state.

Examples:

  • Mox: each test has access to the global module mock, sharded by the pid of the running test.
  • Ecto: each test has access to a "database sandbox", which is a checked out transaction on the global database that acts as its own database shard.
  • Hound,Wallaby: each test generates an ID that is passed outside of the BEAM that is reintercepted on ingress, this ID is then used to connect ecto sandboxes to the parent test PID

This library irresponsibly abuses macros to implement Multiverses-aware versions of several constructs in the Elixir Standard Library which aren't natively Multiversable.

Why are macros necessary?

  1. This entire library should be compile-time-only. We don't want any of this dreck polluting runtime.
  2. Ideally, support for this pattern would be available in the Elixir standard library out of the box (possibly with options), and the hope is that this library can be deprecated altogether.
  3. You should be able to read code, reason about it, and most of the time stay in your universe and not worry that Multiverses exist at test time.

For plugins that are provided for other systems, see the libraries:

  • :multiverses_finch - which extends this to HTTP requests that exit the BEAM.
  • :multiverses_pubsub - which extends this to Phoenix.PubSub

Usage

In mix.exs, you should add the following directive:

{:multiverses, "~> 0.5.2", runtime: false}

In your module where you'll be using at least one multiverse module, use the following header:

use Multiverses, with: Registry

this aliases Multiverses.Registry to Registry and activates the Multiverses.Registry macros across this module. As an escape hatch, if you need to use the underlying module, you may use the macro alias Elixir.Registry

If you need more complex choices for when to activate Multiverses (such as system environment variables), you should encode those choices directly using logic around the use Multiverses statement.

Options

  • :with the names of multiverse modules you'd like to use. May be a single module or a list of modules. Is identical to require Multiverses.<module>; alias Multiverses.<module>.
  • :otp_app the otp_app must have its :use_multiverses application environment variable set in order to be used. Defaults to autodetecting via Mix.

Link to this section Summary

Functions

purges the caller list.

generates a "link" to current universe. If you pass the result of "link" to port/1, then it will bring the ported process into the universe of the process that called link/0

this function can identify if a parent module has been overridden with its Multiverse equivalent in this module.

causes the current process to adopt the universe referred to by the result of a link/0 call.

identifies the universe of the current process.

Link to this section Types

Link to this section Functions

purges the caller list.

generates a "link" to current universe. If you pass the result of "link" to port/1, then it will bring the ported process into the universe of the process that called link/0

Link to this macro

overrides?(module_ast, parent_module_ast)

View Source (macro)
overrides?(module(), module()) :: boolean()

this function can identify if a parent module has been overridden with its Multiverse equivalent in this module.

Important: the parent_module parameter is interpreted in the global aliasing context, and not in the context of the local alias.

useful for making compile-time guarantees, for example in ExUnit Case modules.

causes the current process to adopt the universe referred to by the result of a link/0 call.

identifies the universe of the current process.