# `Mutare`
[🔗](https://github.com/foxbenjaminfox/mutare/blob/v0.2.1/lib/mutare.ex#L1)

Mutare is a mutation testing system for Elixir, that mutates the source you actually write, and compiles once.

The whole project is downstream of one invariant: compile once. Mutare rewrites a project's source into a *metamutant* — a single program that embeds every mutant behind a `:persistent_term` runtime switch — compiles it once, then runs the suite once per mutant, flipping that switch through two environment variables: `MUTARE_MUTANT_NAMESPACE` names the mutant's file and `MUTARE_ACTIVE_MUTANT` its id within that file.

On top of that, the runner adds coverage-guided test selection, compile-poison recovery, parallel execution, timeouts, ignore annotations, and changed-file scoping via `--since`.

Most users drive Mutare through the `mix mutare` task; `run/2` is the programmatic entry point and `transform_string/2` exposes the source rewrite on its own. See `Mutare.Runner` for the run flow and `Mutare.Mutator` for writing your own mutators.

# `run`

Run mutation testing against the project at `root`, returning
`{:ok, %Mutare.Run{}}` on success. See `Mutare.Runner.run/2`.

# `transform_string`

Transform a source string into a metamutant and public mutant descriptions.

    iex> source = "defmodule Calculator do\n  def add(a, b), do: a + b\nend\n"
    iex> result = Mutare.transform_string(source, mutators: [:arithmetic])
    iex> [site] = result.mutants
    iex> {site.id, site.mutator, site.original_code, site.mutated_code, result.next_id}
    {1, :arithmetic, "a + b", "a - b", 2}

---

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