ExUnit
ExUnit

View Source ExUnit.Formatter (ExUnit v1.13.4)

Helper functions for formatting and the formatting protocols.

Formatters are GenServers specified during ExUnit configuration that receive a series of events as casts.

The following events are possible:

  • {:suite_started, opts} - the suite has started with the specified options to the runner.

  • {:suite_finished, times_us} - the suite has finished. Returns several measurements in microseconds for running the suite. See t:times_us for more information.

  • {:module_started, test_module} - a test module has started. See ExUnit.TestModule for details.

  • {:module_finished, test_module} - a test module has finished. See ExUnit.TestModule for details.

  • {:test_started, test} - a test has started. See ExUnit.Test for details.

  • {:test_finished, test} - a test has finished. See ExUnit.Test for details.

  • {:sigquit, [test | test_module]} - the VM is going to shutdown. It receives the test cases (or test module in case of setup_all) still running.

The formatter will also receive the following events but they are deprecated and should be ignored:

  • {:case_started, test_module} - a test module has started. See ExUnit.TestModule for details.

  • {:case_finished, test_module} - a test module has finished. See ExUnit.TestModule for details.

The full ExUnit configuration is passed as the argument to GenServer.init/1 callback when the formatters are started. If you need to do runtime configuration of a formatter, you can add any configuration needed by using ExUnit.configure/1 or ExUnit.start/1, and this will then be included in the options passed to the GenServer.init/1 callback.

Link to this section Summary

Types

id()
test()
times_us()

The times spent on several parts of the test suite.

Functions

format_filters(filters, type)

Formats filters used to constrain cases to be run.

format_test_all_failure(test_module, failures, counter, width, formatter)

Receives a test module and formats its failure.

format_test_failure(test, failures, counter, width, formatter)

Receives a test and formats its failure.

format_times(times)

Formats time taken running the test suite.

Link to this section Types

Link to this type

id()

View Source 
@type id() :: term()
Link to this type

test()

View Source 
@type test() :: ExUnit.Test.t()
Link to this type

times_us()

View Source 
@type times_us() :: %{
  run: pos_integer(),
  async: pos_integer() | nil,
  load: pos_integer() | nil
}

The times spent on several parts of the test suite.

The following properties can be computed:

sync = run - (async || 0)
total = run + (load || 0)

async is nil when there are no async tests. load is nil when the test suite is running and loading tests concurrently.

Link to this section Functions

Link to this function

format_filters(filters, type)

View Source 
@spec format_filters(
  keyword(),
  atom()
) :: String.t()

Formats filters used to constrain cases to be run.

Examples 

iex> format_filters([run: true, slow: false], :include)
"Including tags: [run: true, slow: false]"
Link to this function

format_test_all_failure(test_module, failures, counter, width, formatter)

View Source

Receives a test module and formats its failure.

Link to this function

format_test_failure(test, failures, counter, width, formatter)

View Source

Receives a test and formats its failure.

Link to this function

format_times(times)

View Source 
@spec format_times(times_us()) :: String.t()

Formats time taken running the test suite.

Examples 

iex> format_times(%{run: 10000, async: nil, load: nil})
"Finished in 0.01 seconds (0.00s async, 0.01s sync)"

iex> format_times(%{run: 10000, async: nil, load: 20000})
"Finished in 0.03 seconds (0.02s on load, 0.00s async, 0.01s sync)"

iex> format_times(%{run: 10000, async: nil, load: 200_000})
"Finished in 0.2 seconds (0.2s on load, 0.00s async, 0.01s sync)"

iex> format_times(%{run: 100_000, async: 50000, load: 200_000})
"Finished in 0.3 seconds (0.2s on load, 0.05s async, 0.05s sync)"