# `MutagenEx.TestSelector`
[🔗](https://github.com/iautom8things/mutagen_ex/blob/v0.2.0/lib/mutagen_ex/test_selector.ex#L1)

Resolves user-supplied `--tests` targets into the `{include, exclude, files}`
shape ExUnit's filter system expects.

Contract: [`mutagen.test_selection`](https://github.com/iautom8things/mutagen_ex/blob/main/.spec/specs/test_selection.spec.md).

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]`.

# `error_reason`

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

# `option`

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

Options accepted by `resolve/2`.

# `options`

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

# `target`

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

# `merge_helper_filters`

```elixir
@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.

# `resolve`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
