Per-mutation execution: swap → run → classify → restore. Aggregates the per-site outcomes into a result block the JSON reporter (S6) can serialise.
Contract: mutagen.mutation_pipeline
r3-r11.
Invariants summary
- r3 — refuses to mutate
MutagenEx.*orMix.Tasks.Mutagenmodules (seemutagen.decision.self_mutation_refused). - r4 — per-site test runs wrap
ExUnit.run/0in the timeout structure owned byMutagenEx.MutationRunner.MutationLoop. The timeout uses the two-phase cooperative-cancellation path documented inmutagen.decision.timeout_handling(trappable:shutdownfirst, brutal_kill only as escalation). The runner classifies a deadline hit as:timeoutunless fail-fast already recorded a failure. The following site carriestainted_predecessors: trueeither way. Before restore, the runner calls:code.purge/1on the site's scoped modules to release any orphaned Code.Server load lock left by a brutal-killed task — the per-mutation hardening that bw mutagen-wrd.13 fixed. - r5 — exactly five outcomes:
:killed,:survived,:timeout,:compile_error,:error.:compile_errordoes not count toward the kill-rate denominator. - r6 — after every per-site run, the original module is restored
via
:code.load_binary/3from a per-run ETS snapshot owned byMutagenEx.BeamCache. The snapshot is taken once before the per-site loop dispatches, in a serial pre-pass over every scoped module — closing the TOCTOU window a per-site snapshot would open under--max-concurrency > 1. The cache lives only for the duration ofrun/1(created at the start, deleted in theafterclause). On restore failure the runner aborts with{:error, :unrecoverable_restore_failure, ...}. Seemutagen.decision.per_run_beam_cacheandmutagen.decision.code_server_facade. - r12 — a raise, throw, or exit propagating out of the
loaded-mutation window (from successful compile of the mutated
AST through the test run and
:code.purge/1settle) triggers restore before re-propagation. The original kind/value/stacktrace surfaces to the caller; restore failure during such propagation is best-effort and never masks the original cause. Implemented viawith_restore/4, mirroringMutagenEx.CoverageRunner'swith_cover_lifecycle/2. - r7 — pre/post state snapshots
(
Process.registered/0,:ets.all/0,:persistent_term.get/0). Growth flagstainted_predecessors: truefor subsequent results and emits a warning naming the new entities (best-effort —Process.registered/0is the named-process surface; anonymous leaks are documented as a known caveat permutagen.decision.timeout_handling). - r8 — modules whose AST contains
use SomeModuleget astate_drift_warninglisting the used modules. - r9 — stderr is captured via
ExUnit.CaptureIOand attached to each result'swarningsfield. - r10 — test files are loaded once (the orchestrator's
responsibility upstream); per-site cycles re-register modules via
ExUnit.Server.add_module/2fromMutationLoop. - r11 — no file on disk is modified by the runner. All AST
compilation is in-memory via
Code.compile_quoted/2; restore is an in-memory binary swap via:code.load_binary/3against the per-run BeamCache snapshot (no disk writes either).
Input shape
run/1 takes a map:
:seed—non_neg_integer. Forwarded to ExUnit.configure for the duration of the runner.:timeout_ms—pos_integer. Per-site wall-clock budget.:test_filter—%MutagenEx.TestSelector.TestFilter{}.:ast_cache—%{file => {ast, source_text}}fromMutagenEx.AstCache.load/1.:sites—[%MutagenEx.MutationEnumerator.Site{}, ...].:scope_records—[%MutagenEx.ScopeResolver.Scope{}], used for r8 (state-drift detection overuse SomeModulein scoped modules).:test_modules—[{module, exunit_module_cfg}]to re-register between per-site runs. Built by the orchestrator from the test filter once before the runner starts.
Optional:
:fail_fast—boolean. Defaulttrue. Stops executing cited tests after the first failure. Usefalsefor a full suite run.:ex_unit— module implementingMutagenEx.Test.ExUnitFacade. DefaultMutagenEx.Test.ExUnit. Passed through toMutationLoop.:ex_unit_server— module implementingMutagenEx.Test.ExUnitServerFacade. DefaultMutagenEx.Test.ExUnitServer. Passed through toMutationLoop.:capture_io— module implementingMutagenEx.Test.CaptureIoFacade. DefaultMutagenEx.Test.CaptureIo. Used by both the swap-compile capture aroundCode.compile_quoted/2and the per-siteMutationLoopstderr capture.:compiler— module implementingMutagenEx.Test.CompilerFacade, OR a legacy{module, function}tuple for back-compat with the pre-bw mutagen-wrd.24 stubs. DefaultMutagenEx.Test.Compiler. The legacy tuple shape is honored so existing test stubs that pass{CompilerStub, :compile_quoted}keep working.:code_server— module implementingMutagenEx.Test.CodeServerFacade. DefaultMutagenEx.Test.CodeServer. The restore path uses this facade to call:code.get_object_code/1(snapshot pre-pass) and:code.load_binary/3(per-site restore). Tests inject a stub that records calls and returns canned binaries; production callers leave the default. Mirrors the:compilerseam.:beam_cache_table—:ets.tab(). The per-run snapshot table. Callers DO NOT pass this;run/1creates the table itself viaMutagenEx.BeamCache.new/0at the start ofexecute/2and deletes it in theafterclause. The field is documented here so internal helpers that readcfg.beam_cache_tablehave a named contract. Tests that bypassexecute/2(and thread a hand-rolled cfg into deeper helpers) must populate this themselves.:cancel_grace_ms—non_neg_integer. Grace window the cooperative-cancellation phase waits before escalating to brutal_kill on a timeout. Default100. Set to0in tests that need to exercise the brutal-only path. Passed through toMutationLoop.:code_purge—(module -> any). Test seam for the post-:timeoutCode.Server settle pass. Default&:code.purge/1.:max_concurrency—pos_integer | nil. Cap on the number of per-site tasksTask.Supervisor.async_stream_nolink/4will spawn in parallel.nilresolves to1(fully-serial, v1.0-equivalent execution) — this is also the Mix-task default when the user does not pass--max-concurrency.N > 1is the explicit opt-in path for callers with collision-free input. Regardless of value, results are collected in input order (theasync_stream:ordereddefault) so the JSON document is byte-identical to the serial-equivalent run on deterministic scopes — taint, warnings, and per-site classification all fold sequentially over the ordered result list. Seemutagen.mutation_pipeline.r15.:task_sup—atom | pid. TheTask.Supervisorthe per-site tasks run under. DefaultMutagenEx.TaskSup. Tests can pass a one-off supervisor pid for isolation.:on_site_completed—(result_or_compile_error -> :ok). Called once per site as the result becomes available (in input order), before the runner accumulates it. This is the streaming-NDJSON seam: the Mix task wires this to emit one wire-shape JSON line per site. The runner only invokes it; it does no I/O itself (mutagen.json_schema.r11).
Output shape
{:ok, %{results: [...], compile_errors: [...], state_drift_warning: %{...}, warnings: [...]}}
on full pipeline. {:error, reason, details} on :self_mutation_refused
or :unrecoverable_restore_failure.
Summary
Types
Compile-error record (sites whose mutated AST refused to compile).
Reasons the runner can abort with.
Aggregated runner result.
Successful per-site result. :compile_error outcomes live in compile_errors instead.
Functions
Runs the mutation phase. See module doc for input shape.
Types
@type compile_error_entry() :: %{ id: String.t(), file: String.t(), function: String.t() | nil, line: pos_integer(), column: pos_integer(), mutator: atom(), message: String.t(), exception: module() | nil }
Compile-error record (sites whose mutated AST refused to compile).
@type error_reason() ::
:self_mutation_refused | :unrecoverable_restore_failure | :invalid_input
Reasons the runner can abort with.
@type ok_result() :: %{ results: [site_result()], compile_errors: [compile_error_entry()], dropped: [ %{ id: String.t(), path: Path.t(), reason: :ast_cache_miss | :site_node_not_found } ], tainted: boolean(), truncated: boolean(), state_drift_warning: %{optional(module()) => [atom()]}, warnings: [String.t() | {atom(), term()} | {:host_names, atom(), [term()]}] }
Aggregated runner result.
@type site_result() :: %{ id: String.t(), function: String.t() | nil, file: String.t(), line: pos_integer(), column: pos_integer(), mutator: atom(), original_ast: Macro.t(), mutated_ast: Macro.t(), status: :killed | :survived | :timeout | :error, tainted_predecessors: boolean(), warnings: [String.t() | {atom(), String.t()}], end_line: pos_integer() | nil, end_column: pos_integer() | nil, source_span: {non_neg_integer(), pos_integer()} | nil, source_line: pos_integer() | nil, source_text: String.t() | nil }
Successful per-site result. :compile_error outcomes live in compile_errors instead.
Functions
@spec run(map()) :: {:ok, ok_result()} | {:error, error_reason(), map()}
Runs the mutation phase. See module doc for input shape.