Mutare Plug

Custom Mutare mutators for the Plug request surface — the Plug.Conn calls a plug, router, or controller action performs on the conn.

A plug returns a transformed conn, so its whole contract is which conn-transforming call ran — the status/header/session/cookie it set, the body it sent, whether it halted. These are exactly the calls a suite tends to under-assert: a test that checks "something happened" but not which transformation leaves a gap. mutare_plug turns each such gap into a located Mutare survivor.

The families

Mutare.Plug.all/0 returns six mutator families:

Each family matches its call written directly (Plug.Conn.halt(conn)), aliased, or bare-imported (halt(conn), the form use Plug.Builder / use Plug.Router — or Phoenix's use MyAppWeb, :controller — produces). Integer statuses (put_status(conn, 200)) are left to Mutare's built-in literal family; :http_status only swaps atom statuses.

Usage

mutare_plug rides on the Mutare engine, so add both as :dev/:test dependencies:

# mix.exs
defp deps do
  [
    {:mutare, "~> 0.1", only: [:dev, :test], runtime: false},
    {:mutare_plug, "~> 0.1", only: [:dev, :test], runtime: false}
  ]
end

Then list the families in .mutare.exs. Setting :mutatorsreplaces Mutare's default set, so include the :builtins family to keep the built-ins on:

# .mutare.exs
[mutators: [:builtins] ++ Mutare.Plug.all()]

Run it the usual way:

mix mutare

A Phoenix app adds the companion mutare_phoenix on top for the Phoenix.Controller surface (see "Scope").

Configuring a family

:http_status's swap table is tunable. Give the family {module, opts} with a :swaps map — a status you list replaces its built-in siblings, an empty list disables it, and any status you omit keeps its built-in siblings. Configuring a family means listing it yourself, so expand Mutare.Plug.all/0 into its members and replace that one entry:

# .mutare.exs — narrow :ok to one sibling, stop mutating :no_content, add a teapot
[
  mutators: [
    :builtins,
    Mutare.Plug.Halt,
    {Mutare.Plug.Status, swaps: %{ok: [:created], no_content: [], im_a_teapot: [:bad_request]}},
    Mutare.Plug.Session,
    Mutare.Plug.Header,
    Mutare.Plug.Cookie,
    Mutare.Plug.Body
  ]
]

Configured siblings must be valid Plug.Conn.Status reason atoms — trusted, not checked: a sibling that isn't a real status produces a crashing mutant rather than the built-in table's valid-but-wrong swap. See Mutare.Plug.Status for the full table.

Why not the built-in atom mutators?

In a status position, Mutare's built-in atom swaps (:ok → :error / :mutare) produce a value that crashes — an uninformative kill that tells you nothing about test quality. :http_status swaps to valid siblings, so a survivor means a genuine missing assertion rather than a crash, and Mutare's overlap pruning drops the redundant crashing leaves at the same range. :resp_body works the same way for a literal body: its whole-call blank covers the string node, so the built-in string family's sentinel leaves there are pruned automatically and one clean "is the body read?" mutant remains.

Example

examples/demo is a standalone mini-project — an auth plug and a few request handlers over a tiny Plug.Conn stand-in — with deliberate test gaps that surface survivors in the halt/status/body families. From the repo root:

mix compile
mix mutare examples/demo

Scope

This package owns the Plug.Conn surface only. The Phoenix.Controller surface (redirect/2's status, and the defensive :skip routing for Phoenix's compile-time macros) is the companion mutare_phoenix, which depends on this package the way phoenix depends on plug; LiveView is mutare_phoenix_live_view on top of that.

License

MIT — see LICENSE.