Helpers for defining test cases.

This module must be used in other modules as a way to configure and prepare them for testing.

When used, it accepts the following options:

• :async - configures tests in this module to run concurrently with tests in other modules. Tests in the same module never run concurrently (with the exception of tests run via the :parameterize option - see below). It should be enabled only if tests do not change any global state. Defaults to false.

• :group (since v1.18.0) - configures the group this module belongs to. Tests in the same group never run concurrently. Tests from different groups (or with no groups) can run concurrently when async: true is given. By default, this module belongs to no group (defaults to nil).

• :register - when false, does not register this module within ExUnit server. This means the module won't run when ExUnit suite runs.

• :parameterize (since v1.18.0) - a list of maps to parameterize tests. If both :async and :parameterize are given, the different parameters run concurrently. See the "Parameterized tests" section below for more information.

Examples

defmodule AssertionTest do
  # Use the module
  use ExUnit.Case, async: true

  # The "test" macro is imported by ExUnit.Case
  test "always pass" do
    assert true
  end
end

Context

All tests receive a context as an argument. The context is particularly useful for sharing information between callbacks and tests:

defmodule KVTest do
  use ExUnit.Case

  setup do
    {:ok, pid} = KV.start_link()
    {:ok, pid: pid}
  end

  test "stores key-value pairs", context do
    assert KV.put(context[:pid], :hello, :world) == :ok
    assert KV.get(context[:pid], :hello) == :world
  end
end

As the context is a map, it can be pattern matched on to extract information:

test "stores key-value pairs", %{pid: pid} = _context do
  assert KV.put(pid, :hello, :world) == :ok
  assert KV.get(pid, :hello) == :world
end

Tags

The context is used to pass information from the callbacks to the test. In order to pass information from the test to the callback, ExUnit provides tags.

By tagging a test, the tag value can be accessed in the context, allowing the developer to customize the test. Let's see an example:

defmodule FileTest do
  # Changing directory cannot be async
  use ExUnit.Case, async: false

  setup context do
    # Read the :cd tag value
    if cd = context[:cd] do
      prev_cd = File.cwd!()
      File.cd!(cd)
      on_exit(fn -> File.cd!(prev_cd) end)
    end

    :ok
  end

  @tag cd: "fixtures"
  test "reads UTF-8 fixtures" do
    File.read("README.md")
  end
end

In the example above, we have defined a tag called :cd that is read in the setup callback to configure the working directory the test is going to run on.

Tags are also very effective when used with case templates (ExUnit.CaseTemplate) allowing callbacks in the case template to customize the test behaviour.

Note a tag can be set in two different ways:

@tag key: value
@tag :key       # equivalent to setting @tag key: true

If a tag is given more than once, the last value wins.

Module and describe tags

A tag can be set for all tests in a module or describe block by setting @moduletag or @describetag inside each context respectively:

defmodule ApiTest do
  use ExUnit.Case
  @moduletag :external

  describe "makes calls to the right endpoint" do
    @describetag :endpoint

    # ...
  end
end

If you are setting a @moduletag or @describetag attribute, you must set them after your call to use ExUnit.Case otherwise you will see compilation errors.

If the same key is set via @tag, the @tag value has higher precedence.

The setup_all blocks only receive tags that are set using @moduletag.

Known tags

The following tags are set automatically by ExUnit and are therefore reserved:

• :async - if the test case is in async mode

• :file - the file on which the test was defined

• :line - the line on which the test was defined

• :module - the module on which the test was defined

• :registered - used for ExUnit.Case.register_attribute/3 values

• :test - the test name

• :test_group - the group the test belongs to

• :test_pid - the PID of the testing process

• :test_type - the test type used when printing test results. It can also be used for filtering. It is set by ExUnit to :test, :doctest, or the equivalent type given to register_test/6

• :describe - the describe block the test belongs to (if in a describe)

• :describe_line - the line the describe block begins on (if in a describe). It can be used to run all tests in the describe block given by line

• :doctest - the module or the file being doctested (if a doctest)

• :doctest_data - additional metadata about doctests stored in a map, such as the :end_line, available for reflection purposes (if a doctest)

• :doctest_line - the line the doctest was defined (if a doctest). It can be used to run a doctest defined at the given source line

The following tags customize how tests behave:

• :capture_log - see the "Log Capture" section below

• :skip - skips the test with the given reason

