#!/usr/bin/env python3 """Mutation tests for docs/fire-control-cut.md's Cut 4 ("The unused kinds join the same path") -- the last five weapon kinds (ConstantLaser, ConstantLightning, ConstantParticleWeapon, HitscanEffect, Mine) stop deciding their own hits through live Physics queries and join FireControl, the same owner Cut 3 gave the other four. Four rules are pinned here, each against tests/Aetheria.Shared.Tests/FireControlCut4Tests.cs: 1. BeamRollsPerInterval: a continuous weapon (ConstantWeapon) is a sequence of discrete rolls, one per GameplaySettings.BeamResolveInterval, not a roll per tick and not one roll for the whole burst. 2. InstantWeaponFiresWithoutAnyOnFireSubscriber / (implicitly) BeamRollsPerInterval again: FireControl.Fire must run whether or not a presentation is listening -- a real Cut 3/4 defect this campaign found and fixed. Inlining the call back into `OnFire?.Invoke(FireControl.Fire(...))` silently stops every shot from firing in a headless run (no Unity EntityInstance ever subscribes OnFire/OnBeamShot), because C#'s null-conditional short-circuits the whole expression, argument included, when the event has no subscriber. Pinned on both InstantWeapon.cs and ConstantWeapon.cs since Cut 3 introduced the pattern once and Cut 4 copied it a second time. 3. SplashHitsEveryEntityInRadius: FireControl.Splash (mine/airburst blast) is one rule applied to every entity within radius, not just the nearest. 4. SplashIsDirectional: splash damage lands on the half of each target's own hull that faces the blast, not the whole hull. A no-op control mutation proves the read/replace/restore path is transparent. Usage: python tests/mutation_tests_fire_control_cut4.py --cultlib-root Only touches files under this repository; every mutation is reversed before the script exits, including on failure. """ from __future__ import annotations import argparse import subprocess import sys from dataclasses import dataclass from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent TEST_PROJECT = REPO_ROOT / "tests" / "Aetheria.Shared.Tests" CONSTANT_WEAPON_CS = "Assets/Scripts/ServerShared/Behaviors/ConstantWeapon.cs" INSTANT_WEAPON_CS = "Assets/Scripts/ServerShared/Behaviors/InstantWeapon.cs" FIRE_CONTROL_CS = "Assets/Scripts/ServerShared/FireControl.cs" @dataclass class Mutation: rule: str file: str anchor: str mutated: str test: str expect: str # "red" (mutant must be killed) or "green" (the no-op control) MUTATIONS: list[Mutation] = [ # --- No-op control: proves the anchor/replace/restore mechanism is transparent --- Mutation( rule="control (no-op round trip)", file=CONSTANT_WEAPON_CS, anchor=" while (_beamTimer >= interval)", mutated=" while (_beamTimer >= interval)", test="FireControlCut4Tests.BeamRollsPerInterval", expect="green", ), # --- A beam is a sequence of rolls, not a continuous truth: roll per tick (many more, much smaller # --- outcomes over the same second) must be killed. --- Mutation( rule="ConstantWeapon must roll once per BeamResolveInterval, not once per tick", file=CONSTANT_WEAPON_CS, anchor=" while (_beamTimer >= interval)", mutated=" while (true)", test="FireControlCut4Tests.BeamRollsPerInterval", expect="red", ), # --- The opposite direction: rolling once for the whole burst (never draining the timer back below # --- interval) must also be killed -- a single outcome instead of a sequence. --- Mutation( rule="ConstantWeapon must not roll once for the whole burst", file=CONSTANT_WEAPON_CS, anchor=" _beamTimer -= interval;", mutated=" _beamTimer = float.NegativeInfinity;", test="FireControlCut4Tests.BeamRollsPerInterval", expect="red", ), # --- The real defect this campaign found: FireControl.Fire must run whether or not OnBeamShot has a # --- subscriber. Inlining it back into the null-conditional silently stops every beam from firing in a # --- headless run (nothing ever subscribes OnBeamShot). --- Mutation( rule="ConstantWeapon.Execute must evaluate FireControl.Fire even with no OnBeamShot subscriber", file=CONSTANT_WEAPON_CS, anchor=" var shotId = FireControl.Fire(this, Item, Entity, Damage * interval);\n OnBeamShot?.Invoke(shotId);", mutated=" OnBeamShot?.Invoke(FireControl.Fire(this, Item, Entity, Damage * interval));", test="FireControlCut4Tests.BeamRollsPerInterval", expect="red", ), # --- The same defect, in InstantWeapon.cs (Cut 3's original copy of the pattern) -- caught only by this # --- cut's own regression test, since FireAuthorityTests.cs always calls FireControl.Fire directly and # --- never exercises Trigger()/Execute() with zero OnFire subscribers. --- Mutation( rule="InstantWeapon.Execute must evaluate FireControl.Fire even with no OnFire subscriber", file=INSTANT_WEAPON_CS, anchor=" var shotId = FireControl.Fire(this, Item, Entity);\n OnFire?.Invoke(shotId);", mutated=" OnFire?.Invoke(FireControl.Fire(this, Item, Entity));", test="FireControlCut4Tests.InstantWeaponFiresWithoutAnyOnFireSubscriber", expect="red", ), # --- Splash is one rule, not per-effect: damaging only the nearest entity in range instead of every one # --- must be killed. --- Mutation( rule="FireControl.Splash must damage every entity in radius, not only the nearest", file=FIRE_CONTROL_CS, anchor=" var toTarget = (target.Position - position).xz;\n if (length(toTarget) > radius) continue;", mutated=" var toTarget = (target.Position - position).xz;\n if (length(toTarget) > radius) continue;\n if (zone.Entities.Where(e => length((e.Position - position).xz) <= radius).OrderBy(e => length((e.Position - position).xz)).First() != target) continue;", test="FireControlCut4Tests.SplashHitsEveryEntityInRadius", expect="red", ), # --- Splash is directional over each target's own hull: damaging the whole shape regardless of facing # --- must be killed. --- Mutation( rule="FireControl.Splash must damage only the half of the hull facing the blast, not the whole shape", file=FIRE_CONTROL_CS, anchor=" if (dot(normalize((float2) v - hullData.Shape.CenterOfMass), localDirection) < 0)\n hitShape[v] = true;", mutated=" hitShape[v] = true;", test="FireControlCut4Tests.SplashIsDirectional", expect="red", ), ] def replace_unique(path: Path, anchor: str, mutated: str) -> None: original = path.read_text(encoding="utf-8") count = original.count(anchor) if count != 1: raise SystemExit(f"{path}: anchor must occur exactly once, found {count}\n---\n{anchor}") path.write_text(original.replace(anchor, mutated), encoding="utf-8") def run_test(cultlib_root: str, test: str) -> tuple[int, str]: proc = subprocess.run( ["dotnet", "test", str(TEST_PROJECT), f"-p:CultLibRoot={cultlib_root}", "--filter", f"FullyQualifiedName~{test}"], capture_output=True, text=True, timeout=300, ) return proc.returncode, proc.stdout + proc.stderr def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("--cultlib-root", required=True) args = parser.parse_args() failures: list[str] = [] originals: dict[str, str] = {} for m in MUTATIONS: if m.file not in originals: originals[m.file] = (REPO_ROOT / m.file).read_text(encoding="utf-8") def restore_all() -> None: for file, text in originals.items(): (REPO_ROOT / file).write_text(text, encoding="utf-8") try: for m in MUTATIONS: print(f"\n=== {m.rule} (expect {m.expect}) ===") path = REPO_ROOT / m.file replace_unique(path, m.anchor, m.mutated) code, output = run_test(args.cultlib_root, m.test) passed = "Passed!" in output and code == 0 if m.expect == "green": if not passed: failures.append(f"{m.rule}: expected green (test passing), got failure\n{output[-2000:]}") else: print(f"OK: {m.test} passed under a no-op mutation, as expected") else: if passed: failures.append(f"{m.rule}: expected red (mutant killed), but {m.test} still passed") else: print(f"OK: {m.test} went red under the mutation, as expected") # Restore this file immediately so the next mutation starts from a clean tree. path.write_text(originals[m.file], encoding="utf-8") finally: restore_all() if failures: print("\n=== FAILURES ===") for f in failures: print(f"- {f}") return 1 print("\nAll mutations behaved as declared.") return 0 if __name__ == "__main__": sys.exit(main())