gestalt v0.3.0 Gestalt View Source

Provides a wrapper for Application.get_env/3 and System.get_env/1, where configuration can be overridden on a per-process basis. This allows asynchronous tests to change configuration on the fly without altering global state for other tests.

Usage

In test_helper.exs, add the following:

{:ok, _} = Gestalt.start()

In runtime code, where one would use Application.get_env/3,

value = Application.get_env(:my_module, :my_config)

instead the following could be used:

value = Gestalt.get_config(:my_module, :my_config, self())

In runtime code, where one would use System.get_env/1,

value = System.get_env("VARIABLE_NAME")

instead the following could be used:

value = Gestalt.get_env("VARIABLE_NAME", self())

Overriding values in tests

The value of Gestalt comes from its ability to change configuration and/or environment in a way that only effects the current process. For instance, if code behaves differently depending on configuration, then a test that uses Application.put_env/4 to verify its effect will change global state for other asynchronously-running tests.

To change Application configuration, use the following:

Gestalt.replace_config(:my_module, :my_value, "some value", self())

To change System environment, use the following:

Gestalt.replace_env("VARIABLE_NAME", "some value", self())

Caveats

Gestalt does not try to be too smart about merging overrides with existing configuration. If an override is set for the current pid, then all config and env values required by the runtime code must be specifically set.

Also, note that Gestalt is a runtime configuration library. Values used by module variables are evaluated at compile time, not at runtime.

Link to this section Summary

Functions

Copies Gestalt overrides from one pid to another. If no overrides have been defined, returns nil.

Copies Gestalt overrides from one pid to another. If no overrides have been defined, raises a RuntimeError.

Gets configuration either from Application, or from the running agent.

Gets environment variables either from System, or from the running agent.

Sets an override for the provided pid, effecting the behavior of get_config/4.

Sets an override for the provided pid, effecting the behavior of get_env/3.

Starts an agent for storing override values. If an agent is already running, it is returned.

Link to this section Functions

Link to this function

copy(from_pid, to_pid, agent \\ __MODULE__)

View Source

Copies Gestalt overrides from one pid to another. If no overrides have been defined, returns nil.

Link to this function

copy!(from_pid, to_pid, agent \\ __MODULE__)

View Source

Copies Gestalt overrides from one pid to another. If no overrides have been defined, raises a RuntimeError.

Link to this function

get_config(module, key, pid, agent \\ __MODULE__)

View Source

Gets configuration either from Application, or from the running agent.

Examples

iex> {:ok, _pid} = Gestalt.start()
iex> Application.put_env(:module_name, :key_name, true)
iex> Gestalt.get_config(:module_name, :key_name, self())
true
iex> Gestalt.replace_config(:module_name, :key_name, false, self())
:ok
iex> Gestalt.get_config(:module_name, :key_name, self())
false
Link to this function

get_env(variable, pid, agent \\ __MODULE__)

View Source

Gets environment variables either from System, or from the running agent.

Examples

iex> {:ok, _pid} = Gestalt.start()
iex> System.put_env("VARIABLE_FROM_ENV", "value set from env")
iex> Gestalt.get_env("VARIABLE_FROM_ENV", self())
"value set from env"
iex> Gestalt.replace_env("VARIABLE_FROM_ENV", "no longer from env", self())
:ok
iex> Gestalt.get_env("VARIABLE_FROM_ENV", self())
"no longer from env"
Link to this function

replace_config(module, key, value, pid, agent \\ __MODULE__)

View Source

Sets an override for the provided pid, effecting the behavior of get_config/4.

Link to this function

replace_env(variable, value, pid, agent \\ __MODULE__)

View Source

Sets an override for the provided pid, effecting the behavior of get_env/3.

Link to this function

start(agent \\ __MODULE__)

View Source

Starts an agent for storing override values. If an agent is already running, it is returned.

Examples

iex> {:ok, pid} = Gestalt.start()
iex> is_pid(pid)
true
iex> {:ok, other_pid} = Gestalt.start()
iex> pid == other_pid
true