View Source ExUnitFormatterTemplate behaviour (ExUnitFormatterTemplate v0.0.1)
ExUnitFormatterTemplate provides a simplified wrapper around the GenServer
code necessary to create a custom ExUnit formatter.
This library aims to abstract away some of the repetition inherent in creating
a GenServer by providing a simple API to hook into the events sent by the test
runner.
usage
Usage
To begin, create a new module for your formatter, and use the
ExUnitFormatterTemplate
defmodule YourFormatter do
use ExUnitFormatterTemplate
end
default-formatter
Default formatter
Without adding any code to the above example, you already have a working, albeit
basic, test formatter. ExUnitFormatterTemplate provides a default implementation
that records the total number of tests run, as well as the counts for each
completion result, and prints out the resulting map when the suite has finished running.
It's not exciting, but it ensures that you have useful test suite data to get started as you develop your formatter.
exunitformattertemplate-behaviour
ExUnitFormatterTemplate behaviour
use-ing ExUnitFormatterTemplate sets your module up to implement the
ExUnitFormatterTemplate behaviour, which provides the following
(all optional) callbacks:
init/0suite_started/2suite_finished/2module_started/2module_finished/2test_started/2test_finished/2
The names of the callbacks should give you a good idea of where they are invoked
during the test run. See the ExUnitFormatterTemplate documentation for complete
explanations.
With the exception of init/0, each of these callbacks takes as its first argument
the metadata related to the part of the test suite (the suite itself, a module,
or an individual test), and as its second argument the built up state of the test suite.
Each callback is expected to return this state as a single return value.
init/0 takes no arguments, and is expected to return a new state to be passed
through the other callbacks. This can take whatever form you want.
Because all of these callbacks are optional, you are able to only define those for
which you wish to take a specific action. Otherwise, with the exception of
init/0 and test_finished/2, which have default implementations in ExUnitFormatterTemplate,
all unimplemented callbacks are simple pass-throughs. suite_finished/2 also has a default
implementation, but it is simply
def suite_finished(_suite_data, state), do: IO.inspect(state)so it can safely be left unimplemented without concern for any custom state shape you may be using in your formatter
running-tests-with-your-formatter
Running tests with your formatter
To run tests with your formatter, pass the name of your formatter module to mix test
using the --formatter flag:
mix test --formatter YourFormatter
Link to this section Summary
Types
The shape of the state your formatter builds up over the test suite run. This can be any valid Elixir data shape.
Callbacks
Called before the test suite is run. This callback allows you to define the data shape of the state your formatter builds up over the course of the test suite run.
Called when the tests contained in a single module finish running.
Called when the tests contained in a single module begin running.
Called when the test suite completes.
Called when the test suite begins.
Called when an individual test completes.
Called when an individual test begins.
Link to this section Types
@type state() :: term()
The shape of the state your formatter builds up over the test suite run. This can be any valid Elixir data shape.
If you do not implement this callback, the default state is a map with keys for each possible test outcome and integers for values.
Link to this section Callbacks
@callback init() :: state()
Called before the test suite is run. This callback allows you to define the data shape of the state your formatter builds up over the course of the test suite run.
@callback module_finished(module_data :: ExUnit.TestModule.t(), state()) :: state()
Called when the tests contained in a single module finish running.
The first argument is an ExUnit.TestModule struct that contains data
about the module whose tests have just been run, and the second argument
is your formatter's state.
See ExUnit.TestModule.t/0 for additional information about this data.
@callback module_started(module_data :: ExUnit.TestModule.t(), state()) :: state()
Called when the tests contained in a single module begin running.
The first argument is an ExUnit.TestModule struct that contains data
about the module whose tests are being run, and the second argument
is your formatter's state.
See ExUnit.TestModule.t/0 for additional information about this data.
@callback suite_finished(suite_data :: ExUnit.Formatter.times_us(), state()) :: state()
Called when the test suite completes.
The first argument is a map of timing data for the test suite (times given in milliseconds), and the second argument is your formatter's state.
See ExUnit.Formatter.times_us/0 for additional information about this data.
Called when the test suite begins.
The first argument is the set of options you have configured for the test run
via command line flags or in test_helper.exs, and the second argument is your
formatter's state.
@callback test_finished(test_data :: ExUnit.Test.t(), state()) :: state()
Called when an individual test completes.
The first argument is an ExUnit.Test struct containing data about the test
being run, and the second argument is your formatter's state.
See ExUnit.Test.t/0 for additional information about this data.
@callback test_started(test_data :: ExUnit.Test.t(), state()) :: state()
Called when an individual test begins.
The first argument is an ExUnit.Test struct containing data about the test
being run, and the second argument is your formatter's state.
See ExUnit.Test.t/0 for additional information about this data.