#turtles

#Install

#Stable — Mooncakes

moon install f4ah6o/turtles/cmd/turtles@0.4.7

#Development — GitHub

moon install https://github.com/gpui-mbt/turtles.mbt.git cmd/turtles --branch main

moon install https://github.com/gpui-mbt/turtles.mbt.git cmd/turtles --tag v0.4.7

#From a local clone

moon install ./cmd/turtles

#First run in 30 seconds

turtles --version          # turtles 0.4.7 for this source release
turtles --help

cd path/to/your-moonbit-module
turtles --dir .            # or: turtles --list to preview the mutation set

#Typical local usage

turtles --dir .                    # run all discovered mutants
turtles --dir . --list             # preview mutations without running tests
turtles --dir . --file src/parser  # only mutate paths containing TEXT
turtles --dir . --target native     # run only what moon compiles for native
turtles --dir . --target js --list  # preview the js-active mutation set
turtles --dir . --timeout 120      # per-command timeout in seconds (default 60)
turtles --dir . --json report.json # machine-readable report (schema 3)
turtles --dir . --iterate          # reuse KILLED/UNVIABLE outcomes from the last run
turtles --dir . --affected         # run only tests that can observe each mutant
turtles --dir . --emit-regressions # write regression-test templates for property kills
turtles --dir . --emit-properties  # write property-test skeletons for survivors
turtles --dir . --pbt-witness      # differential QuickCheck witness for survivors
turtles --dir . --pbt-amplify 4    # re-run survivor properties with 4x budget
turtles --dir . --timeout-multiplier 3   # per-phase timeout = 3x the measured baseline (min 10s)

#Parallel execution

turtles --dir . --jobs 4

#CI usage

moon install f4ah6o/turtles/cmd/turtles@0.4.7
turtles --dir . --fail-under 80 --json turtles-report.json

turtles --dir . --fail-under 80

• score >= threshold → exit 0, even if survivors exist.
• score < threshold → exit 1.
• Setup or baseline failures → exit 2 regardless of thresholds.
• Without --fail-under, the previous rule applies: exit 1 on any SURVIVED or TIMEOUT mutant.

#Mutation score semantics

score = killed / viable * 100     where viable = killed + survived + timeout

• UNVIABLE mutants (which fail moon check) are excluded from the score entirely.
• Target-inactive mutants (files the selected --target does not compile) are excluded too — they are never classified.
• TIMEOUT mutants count as not killed — a mutant that makes your tests hang drags the score down instead of being silently forgiven.
• An empty mutation set scores 100.

#Reading results

• comparisons: == ↔ !=, > → <, < → >, >= → <, <= → >
• boolean logic: && ↔ ||
• arithmetic: + ↔ -, * ↔ /, unary -x → +x
• boolean literals: true ↔ false
• conditions: whole if conditions → true or false
• bodies (opt-in body group): a whole function body → a trivial literal of the declared return type (0/1/-1 for signed ints, 0/1 for unsigned, true/false for Bool, 0.0/1.0 for floats, ""/"xyzzy" for String, () for Unit or omitted annotations, None for T?/Option[T], [] for Array/FixedArray, {} for Map)

• KILLED — moon check succeeded and moon test failed.
• SURVIVED — both commands succeeded; tests did not detect the change.
• TIMEOUT — checking or testing exceeded the configured timeout.
• UNVIABLE — moon check rejected the mutated source.

{
  "schema": 3,
  "module": "/abs/path",
  "turtles_version": "0.4.7",
  "moon_version": "moon 0.1.20260920 (914d7da 2026-09-20) ~/.moon/bin/moon",
  "target": "native",
  "inactive_mutants": 1,
  "inactive_files": ["js_only.mbt"],
  "baseline_duration_ms": "216",
  "baseline_check_ms": "70",
  "baseline_test_ms": "146",
  "test_scope": "module",
  "mutants": [
    { "id": "m-e7ccdf47c3b8bc0b", "path": "math.mbt", "line": 3, "column": 5,
      "offset": 47, "end": 48, "group": "arithmetic",
      "original": "+", "replacement": "-", "outcome": "KILLED",
      "duration_ms": "202", "reused": false }
  ],
  "summary": { "killed": 6, "survived": 0, "timeout": 0, "unviable": 0,
               "reused": 0, "score": 100 }
}

