Defines ExUnit callbacks.

This module defines the setup/1, setup/2, setup_all/1, and setup_all/2 callbacks, as well as the on_exit/2, start_supervised/2 and stop_supervised/1 functions.

The setup callbacks may be used to define test fixtures and run any initialization code which help bring the system into a known state. They are defined via macros and each one can optionally receive a map with test state and metadata, usually referred to as the context. Optionally, the context to be used in the tests can be extended by the setup callbacks by returning a properly structured value (see below).

The setup_all callbacks are invoked only once per module, before any test is run. All setup callbacks are run before each test. No callback is run if the test case has no tests or all tests have been filtered out.

setup and setup_all callbacks can be defined by a block, by passing an atom naming a one-arity function, or by passing a list of such atoms. Both can opt to receive the current context by specifying it as parameter if defined by a block. Functions used to define a test setup must accept the context as single argument.

A test module can define multiple setup and setup_all callbacks, and they are invoked in order of appearance.

start_supervised/2 is used to start processes under a supervisor. The supervisor is linked to the current test process. The supervisor as well as all child processes are guaranteed to terminate before any on_exit/2 callback runs.

on_exit/2 callbacks are registered on demand, usually to undo an action performed by a setup callback. on_exit/2 may also take a reference, allowing the callback to be overridden in the future. A registered on_exit/2 callback will always run, while failures in setup and setup_all will stop all remaining setup callbacks from executing.

Finally, setup_all callbacks run in a separate process per module, while all setup callbacks run in the same process as the test itself. on_exit/2 callbacks always run in a separate process, as implied by their name. The test process always exits with reason :shutdown, which means any process linked to the test process will also exit, although asynchronously. Therefore it is preferred to use start_supervised/2 to guarantee synchronous termination.

Here is a rundown of the life-cycle of the test process:

1. the test process is spawned
2. it runs setup/2 callbacks
3. it runs the test itself
4. it stops all supervised processes
5. the test process exits with reason :shutdown
6. on_exit/2 callbacks are executed in a separate process

Context

If setup_all or setup return a keyword list, a map, or a tuple in the shape of {:ok, keyword() | map()}, the keyword list or map will be merged into the current context and will be available in all subsequent setup_all, setup, and the test itself.

Returning :ok leaves the context unchanged (in setup and setup_all callbacks).

Returning anything else from setup_all will force all tests to fail, while a bad response from setup causes the current test to fail.

Examples

defmodule AssertionTest do
  use ExUnit.Case, async: true

  # "setup_all" is called once per module before any test runs
  setup_all do
    IO.puts("Starting AssertionTest")

    # Context is not updated here
    :ok
  end

  # "setup" is called before each test
  setup do
    IO.puts("This is a setup callback for #{inspect(self())}")

    on_exit(fn ->
      IO.puts("This is invoked once the test is done. Process: #{inspect(self())}")
    end)

    # Returns extra metadata to be merged into context.
    # Any of the following would also work:
    #
    #     {:ok, %{hello: "world"}}
    #     {:ok, [hello: "world"]}
    #     %{hello: "world"}
    #
    [hello: "world"]
  end

  # Same as above, but receives the context as argument
  setup context do
    IO.puts("Setting up: #{context.test}")

    # We can simply return :ok when we don't want to add any extra metadata
    :ok
  end

  # Setups can also invoke a local or imported function that returns a context
  setup :invoke_local_or_imported_function

  test "always pass" do
    assert true
  end

  test "uses metadata from setup", context do
    assert context[:hello] == "world"
    assert context[:from_named_setup] == true
  end

  defp invoke_local_or_imported_function(context) do
    [from_named_setup: true]
  end
end

It is also common to define your setup as a series of functions, which are put together by calling setup or setup_all with a list of atoms. Each of these functions receive the context and can return any of the values allowed in setup blocks:

defmodule ExampleContextTest do
  use ExUnit.Case

  setup [:step1, :step2, :step3]

  defp step1(_context), do: [step_one: true]
  defp step2(_context), do: {:ok, step_two: true} # return values with shape of {:ok, keyword() | map()} allowed
  defp step3(_context), do: :ok # Context not modified

  test "context was modified", context do
    assert context[:step_one] == true
    assert context[:step_two] == true
  end
end

Finally, as discussed in the ExUnit.Case documentation, remember that the initial context metadata can also be set via @tags, which can then be accessed in the setup block:

defmodule ExampleTagModificationTest do
  use ExUnit.Case

  setup %{login_as: username} do
    {:ok, current_user: username}
  end

  @tag login_as: "max"
  test "tags modify context", context do
    assert context[:login_as] == "max"
    assert context[:current_user] == "max"
  end
end