MutagenEx.TestSelector (mutagen_ex v0.2.0)

Copy Markdown View Source

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 what ExUnit's path-parse helper produces for a path with no :line. The earlier (broken) shape was exclude: [:test], which paired with an empty include silently excluded every test (mutagen-wrd.11 — ExUnit's filter eval admits a test only when an include tag matches or no exclude tag matches; with include: [] and exclude: [:test] neither holds, so every test fails the filter).
  • file:line and tag: targets — exclude: [:test]. The non-empty include (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

error_reason()

@type error_reason() ::
  :no_tests_match | :invalid_target | :invalid_line | :file_not_found

option()

@type option() :: {:test_root, String.t()} | {:test_paths, [String.t()]}

Options accepted by resolve/2.

options()

@type options() :: [option()]

target()

@type target() :: String.t()

Functions

merge_helper_filters(filter, helper, literal_tags \\ MapSet.new())

Applies helper filters while preserving restrictive tag and line targets.

resolve(target, opts \\ [])

@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 for tag:NAME resolution. Defaults to "test". Exposed so the test suite can point at fixture trees without polluting the real test/ 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.