ExUnit.Filters — ExUnit v1.16.3

Search documentation of ExUnit

# View Source ExUnit.Filters (ExUnit v1.16.3)

Conveniences for parsing and evaluating filters.

# Summary

## Types

ex_unit_opts()
location()
t()

## Functions

eval(include, exclude, tags, collection)

Evaluates the `include` and `exclude` filters against the given `tags` to determine if tests should be skipped or excluded.

failure_info(manifest_file)

Returns a tuple containing useful information about test failures from the manifest. The tuple contains

normalize(include, exclude)

Normalizes `include` and `exclude` filters to remove duplicates and keep precedence.

parse(filters)

Parses the given filters, as one would receive from the command line.

parse_path(file_path)

Parses filters out of a path.

parse_paths(file_paths)

Like `parse_path/1` but for multiple paths.

# Types

Link to this type

# ex_unit_opts()

View Source

    @type ex_unit_opts() :: [exclude: [:test], include: [location(), ...]] | []

Link to this type

# location()

View Source

    @type location() :: {:location, {String.t(), pos_integer() | [pos_integer(), ...]}}

Link to this type

# t()

View Source

    @type t() :: [{atom(), Regex.t() | String.Chars.t()} | atom()]

# Functions

Link to this function

# eval(include, exclude, tags, collection)

View Source

    @spec eval(t(), t(), map(), [ExUnit.Test.t()]) ::
      :ok | {:excluded, String.t()} | {:skipped, String.t()}

Evaluates the `include` and `exclude` filters against the given `tags` to determine if tests should be skipped or excluded.

Some filters, like `:line`, may require the whole test `collection` to find the closest line, that's why it must also be passed as an argument.

Filters can either be a regular expression or any data structure that implements the `String.Chars` protocol, which is invoked before comparing the filter with the `:tag` value.

## Precedence

Tests are first excluded, then included, and then skipped (if any left).

If a `:skip` tag is found in `tags`, `{:skipped, message}` is returned if the test has been left after the `exclude` and `include` filters. Otherwise `{:exclude, message}` is returned.

The only exception to this rule is that `:skip` is found in the `include` filter, `:ok` is returned regardless of whether the test was excluded or not.

## Examples

    iex> ExUnit.Filters.eval([foo: "bar"], [:foo], %{foo: "bar"}, [])
    :ok

    iex> ExUnit.Filters.eval([foo: "bar"], [:foo], %{foo: "baz"}, [])
    {:excluded, "due to foo filter"}

Link to this function

# failure_info(manifest_file)

View Source

    @spec failure_info(Path.t()) :: {MapSet.t(Path.t()), MapSet.t(ExUnit.test_id())}

Returns a tuple containing useful information about test failures from the manifest. The tuple contains:

- A set of files that contain tests that failed the last time they ran. The paths are absolute paths.
- A set of test IDs that failed the last time they ran

Link to this function

# normalize(include, exclude)

View Source

    @spec normalize(t() | nil, t() | nil) :: {t(), t()}

Normalizes `include` and `exclude` filters to remove duplicates and keep precedence.

## Examples

    iex> ExUnit.Filters.normalize(nil, nil)
    {[], []}

    iex> ExUnit.Filters.normalize([:foo, :bar, :bar], [:foo, :baz])
    {[:foo, :bar], [:baz]}

    iex> ExUnit.Filters.normalize([foo: "true"], [:foo])
    {[foo: "true"], [:foo]}

    iex> ExUnit.Filters.normalize([:foo], [foo: "true"])
    {[:foo], []}

    iex> ExUnit.Filters.normalize([foo: "true"], [foo: true])
    {[foo: "true"], []}

    iex> ExUnit.Filters.normalize([foo: true], [foo: "true"])
    {[foo: true], []}

    iex> ExUnit.Filters.normalize([foo: 1, foo: 1, foo: 2], [])
    {[foo: 1, foo: 2], []}

    iex> ExUnit.Filters.normalize([], [foo: 1, foo: 1, foo: 2])
    {[], [foo: 1, foo: 2]}

Link to this function

# parse(filters)

View Source

    @spec parse([String.t()]) :: t()

Parses the given filters, as one would receive from the command line.

## Examples

    iex> ExUnit.Filters.parse(["foo:bar", "baz", "line:9", "bool:true"])
    [{:foo, "bar"}, :baz, {:line, 9}, {:bool, "true"}]

Link to this function

# parse_path(file_path)

View Source

    @spec parse_path(String.t()) :: {String.t(), ex_unit_opts()}

Parses filters out of a path.

Determines whether a given file path (supplied to ExUnit/Mix as arguments on the command line) includes a line number filter, and if so returns the appropriate ExUnit configuration options.

Link to this function

# parse_paths(file_paths)

View Source

    @spec parse_paths([String.t()]) :: {[String.t()], ex_unit_opts()}

Like `parse_path/1` but for multiple paths.

ExUnit filter options are combined.