• :timeout - customizes the test timeout in milliseconds (defaults to 60_000). Accepts :infinity as a timeout value.

• :tmp_dir - (since v1.11.0) see the "Tmp Dir" section below

Parameterized tests

Sometimes you want to run the same tests but with different parameters. In ExUnit, it is possible to do so by passing a :parameterize key to ExUnit.Case. The value must be a list of maps which will be the parameters merged into the test context.

For example, Elixir has a module called Registry, which can have type :unique or :duplicate, and can control its concurrency factor using the :partitions option. If you have a number of tests that behave the same across all of those values, you can parameterize those tests with:

use ExUnit.Case,
  async: true,
  parameterize:
    for(kind <- [:unique, :duplicate],
        partitions <- [1, 8],
        do: %{kind: kind, partitions: partitions})

Then, in your tests, you can access the parameters as part of the context:

test "starts a registry", %{kind: kind, partitions: partitions} do
  ...
end

Use parameterized tests with care:

• Although parameterized tests run concurrently when async: true is also given, abuse of parameterized tests may make your test suite slower

• If you use parameterized tests and then find yourself adding conditionals in your tests to deal with different parameters, then parameterized tests may be the wrong solution to your problem. Consider creating separated tests and sharing logic between them using regular functions

Filters

Tags can also be used to identify specific tests, which can then be included or excluded using filters. The most common functionality is to exclude some particular tests from running, which can be done via ExUnit.configure/1:

# Exclude all external tests from running
ExUnit.configure(exclude: [external: true])

From now on, ExUnit will not run any test that has the :external option set to true. This behaviour can be reversed with the :include option which is usually passed through the command line:

$ mix test --include external:true

Run mix help test for more information on how to run filters via Mix.

Another use case for tags and filters is to exclude all tests that have a particular tag by default, regardless of its value, and include only a certain subset:

ExUnit.configure(exclude: :os, include: [os: :unix])

A given include/exclude filter can be given more than once:

ExUnit.configure(exclude: [os: :unix, os: :windows])

Keep in mind that all tests are included by default, so unless they are excluded first, the include option has no effect.

Log Capture

ExUnit can optionally suppress printing of log messages that are generated during a test. Log messages generated while running a test are captured and only if the test fails are they printed to aid with debugging.

You can opt into this behaviour for individual tests by tagging them with :capture_log or enable log capture for all tests in the ExUnit configuration:

ExUnit.start(capture_log: true)

This default can be overridden by @tag capture_log: false or @moduletag capture_log: false.

Since setup_all blocks don't belong to a specific test, log messages generated in them (or between tests) are never captured. If you want to suppress these messages as well, remove the console backend globally by setting:

config :logger, :default_handler, false

Tmp Dir

ExUnit automatically creates a temporary directory for tests tagged with :tmp_dir and puts the path to that directory into the test context. The directory is removed before being created to ensure we start with a blank slate.

The temporary directory path is unique (includes the test module and test name) and thus appropriate for running tests concurrently. You can customize the path further by setting the tag to a string, e.g.: tmp_dir: "my_path", which would make the final path to be: tmp/<module>/<test>/my_path.

Example:

defmodule MyTest do
  use ExUnit.Case, async: true

  @tag :tmp_dir
  test "with tmp_dir", %{tmp_dir: tmp_dir} do
    assert tmp_dir =~ "with tmp_dir"
    assert File.dir?(tmp_dir)
  end
end

As with other tags, :tmp_dir can also be set as @moduletag and @describetag.

Process Architecture

An ExUnit test case uses several processes when it runs. These are illustrated below.

sequenceDiagram
  participant runner as ExUnit Case
  runner->>runner: Run setup_all callbacks

  loop Each test
    create participant test as Test Process
    runner->>test: Spawn
    test->>test: Run setup callbacks
    test->>test: Run test
    destroy test
    test-xrunner: Exits
    runner->>runner: Run on_exit callbacks
  end

1. First, all ExUnit.Callbacks.setup_all/1 callbacks run in a single process, sequentially, in the order they were defined.

2. Then, a new process is spawned for the test itself. In this process, first all ExUnit.Callbacks.setup/1 callbacks run, in the order they were defined. Then, the test itself is executed.

3. After the test exits, a new process is spawned to run all ExUnit.Callbacks.on_exit/2, in the reverse order they were defined.