Resolves user-supplied --tests targets into the {include, exclude, files}
shape ExUnit's filter system expects.
Contract: mutagen.test_selection.
Three target shapes are recognised:
- A whole test file:
test/foo_test.exs - A specific test inside a file:
test/foo_test.exs:42 - A tag:
tag:integration
Tag resolution walks test/**/*_test.exs via Code.string_to_quoted/2. It
does not load the test modules — loading them would trip the state
hygiene contract carried by mutagen.mutation_pipeline. The selector
therefore remains usable from any process without ExUnit being running.
Atom safety (mutagen.test_selection.r7)
Tag resolution never calls String.to_atom/1 on the user-supplied
tag:NAME. Instead it walks the test corpus and compares NAME (a
string) against Atom.to_string/1 of each @tag :ATOM literal found in
the parsed AST; the matched atom that flows into include: is the
AST-derived one. For a tag with no matching @tag anywhere, the walk
produces zero matches and the selector returns :no_tests_match — with
:erlang.system_info(:atom_count) unchanged across N invocations with
N distinct never-registered names. The mutagen-wrd.20 bound: CI loops
like mix mutagen --tests tag:$(uuidgen) cannot grow the atom table
through this path (and the upstream mutagen.cli.r10 charset gate
rejects most adversarial inputs before they even reach here).
A target that resolves to zero matching tests (e.g. tag:unused with no
matching @tag :unused anywhere, or a :line that points outside every
test block in the named file) returns a structured {:error, ...} tuple
rather than an empty filter.
Return shape
Successful resolution returns {:ok, %TestFilter{include, exclude, files}}.
Multiple targets compose by union: files and include are the
deduplicated union of each target's contribution. exclude differs by
target shape:
- bare-file targets (
<path>_test.exs) —exclude: []. The filter degenerates to "load these files and run everything," matching whatExUnit's path-parse helperproduces for a path with no:line. The earlier (broken) shape wasexclude: [:test], which paired with an emptyincludesilently excluded every test (mutagen-wrd.11 — ExUnit's filter eval admits a test only when anincludetag matches or noexcludetag matches; withinclude: []andexclude: [:test]neither holds, so every test fails the filter). file:lineandtag:targets —exclude: [:test]. The non-emptyinclude(a{:location, …}or a tag atom) supplies the admit side;[:test]makes the filter restrictive by excluding everything else.
Union (r6): if any contributor is a bare-file target, the merged
exclude is [] (the bare-file is admitting all its tests; tag-style
restriction would re-suppress them). Otherwise the merged exclude
stays [:test].
Summary
Functions
Applies helper filters while preserving restrictive tag and line targets.
Resolves one or more --tests targets to a single TestFilter.
Types
Functions
@spec merge_helper_filters( MutagenEx.TestSelector.TestFilter.t(), keyword(), MapSet.t() ) :: MutagenEx.TestSelector.TestFilter.t()
Applies helper filters while preserving restrictive tag and line targets.
@spec resolve(target() | [target()], options()) :: {:ok, MutagenEx.TestSelector.TestFilter.t()} | {:error, %{reason: error_reason(), target: target()}}
Resolves one or more --tests targets to a single TestFilter.
Options
:test_root— directory to walk fortag:NAMEresolution. Defaults to"test". Exposed so the test suite can point at fixture trees without polluting the realtest/directory.
Targets compose by union; duplicates collapse. If any target fails to resolve (unknown shape, no matching tests, file not found), the first failure is returned and no filter is produced.