ExUnit.Formatter

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.

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.

Types

id()Source

Specs

id() :: term()

test()Source

Specs

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

times_us()Source

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.

Functions

format_filters(filters, type)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]"

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

Receives a test module and formats its failure.

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

Receives a test and formats its failure.

format_times(times)Source

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

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/ex_unit/1.12.0/ExUnit.Formatter.html