mutastic explain

Everything known of one mutant, with its tests run. Its card when it's missed, or what became of it otherwise, then what the change is, its operator, how its id is made, where it is, and how the last run of every mutant, by run or next, went for it, from that run's mutation.json.

Usage

mutastic explain <id> [dir]

Inside a package, cargo mutastic explain runs the same command, with the same options.

mutastic explain mb2f8ae57
mutastic explain \
  mb2f8ae57 \
  fixtures/pricing

Output

On the pricing fixture, after a run. This is mutastic's own output, written from the CLI and checked against it on every build.

  ✗ MISSED  no test checks discount() at total == 100
    ┌─ src/lib.rs:26
    │
 25 │     pub fn discount(&self, total: u32) -> u32 {
 26 │         if total >= 100 {
    │                  ^^ >= changed to >
 27 │             return total / 10;
    │
    = mutant  - if total >= 100 {
              + if total > 100 {
    = note: every test calls discount() away from the boundary
            inputs seen: 50, 250 (none is 100)
            covered by tests::small_orders_pay_full_price, pricing::big_orders_get_ten_percent_off (all 2 covering tests still pass)
    = help: test discount() with total = 100 and assert the result

            // in mod tests
            #[test]
            fn discount_at_the_total_edge() {
                assert_eq!(Pricing::new().discount(100), 10); // today 10 · with this mutant 0
            }
            check today's value is the one you intend: the test pins what the code does now

    done when  mutastic verify mb2f8ae57 fixtures/pricing passes
    reproduce  mutastic run --only=mb2f8ae57 fixtures/pricing
    or ignore  mutastic ignore mb2f8ae57 --reason="<why>" fixtures/pricing

 About this mutant ───────────────────────────────────────────────
    = change    total >= 100 → (total) > (100)
                the code the switch puts in place of the original when this mutant is live
    = operator  mutastic/boundary: `>=` becomes `>`
                docs: https://docs.mutastic.io/rust/operators/conditions/#boundary
    = id        mb2f8ae57: `m` and the first 8 hex digits of its fingerprint, b2f8ae57ca6c48cb, a SHA-256 of the crate, function, operator, site and change
                no line number goes in, so the id stays the same when code above it moves
    = site      `total >= 100` in Pricing::discount, line 26, column 18
    = last run  missed: every covering test still passed

Exit status

0 whatever the mutant's result: it explains, it doesn't judge. Any command exits 2 when mutastic couldn't run: see exit codes.

Options

--workers=N

How many mutants run side by side; half the cores, from 1 to 4, unless set.

Command line	--workers=N

mutastic explain \
  mb2f8ae57 \
  --workers=2

--no-suggestions

Don't look for a test that catches each missed mutant, which runs the missed mutant's function outside the tests.

Command line	--no-suggestions

mutastic explain \
  mb2f8ae57 \
  --no-suggestions

--format=FORMAT

How the result is shown; full on a terminal, concise elsewhere, agent for coding agents; explain takes full and jsonl.

One of fullbriefconcisegroupedagentjsonl

Command line	--format=FORMAT
Environment	MUTASTIC_FORMAT, MUTASTIC_AGENT

mutastic explain \
  mb2f8ae57 \
  --format=jsonl

--vocabulary=WORDS

plain says caught and missed; classic says killed and survived.

One of plainclassic

Command line	--vocabulary=WORDS
Environment	MUTASTIC_VOCABULARY

mutastic explain \
  mb2f8ae57 \
  --vocabulary=classic

--color=WHEN

Colour: auto uses it on a terminal that wants it.

One of autoalwaysnever

Command line	--color=WHEN
Environment	NO_COLOR, FORCE_COLOR

mutastic explain \
  mb2f8ae57 \
  --color=never

--hyperlinks=WHEN

File locations as links a terminal can open: auto uses them on a terminal.

One of autoalwaysnever

Command line	--hyperlinks=WHEN

mutastic explain \
  mb2f8ae57 \
  --hyperlinks=never

--progress=STYLE

Progress on stderr: a bar on a terminal, counter lines in logs, none for agents.

One of autobarcounternone

Command line	--progress=STYLE

mutastic explain \
  mb2f8ae57 \
  --progress=counter

--edition=EDITION

Which edition runs; unless set, the build file in dir, or the nearest above it: Cargo.toml for rust, pom.xml, build.gradle or settings.gradle for java.

One of rustjava

Command line	--edition=EDITION

mutastic explain \
  mb2f8ae57 \
  --edition=rust