multiverses v0.5.0 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?
- This entire library should be compile-time-only. We don't want any of this dreck polluting runtime.
- 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.
- 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.0", 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 torequire 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
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
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.