ExUnit.Callbacks

ExUnit.Callbacks

Defines ExUnit Callbacks.

This module defines both setup_all and setup callbacks, as well as the on_exit facility.

The setup callbacks are defined via macros and each one can optionally receive a map with metadata, usually referred to as context. The callback may optionally put extra data into context to be used in the tests.

The setup_all callbacks are invoked once to setup the test case before any test is run and all setup callbacks are run before each test. No callback runs if the test case has no tests or all tests were filtered out.

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

Finally, setup_all callbacks run in the test case process, while all setup callbacks run in the same process as the test itself. on_exit callbacks always run in a separate process than the test case or the test itself. Since the test process exits with reason :shutdown, most of times on_exit/1 can be avoided as processes are going to clean up on their own.

Context

If you return {:ok, keywords} from setup_all, the keyword will be merged into the current context and be available in all subsequent setup_all, setup and the test itself.

Similarly, returning {:ok, keywords} from setup, the keyword returned will be merged into the current context and be available in all subsequent setup and the test itself.

Returning :ok leaves the context unchanged in both cases.

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 to setup the case before any test is run
  setup_all do
    IO.puts "Starting AssertionTest"

    # No metadata
    :ok
  end

  # "setup" is called before each test is run
  setup do
    IO.puts "This is a setup callback"

    on_exit fn ->
      IO.puts "This is invoked once the test is done"
    end

    # Returns extra metadata to be merged into context
    [hello: "world"]
  end

  # Same as "setup", but receives the context
  # for the current test
  setup context do
    IO.puts "Setting up: #{context[:test]}"
    :ok
  end

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

  test "always pass" do
    assert true
  end

  test "another one", context do
    assert context[:hello] == "world"
  end

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

Summary

Functions

on_exit(ref \\ make_ref, callback)

Defines a callback that runs on the test (or test case) exit

Macros

setup(block)

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

setup(var, block)

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

setup_all(block)

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

setup_all(var, block)

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

Functions

on_exit(ref \\ make_ref, callback)

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

Defines a callback that runs on the test (or test case) exit.

An on_exit callback is a function that receives no arguments and runs in a separate process than the caller.

on_exit/2 is usually called from setup and setup_all callbacks, often to undo the action performed during setup. However, on_exit may also be called dynamically, where a reference can be used to guarantee the callback will be invoked only once.

Macros

setup(block)

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

Examples

setup :clean_up_tmp_directory

setup(var, block)

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

Examples

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

setup_all(block)

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

Examples

setup_all :clean_up_tmp_directory

setup_all(var, block)

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

Examples

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