# ExUnit v1.10.3 ExUnit View Source

Unit testing framework for Elixir.

## Example

A basic setup for ExUnit is shown below:

    # File: assertion_test.exs

    # 1) Start ExUnit.
    ExUnit.start()

    # 2) Create a new test module (test case) and use "ExUnit.Case".
    defmodule AssertionTest do
      # 3) Notice we pass "async: true", this runs the test case
      #    concurrently with other test cases. The individual tests
      #    within each test case are still run serially.
      use ExUnit.Case, async: true

      # 4) Use the "test" macro instead of "def" for clarity.
      test "the truth" do
        assert true
      end
    end

To run the tests above, run the file using `elixir` from the command line. Assuming you named the file `assertion_test.exs`, you can run it as:

    elixir assertion_test.exs

## Case, Callbacks and Assertions

See `ExUnit.Case` and `ExUnit.Callbacks` for more information about defining test cases and setting up callbacks.

The `ExUnit.Assertions` module contains a set of macros to generate assertions with appropriate error messages.

## Integration with Mix

Mix is the project management and build tool for Elixir. Invoking `mix test` from the command line will run the tests in each file matching the pattern `*_test.exs` found in the `test` directory of your project.

You must create a `test_helper.exs` file inside the `test` directory and put the code common to all tests there.

The minimum example of a `test_helper.exs` file would be:

    # test/test_helper.exs
    ExUnit.start()

Mix will load the `test_helper.exs` file before executing the tests. It is not necessary to `require` the `test_helper.exs` file in your test files. See `Mix.Tasks.Test` for more information.

# Link to this section Summary

## Types

failed()

The error state returned by `ExUnit.Test` and `ExUnit.TestModule`

state()

All tests start with a state of `nil`.

suite_result()

A map representing the results of running a test suite

## Functions

after_suite(function)

Sets a callback to be executed after the completion of a test suite.

configuration()

Returns ExUnit configuration.

configure(options)

Configures ExUnit.

plural_rule(word)

Returns the pluralization for `word`.

plural_rule(word, pluralization)

Registers a `pluralization` for `word`.

run()

Runs the tests. It is invoked automatically if ExUnit is started via `start/1`.

start(options \\ [])

Starts ExUnit and automatically runs tests right before the VM terminates.

# Link to this section Types

Link to this type

# failed()

View Source

## Specs

    failed() :: [{Exception.kind(), reason :: term(), Exception.stacktrace()}]

The error state returned by `ExUnit.Test` and `ExUnit.TestModule`

Link to this type

# state()

View Source

## Specs

    state() ::
      nil
      | {:failed, failed()}
      | {:skipped, binary()}
      | {:excluded, binary()}
      | {:invalid, module()}

All tests start with a state of `nil`.

A finished test can be in one of five states:

1. Passed (also represented by `nil`)
2. Failed
3. Skipped (via @tag :skip)
4. Excluded (via :exclude filters)
5. Invalid (when setup_all fails)

Link to this type

# suite_result()

View Source

## Specs

    suite_result() :: %{
      excluded: non_neg_integer(),
      failures: non_neg_integer(),
      skipped: non_neg_integer(),
      total: non_neg_integer()
    }

A map representing the results of running a test suite

# Link to this section Functions

Link to this function

# after_suite(function)

View Source (since 1.8.0)

## Specs

    after_suite((suite_result() -> any())) :: :ok

Sets a callback to be executed after the completion of a test suite.

Callbacks set with `after_suite/1` must accept a single argument, which is a map containing the results of the test suite's execution.

If `after_suite/1` is called multiple times, the callbacks will be called in reverse order. In other words, the last callback set will be the first to be called.

Link to this function

# configuration()

View Source

## Specs

    configuration() :: Keyword.t()

Returns ExUnit configuration.

Link to this function

# configure(options)

View Source

## Specs

    configure(Keyword.t()) :: :ok

Configures ExUnit.

## Options

ExUnit supports the following options:

- `:assert_receive_timeout` - the timeout to be used on `assert_receive` calls in milliseconds, defaults to `100`;

- `:autorun` - if ExUnit should run by default on exit. Defaults to `true`;

