yak(mutation-testing-with-muex-blogex-pure-app-code-1341): mutation testing with muex (blogex + pure app code)

app/mix.exs

@@ -83,6 +83,7 @@ defmodule Firehose.MixProject do
        branch: "main"},
       {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
       {:ex_crap, "~> 0.1.1", only: [:dev, :test], runtime: false},
+      {:muex, "~> 0.12", only: [:dev, :test], runtime: false},
       {:sobelow, "~> 0.16", only: [:dev, :test], runtime: false}
     ]
   end
@@ -93,6 +94,14 @@ defmodule Firehose.MixProject do
   #     $ mix setup
   #
   # See the documentation for `Mix` for more info on aliases.
+  #
+  # `mutate` / `mutate.fast` are a sensor, not a gate: they are deliberately
+  # absent from Makefile's VERIFY_SENSORS and always pass `--fail-at 0`, so a
+  # survivor is reported rather than fatal. The scope lives in the plain-text
+  # files beside this one; the aliases read them at run time, so the text file
+  # stays the single source of truth. Both are empty today because the app's
+  # candidate modules are only tested through the database-backed DataCase;
+  # an empty scope raises instead of silently running over nothing.
   defp aliases do
     [
       setup: ["deps.get", "ecto.setup", "assets.setup", "assets.build"],
@@ -106,10 +115,65 @@ defmodule Firehose.MixProject do
         "esbuild firehose --minify",
         "phx.digest"
       ],
-      precommit: ["compile --warning-as-errors", "deps.unlock --unused", "format", "test"]
+      precommit: ["compile --warning-as-errors", "deps.unlock --unused", "format", "test"],
+      mutate: &mutate/1,
+      "mutate.fast": &mutate_fast/1
     ]
   end
 
+  # No macro/`use` mutators: the web layer (where the DSLs live) is out of
+  # scope, and an empty scope never reaches muex at all. Spellings are muex
+  # 0.12's CLI names.
+  @mutation_mutators "arithmetic,boolean,comparison,conditional,function_call,literal,return_value"
+
+  defp mutate(args), do: run_mutation("mutation_scope.txt", args)
+
+  defp mutate_fast(args), do: run_mutation("mutation_scope_fast.txt", args)
+
+  defp run_mutation(scope_file, args) do
+    Mix.Task.run("muex", mutation_args(scope_file, args))
+  end
+
+  @doc false
+  def mutation_args(scope_file, extra_args \\ []) do
+    files = read_mutation_scope(scope_file)
+
+    # `--fail-at 0` comes first so an ad-hoc override cannot turn the sensor
+    # into a gate. Extra args come before our defaults, and OptionParser keeps
+    # the first value, so `mix mutate --files lib/foo.ex` targets one file.
+    ["--fail-at", "0"] ++
+      extra_args ++
+      ["--files", Enum.join(files, ","), "--mutators", @mutation_mutators]
+  end
+
+  @doc false
+  def read_mutation_scope(scope_file) do
+    path = Path.expand(scope_file, Path.dirname(Mix.Project.project_file()))
+
+    files =
+      case File.read(path) do
+        {:ok, contents} ->
+          contents
+          |> String.split("\n", trim: true)
+          |> Enum.map(&String.trim/1)
+          |> Enum.reject(&(&1 == ""))
+
+        {:error, reason} ->
+          Mix.raise(
+            "mutation scope #{scope_file} is unreadable (#{:file.format_error(reason)}); " <>
+              "refusing to run the mutation sensor over an unknown scope"
+          )
+      end
+
+    if files == [] do
+      Mix.raise(
+        "mutation scope #{scope_file} is empty; refusing to run the mutation sensor over nothing"
+      )
+    end
+
+    files
+  end
+
   # The coverage floor the Lens pass enforces (`make verify` -> `make coverage`
   # in app/). Rule: the threshold is a FLOOR. Raise it as behavior-test yaks
   # land; never lower it. A drop means the change (or an exclusion) is wrong,