ExUnit v1.5.1 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()

state()

The error state returned by ExUnit.Test and ExUnit.TestCase

Functions

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

API used to run the tests. It is invoked automatically if ExUnit is started via ExUnit.start/1

start(options \\ [])

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)

Link to this section Types

failed()

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

state()

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

The error state returned by ExUnit.Test and ExUnit.TestCase

Link to this section Functions

configuration()

Returns ExUnit configuration.

configure(options)

Configures ExUnit.

Options

ExUnit supports the following options:

:assert_receive_timeout - the timeout to be used on assert_receive calls, defaults to 100 milliseconds;
: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;
:case_load_timeout - the timeout to be used when loading a test case, defaults to 60_000 milliseconds;
:colors - a keyword list of colors to be used by some formatters. The only option so far is [enabled: boolean] which defaults to IO.ANSI.enabled?/0;
:exclude - specifies which tests are run by skipping tests that match the filter;
: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;
:max_cases - maximum number of cases to run in parallel. It defaults to System.schedulers_online * 2 to optimize both CPU-bound and IO-bound tests;
:refute_receive_timeout - the timeout to be used on refute_receive calls, defaults to 100 milliseconds;
:seed - an integer seed value to randomize the test suite;
:stacktrace_depth - configures the stacktrace depth to be used on formatting and reporters, defaults to 20;
:timeout - sets the timeout for the tests, defaults to 60_000 milliseconds;
: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.

plural_rule(word)

plural_rule(binary()) :: binary()

Returns the pluralization for word.

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

plural_rule(word, pluralization)

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

Registers a pluralization for word.

If one is already registered, it is replaced.

run()

API used to run the tests. It is invoked automatically if ExUnit is started via ExUnit.start/1.

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

start(options \\ [])

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 :autorun to false.