View Source ExUnit.Formatter (ExUnit v1.14.3)

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

@type id() :: term()
@type test() :: ExUnit.Test.t()
@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_assertion_diff(assert_error, padding_size, width, formatter)

View Source

Formats ExUnit.AssertionError diff.

It returns a keyword list with diffing information from the left and right side of the assertion, if any exists.

It expects the assertion error, the padding_size for formatted content, the width (may be :infinity), and the formatter callback function.

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.

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