#Survivor analysis (opt-in)

• --emit-properties writes <output>/properties/<mutant-id>.mbt skeleton tests for survivors whose parameter and return types have Arbitrary + Shrink + Debug instances. The shape is chosen from the signature: idempotence + involution for (A) -> A, commutativity + associativity for (A, A) -> A, a round-trip for encode/decode-style pairs, otherwise a @quickcheck.check stub over the parameter tuple. Each generated file starts with the marker // turtles: generated property suggestion plus the producing target; each run sweeps marker-bearing files that are no longer in the live set (a target switch removes a native-only mutant's suggestion) while never touching unmarked files. User tests are never edited — drop a skeleton into the package's tests when it looks right.
• --pbt-witness runs a differential witness on eligible survivors: for each surviving fn f, a temporary workspace gets a renamed copy of the original body plus a white-box @quickcheck.check(args => f(args) == f__turtles_orig(args)) and a determinism guard. If QuickCheck falsifies the equivalence, the counterexample is recorded as "witness" — strong evidence the mutant is a real gap. Ineligible survivors report witness_skipped: "effects-unknown" (mutable state, async, non-core calls, trait dispatch — anything the call-graph analysis cannot prove pure), "recursive" (the fn sits in a recursive SCC — an unbounded self-rewriting copy could diverge), "cfg" (a #cfg(...) declaration), "nondeterministic" (the guard falsified — f(args) != f(args)), "name-collision" (no collision-safe helper name left after 16 tries) or "harness-error". witness/witness_skipped fields appear only on survivors the analysis ran for; witness: "none" means the harness ran and did not falsify.
• --pbt-amplify <N> re-runs each survivor's module tests with the property budget scaled ×N (count = 100*N, or existing*N for explicit counts) and seeds shifted, in a temporary workspace. A mutant killed only after amplification reports KILLED with "amplified": true.

#Kill attribution and determinism

#Configuration

include = ["src/", "lib/"]
exclude = ["generated/", "vendor/"]
operators = ["comparison", "boolean", "arithmetic", "literal", "condition"]

• include: optional path substrings; when non-empty, at least one must match the normalized relative source path.
• exclude: optional path substrings; matching sources are skipped.
• operators: optional operator groups. Supported groups are comparison, boolean, arithmetic, literal, condition (whole-if-condition replacement), and body (function-body replacement). boolean covers only logical &&/||; selecting condition alone gives structural mutations without logical ones, and vice versa. body is never enabled implicitly — with no operators list every group except body runs.
• CLI --operators <LIST> takes a comma-separated group list and replaces the turtles.toml list wholesale, e.g. turtles --dir . --operators body,comparison.

#Skipping blocks

///|
#turtles.skip
pub fn fragile() -> Int {
  1 + 2
}

// turtles: skip
///|
pub fn also_skipped() -> Int {
  3 + 4
}

• CLI --file remains an additional filter on top of turtles.toml.
• Test files remain excluded by default and cannot be enabled through this configuration.

#Safety model

#Implementation notes

• moonbitlang/async for subprocess execution, cancellation, timing, the worker-pool task group, and async filesystem operations
• moonbitlang/parser@0.4.0 for syntax-aware mutation candidate discovery
• moonbitlang/x for native path/system support
• moon check and moon test for mutant classification

#Development

#Experimental proof companion

moon update
moon fmt --check
moon check --target native --deny-warn
moon test --target native
moon -C fixtures/basic test
moon run cmd/turtles -- --dir fixtures/basic --timeout 30

#Planned follow-ups

#Versioned native releases