ExUnit.Formatter (ExUnit v1.12.3) View Source

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

The times spent on several parts of the test suite.

Functions

Formats filters used to constrain cases to be run.

Receives a test module and formats its failure.

Receives a test and formats its failure.

Formats time taken running the test suite.

Link to this section Types

Specs

id() :: term()

Specs

test() :: ExUnit.Test.t()

Specs

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

Specs

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.

Specs

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)"