- `:capture_log` - if ExUnit should default to keeping track of log messages and print them on test failure. Can be overridden for individual tests via `@tag capture_log: false`. Defaults to `false`;

- `:colors` - a keyword list of color options to be used by some formatters:

  - `:enabled` - boolean option to enable colors, defaults to `IO.ANSI.enabled?/0`;
  - `:diff_insert` - color of the insertions on diffs, defaults to `:green`;
  - `:diff_insert_whitespace` - color of the whitespace insertions on diffs, defaults to `IO.ANSI.color_background(2, 0, 0)`;
  - `:diff_delete` - color of the deletiopns on diffs, defaults to `:red`;
  - `:diff_delete_whitespace` - color of the whitespace deletions on diffs, defaults to `IO.ANSI.color_background(0, 2, 0)`;

- `:exclude` - specifies which tests are run by skipping tests that match the filter;

- `:failures_manifest_file` - specifies a path to the file used to store failures between runs;

- `:formatters` - the formatters that will print results, defaults to `[ExUnit.CLIFormatter]`;

- `:include` - specifies which tests are run by skipping tests that do not match the filter. Keep in mind that all tests are included by default, so unless they are excluded first, the `:include` option has no effect. To only run the tests that match the `:include` filter, exclude the `:test` tag first (see the documentation for `ExUnit.Case` for more information on tags);

- `:max_cases` - maximum number of tests to run in parallel. Only tests from different modules run in parallel. It defaults to `System.schedulers_online * 2` to optimize both CPU-bound and IO-bound tests;

- `:max_failures` - the suite stops evaluating tests when this number of test failures is reached. All tests within a module that fail when using the `setup_all/1,2` callbacks are counted as failures. Defaults to `:infinity`;

- `:only_test_ids` - a list of `{module_name, test_name}` tuples that limits what tests get run;

- `:refute_receive_timeout` - the timeout to be used on `refute_receive` calls in milliseconds, defaults to `100`;

- `:seed` - an integer seed value to randomize the test suite. This seed is also mixed with the test module and name to create a new unique seed on every test, which is automatically fed into the `:rand` module. This provides randomness between tests, but predictable and reproducible results;

- `:slowest` - prints timing information for the N slowest tests. Running ExUnit with slow test reporting automatically runs in `trace` mode. It is disabled by default;

- `:stacktrace_depth` - configures the stacktrace depth to be used on formatting and reporters, defaults to `20`;

- `:timeout` - sets the timeout for the tests in milliseconds, defaults to `60_000`;

- `:trace` - sets ExUnit into trace mode, this sets `:max_cases` to `1` and prints each test case and test while running. Note that in trace mode test timeouts will be ignored as timeout is set to `:infinity`.

- `:test_location_relative_path` - the test location is the file:line information printed by tests as a shortcut to run a given test. When this value is set, the value is used as a prefix for the test itself. This is typically used by Mix to properly set-up umbrella projects

Any arbitrary configuration can also be passed to `configure/1` or `start/1`, and these options can then be used in places such as custom formatters. These other options will be ignored by ExUnit itself.

Link to this function

# plural_rule(word)

View Source

## Specs

    plural_rule(binary()) :: binary()

Returns the pluralization for `word`.

If one is not registered, returns the word appended with an "s".

Link to this function

# plural_rule(word, pluralization)

View Source

## Specs

    plural_rule(binary(), binary()) :: :ok

Registers a `pluralization` for `word`.

If one is already registered, it is replaced.

Link to this function

# run()

View Source

## Specs

    run() :: suite_result()

Runs the tests. It is invoked automatically if ExUnit is started via `start/1`.

Returns a map containing the total number of tests, the number of failures, the number of excluded tests and the number of skipped tests.

Link to this function

# start(options \\ [])

View Source

## Specs

    start(Keyword.t()) :: :ok

Starts ExUnit and automatically runs tests right before the VM terminates.

It accepts a set of `options` to configure `ExUnit` (the same ones accepted by `configure/1`).

If you want to run tests manually, you can set the `:autorun` option to `false` and use `run/0` to run tests.