# ExUnit v1.10.3 ExUnit.Formatter View Source

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, run_us, load_us}` - the suite has finished. `run_us` and `load_us` are the run and load times in microseconds respectively.

- `{: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.

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.TestCase` for details.

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

The full ExUnit configuration is passed as the argument to `c: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 `c:GenServer.init/1` callback.

# Link to this section Summary

## Types

id()
load_us()
run_us()
test()

## 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_time(run_us, load_us)

Formats time taken running the test suite.

# Link to this section Types

Link to this type

# id()

View Source

## Specs

    id() :: term()

Link to this type

# load_us()

View Source

## Specs

    load_us() :: pos_integer() | nil

Link to this type

# run_us()

View Source

## Specs

    run_us() :: pos_integer()

Link to this type

# test()

View Source

## Specs

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

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

Link to this function

# format_time(run_us, load_us)

View Source

## Specs

    format_time(run_us(), load_us()) :: String.t()

Formats time taken running the test suite.

It receives the time spent running the tests and optionally the time spent loading the test suite.

## Examples

    iex> format_time(10000, nil)
    "Finished in 0.01 seconds"

    iex> format_time(10000, 20000)
    "Finished in 0.03 seconds (0.02s on load, 0.01s on tests)"

    iex> format_time(10000, 200_000)
    "Finished in 0.2 seconds (0.2s on load, 0.01s on tests)"