@spec on_exit(term(), (-> term())) :: :ok

Registers a callback that runs once the test exits.

callback is a function that receives no arguments and runs in a separate process than the caller. Its return value is irrelevant and is discarded.

on_exit/2 is usually called from setup/1 and setup_all/1 callbacks, often to undo the action performed during the setup.

However, on_exit/2 may also be called dynamically. An "ID" (the name_or_ref argument) can be used to guarantee that the callback will be invoked only once. ExUnit uses this term to identify an on_exit/2 handler: if you want to override a previous handler, for example, use the same name_or_ref across multiple on_exit/2 calls.

If on_exit/2 is called inside setup/1 or inside a test, it's executed in a blocking fashion after the test exits and before running the next test. This means that no other test from the same test case will be running while the on_exit/2 callback for a previous test is running. on_exit/2 is executed in a different process than the test process. On the other hand, if on_exit/2 is called inside a setup_all/1 callback then callback is executed after running all tests (see setup_all/1 for more information).

Examples

setup do
  File.write!("fixture.json", "{}")
  on_exit(fn -> File.rm!("fixture.json") end)
end

You can use the same name_or_ref across multiple on_exit/2 calls to "override" the registered handler:

setup do
  on_exit(:drop_table, fn ->
    Database.drop_table()
  end)
end

test "a test that shouldn't drop the table" do
  on_exit(:drop_table, fn -> :ok end)
end

Relying too much on overriding callbacks like this can lead to test cases that are hard to understand and with too many layers of indirection. However, it can be useful in some cases or for library authors, for example.

Defines a callback to be run before each test in a case.

Accepts one of these:

• a block
• an atom naming a local function
• a {module, function} tuple
• a list of atoms and {module, function} tuples

Can return values to be merged into the context, to set up the state for tests. For more details, see the "Context" section shown above.

setup/1 callbacks are executed in the same process as the test process.

Examples

defp clean_up_tmp_directory(context) do
  # perform setup
  :ok
end

setup :clean_up_tmp_directory

setup [:clean_up_tmp_directory, :another_setup]

setup do
  [conn: Plug.Conn.build_conn()]
end

setup {MyModule, :my_setup_function}

Defines a callback to be run before each test in a case.

This is similar to setup/1, but the first argument is the context. The block argument can only be a block.

For more details, see the "Context" section shown above.

Examples

setup context do
  [conn: Plug.Conn.build_conn()]
end

Defines a callback to be run before all tests in a case.

Accepts one of these:

• a block
• an atom naming a local function
• a {module, function} tuple
• a list of atoms and {module, function} tuples

Can return values to be merged into the context, to set up the state for tests. For more details, see the "Context" section shown above.

setup_all/1 callbacks are executed in a separate process than tests. All setup_all/1 callbacks are executed in order in the same process.

On-Exit Handlers

On-exit handlers that you register inside setup_all/1 callbacks are executed at once after all tests in the module have been run. They are all executed in the same process, which is a separate process dedicated to running these handlers. These handlers are executed in the reverse order of their respective setup_all/1 callbacks.

Examples

# One-arity function name
setup_all :clean_up_tmp_directory

# A module and function
setup_all {MyModule, :my_setup_function}

# A list of one-arity functions and module/function tuples
setup_all [:clean_up_tmp_directory, {MyModule, :my_setup_function}]

defp clean_up_tmp_directory(_context) do
  # perform setup
  :ok
end

# A block
setup_all do
  [conn: Plug.Conn.build_conn()]
end

The context returned by setup_all/1 will be available in all subsequent setup_all, setup, and the test itself. For instance, the conn from the previous example can be accessed as:

test "fetches current users", %{conn: conn} do
  # ...
end

Handlers

You can define "global" on-exit handlers in setup_all/1 callbacks:

setup_all do
  Database.create_table_for(__MODULE__)

  on_exit(fn ->
    Database.drop_table_for(__MODULE__)
  end)

  :ok
end

The handler in the example above will be executed only once, after running all tests in the module.

Defines a callback to be run before all tests in a case.

Similar as setup_all/1 but also takes a context. The second argument must be a block. See the "Context" section in the module documentation.

Examples

setup_all _context do
  [conn: Plug.Conn.build_conn()]
end

@spec start_link_supervised!(
  Supervisor.child_spec() | module() | {module(), term()},
  keyword()
) :: pid()

Same as start_supervised!/2 but links the started process to the test process.

If the process that was started crashes, the crash is propagated to the test process, failing the test and printing the cause of the crash.

Note that if the started process terminates before it is linked to the test process, this function will exit with reason :noproc.

@spec start_supervised(
  Supervisor.child_spec() | module() | {module(), term()},
  keyword()
) :: Supervisor.on_start_child()

Starts a child process under the test supervisor.

It expects a child specification or a module, similar to the ones given to Supervisor.start_link/2. For example, if your application starts a supervision tree by running:

Supervisor.start_link([MyServer, {OtherSupervisor, ...}], ...)

You can start those processes under test in isolation by running:

start_supervised(MyServer)
start_supervised({OtherSupervisor, :initial_value})

A keyword list can also be given if there is a need to change the child specification for the given child process:

start_supervised({MyServer, :initial_value}, restart: :temporary)

See the Supervisor module for a discussion on child specifications and the available specification keys.

The started process is not linked to the test process and a crash will not necessarily fail the test. To start and link a process to guarantee that any crash would also fail the test use start_link_supervised!/2.

This function returns {:ok, pid} in case of success, otherwise it returns {:error, reason}.

The advantage of starting a process under the test supervisor is that it is guaranteed to exit before the next test starts. Therefore, you don't need to remove the process at the end of your tests via stop_supervised/1. You only need to use stop_supervised/1 if you want to remove a process from the supervision tree in the middle of a test, as simply shutting down the process would cause it to be restarted according to its :restart value.

Finally, since Elixir v1.17.0, the test supervisor has both $ancestors and $callers key in its process dictionary pointing to the test process. This means developers can invoke Process.get(:"$callers", []) in their start_link function and forward it to the spawned process, which may set Process.put(:"$callers", callers) during its initialization. This may be useful in projects who track process ownership during tests. You can learn more about these keys in the Task module.

@spec start_supervised!(
  Supervisor.child_spec() | module() | {module(), term()},
  keyword()
) :: pid()

Same as start_supervised/2 but returns the PID on success and raises if not started properly.

@spec stop_supervised(id :: term()) :: :ok | {:error, :not_found}

Stops a child process started via start_supervised/2.

This function expects the id in the child specification. For example:

{:ok, _} = start_supervised(MyServer)
:ok = stop_supervised(MyServer)

It returns :ok if there is a supervised process with such id, {:error, :not_found} otherwise.

@spec stop_supervised!(id :: term()) :: :ok

Same as stop_supervised/1 but raises if it cannot be stopped.