#
View Source ExUnit.Formatter (ExUnit v1.15.7)

Helper functions for formatting and the formatting protocols.

Formatters are `GenServer`s 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.

# Summary

## Types

id()
test()
times_us()

The times spent on several parts of the test suite.

## Functions

format_assertion_diff(assert_error, padding_size, width, formatter)

Formats `ExUnit.AssertionError` diff.

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.

# 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.

# 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.

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