MutagenEx.MutationRunner (mutagen_ex v0.2.0)

Copy Markdown View Source

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.* or Mix.Tasks.Mutagen modules (see mutagen.decision.self_mutation_refused).
  • r4 — per-site test runs wrap ExUnit.run/0 in the timeout structure owned by MutagenEx.MutationRunner.MutationLoop. The timeout uses the two-phase cooperative-cancellation path documented in mutagen.decision.timeout_handling (trappable :shutdown first, brutal_kill only as escalation). The runner classifies a deadline hit as :timeout unless fail-fast already recorded a failure. The following site carries tainted_predecessors: true either way. Before restore, the runner calls :code.purge/1 on 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_error does not count toward the kill-rate denominator.
  • r6 — after every per-site run, the original module is restored via :code.load_binary/3 from a per-run ETS snapshot owned by MutagenEx.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 of run/1 (created at the start, deleted in the after clause). On restore failure the runner aborts with {:error, :unrecoverable_restore_failure, ...}. See mutagen.decision.per_run_beam_cache and mutagen.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/1 settle) 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 via with_restore/4, mirroring MutagenEx.CoverageRunner's with_cover_lifecycle/2.
  • r7 — pre/post state snapshots (Process.registered/0, :ets.all/0, :persistent_term.get/0). Growth flags tainted_predecessors: true for subsequent results and emits a warning naming the new entities (best-effort — Process.registered/0 is the named-process surface; anonymous leaks are documented as a known caveat per mutagen.decision.timeout_handling).
  • r8 — modules whose AST contains use SomeModule get a state_drift_warning listing the used modules.
  • r9 — stderr is captured via ExUnit.CaptureIO and attached to each result's warnings field.
  • r10 — test files are loaded once (the orchestrator's responsibility upstream); per-site cycles re-register modules via ExUnit.Server.add_module/2 from MutationLoop.
  • 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/3 against 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}} from MutagenEx.AstCache.load/1.
  • :sites — [%MutagenEx.MutationEnumerator.Site{}, ...].
  • :scope_records — [%MutagenEx.ScopeResolver.Scope{}], used for r8 (state-drift detection over use SomeModule in 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. Default true. Stops executing cited tests after the first failure. Use false for a full suite run.
  • :ex_unit — module implementing MutagenEx.Test.ExUnitFacade. Default MutagenEx.Test.ExUnit. Passed through to MutationLoop.
  • :ex_unit_server — module implementing MutagenEx.Test.ExUnitServerFacade. Default MutagenEx.Test.ExUnitServer. Passed through to MutationLoop.
  • :capture_io — module implementing MutagenEx.Test.CaptureIoFacade. Default MutagenEx.Test.CaptureIo. Used by both the swap-compile capture around Code.compile_quoted/2 and the per-site MutationLoop stderr capture.
  • :compiler — module implementing MutagenEx.Test.CompilerFacade, OR a legacy {module, function} tuple for back-compat with the pre-bw mutagen-wrd.24 stubs. Default MutagenEx.Test.Compiler. The legacy tuple shape is honored so existing test stubs that pass {CompilerStub, :compile_quoted} keep working.
  • :code_server — module implementing MutagenEx.Test.CodeServerFacade. Default MutagenEx.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 :compiler seam.
  • :beam_cache_table — :ets.tab(). The per-run snapshot table. Callers DO NOT pass this; run/1 creates the table itself via MutagenEx.BeamCache.new/0 at the start of execute/2 and deletes it in the after clause. The field is documented here so internal helpers that read cfg.beam_cache_table have a named contract. Tests that bypass execute/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. Default 100. Set to 0 in tests that need to exercise the brutal-only path. Passed through to MutationLoop.
  • :code_purge — (module -> any). Test seam for the post- :timeout Code.Server settle pass. Default &:code.purge/1.
  • :max_concurrency — pos_integer | nil. Cap on the number of per-site tasks Task.Supervisor.async_stream_nolink/4 will spawn in parallel. nil resolves to 1 (fully-serial, v1.0-equivalent execution) — this is also the Mix-task default when the user does not pass --max-concurrency. N > 1 is the explicit opt-in path for callers with collision-free input. Regardless of value, results are collected in input order (the async_stream :ordered default) 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. See mutagen.mutation_pipeline.r15.

  • :task_sup — atom | pid. The Task.Supervisor the per-site tasks run under. Default MutagenEx.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

compile_error_entry()

@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).

error_reason()

@type error_reason() ::
  :self_mutation_refused | :unrecoverable_restore_failure | :invalid_input

Reasons the runner can abort with.

ok_result()

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

site_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

run(input)

@spec run(map()) :: {:ok, ok_result()} | {:error, error_reason(), map()}

Runs the mutation phase. See module doc for input shape.