# ExUnit v1.10.3 ExUnit.Filters View Source

Conveniences for parsing and evaluating filters.

# Link to this section Summary

## Types

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)

Parses filters out of a path.

# Link to this section Types

Link to this type

# t()

View Source

## Specs

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

# Link to this section Functions

Link to this function

# eval(include, exclude, tags, collection)

View Source

## Specs

    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

## Specs

    failure_info(Path.t()) ::
      {MapSet.t(Path.t()), MapSet.t(ExUnit.FailuresManifest.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

## Specs

    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

## Specs

    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)

View Source

## Specs

    parse_path(String.t()) :: {String.t(), Keyword.t()}

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.