Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/11-backlog/stryker.md
T

7.8 KiB

Stryker Mutation-Testing

Status: backlog: test-coverage.md (Phase 10) fertig + Bedarf nach höherer Test-Quality (z.B. nach unentdecktem Critical-Bug in Production der trotz hoher Coverage durchgekommen ist) Task-ID: #77 Phase: 11 (Backlog) Estimated Effort: ~1 Woche Setup + Tuning + Initial-Fix-Sprint wenn aktiviert Owner: unassigned

Problem

Coverage-Zahlen aus Phase 10 (test-coverage.md) sagen nur, dass Code „ausgeführt" wurde, nicht dass das Verhalten „verifiziert" wurde. Tests, die zwar Coverage erzeugen aber keine echten Assertions machen (z.B. expect(result).toBeDefined() statt expect(result).toEqual({...})), bleiben unentdeckt. Sobald Coverage > ~80% etabliert ist und trotzdem Bugs in Production rutschen, lohnt sich Mutation-Testing als nächster Quality-Hebel.

Mutation-Testing ist sehr build-intensiv (Faktor 50-500x normale Test-Laufzeit, weil pro Mutation die volle Test-Suite gegen mutierten Code läuft). Vorab-Aktivierung ohne stabile Coverage-Baseline wäre verfrüht, weil zuerst Coverage hochgezogen werden muss, bevor Mutation-Score sinnvoll wird.

Depends on

  • ../10-compliance-polish/test-coverage.md — Coverage muss erst belastbar sein, sonst ist Mutation-Score nicht aussagekräftig
  • bestehende Vitest-Setup im Codebase

Blocks

  • nichts (Backlog-Item, blockt keine aktive Roadmap)

Approach

Stryker (@stryker-mutator/core + @stryker-mutator/vitest-runner) als Nightly-Job, nicht als PR-Check. Begründung:

  • Stryker als PR-Check: würde PR-Builds um Faktor 50+ verlangsamen. Verworfen.
  • Stryker als Nightly-Job (gewählt): läuft auf separatem CI-Runner über Nacht, Report wird morgens als GitHub-Action-Artifact + Slack/Email-Notification ausgeliefert. Slow-Feedback, aber für Mutation-Testing akzeptabel.
  • Andere Mutation-Tools (Pitest für Java, mutmut für Python): nicht relevant — TS-Codebase, Stryker ist Standard.

Was Stryker macht: mutiert Code in kleinen Weisen — Operator-Swap (+ → -, === → !==), Boolean-Flip (true → false), Return-Value-Replacement (return x → return null), Conditional-Boundary-Shifts (< → <=) — und prüft, ob die Test-Suite den mutierten Code „killt" (Test failt). Wenn ein Mutant „überlebt" (alle Tests bleiben grün trotz Mutation), ist das ein Hinweis auf schwache Tests.

Score-Target: Mutation-Score (killed / total) >70% auf Critical-Paths (Auth, Billing, Tenant-Isolation, Audit-Logging, AI-Cost-Tracking). Niedrigere Schwelle für Non-Critical-Paths (UI-Komponenten, Marketing-Pages) — dort ist Mutation-Testing weniger wertvoll und kostet zu viel CI-Zeit.

Tuning: anfänglich nur ausgewählte Pakete/Module mutieren, nicht den ganzen Monorepo (sonst läuft Nightly-Job über 24h). Inkrementell ausweiten wenn CI-Kapazität es zulässt.

Initial-Fix-Sprint: nach erstem Stryker-Run werden vermutlich viele „überlebende" Mutanten gefunden. Sprint priorisiert Critical-Path-Survivors, fügt fehlende Assertions hinzu, fixt schwache Tests. Pro Modul ein Commit.

Implementation Steps

  1. Stryker-Install + Minimal-Config — @stryker-mutator/core + @stryker-mutator/vitest-runner als Dev-Deps, stryker.config.mjs mit Scope auf zunächst nur 1-2 Critical-Module (z.B. app/utils/auth/ + app/modules/billing/). Commit: 11-backlog/stryker: install + minimal config for auth + billing
  2. Erster Lokal-Run + Baseline-Report — npx stryker run lokal, Output sichten, Baseline-Mutation-Score dokumentieren in docs/quality/mutation-testing.md. Commit: 11-backlog/stryker: baseline report
  3. Nightly-CI-Workflow — GitHub-Actions-Workflow mutation-testing-nightly.yml, läuft 03:00 UTC, läuft Stryker für definierten Scope, lädt HTML-Report als Artifact hoch, postet Score in Slack/Discord (oder Issue-Comment). Commit: 11-backlog/stryker: nightly ci workflow
  4. Initial-Fix-Sprint (Auth-Module) — überlebende Mutanten im Auth-Modul analysieren, fehlende Assertions hinzufügen oder neue Test-Cases. Pro logischem Fix-Block ein Commit 11-backlog/stryker: kill <n> mutants in <module>
  5. Initial-Fix-Sprint (Billing-Module) — gleiches für Billing
  6. Scope-Erweiterung Critical-Path-Module — Tenant-Isolation-Module, Audit-Logging-Module, AI-Cost-Tracking-Module hinzunehmen. Commit: 11-backlog/stryker: expand scope to tenant + audit + ai-cost
  7. Score-Gate für Critical-Paths — Stryker-Config: thresholds.high=80, thresholds.low=70, thresholds.break=70 für Critical-Path-Module, Nightly failt unter 70%. Commit: 11-backlog/stryker: enforce 70% threshold on critical paths
  8. Doku — docs/quality/mutation-testing.md: was Mutation-Testing ist, wie man den Nightly-Report liest, wie man überlebende Mutanten fixt, welche Module im Scope sind. Commit: 11-backlog/stryker: documentation

Test Requirements

  • Lokaler Stryker-Run funktioniert auf einem Critical-Path-Modul ohne Crash
  • Nightly-CI-Workflow läuft erfolgreich durch (mind. 1x bestätigt auf Staging-Branch)
  • HTML-Report wird als Artifact gespeichert und ist downloadbar
  • Score-Threshold wird durchgesetzt: ein bewusst eingeführter „leerer Assertion"-Test in Critical-Path muss den Nightly failen lassen
  • Coverage-Target: Mutation-Score >70% auf jedem Critical-Path-Modul (Auth, Billing, Tenant, Audit, AI-Cost) nach Initial-Fix-Sprint
  • Test-Files: keine neuen Test-Files dediziert für Stryker; existing Tests werden verbessert

NICHT als completed markieren bevor mind. 2 Critical-Path-Module die 70%-Schwelle erreichen.

Acceptance Criteria

  • Stryker installiert + konfiguriert mit Scope auf mind. 5 Critical-Path-Module
  • Lokaler Run funktioniert
  • Nightly-CI-Workflow läuft stabil, postet Report in Notification-Channel
  • HTML-Report als Artifact verfügbar
  • Initial-Fix-Sprint: alle Critical-Path-Module erreichen Mutation-Score ≥70%
  • Score-Threshold im CI durchgesetzt (Nightly failt bei Threshold-Bruch)
  • docs/quality/mutation-testing.md mit Erklärung + Report-Reading-Guide + Scope-Liste
  • Tests grün
  • Progress-Log + PROGRESS.md aktualisiert

Rollback Strategy

  • Stryker ist purely additive Quality-Tooling — Entfernen brichtnichts in der App-Funktionalität
  • Nightly-CI-Workflow kann via GitHub-Actions-UI deaktiviert werden, Default-Build-Pipeline läuft unverändert
  • Wenn Mutation-Score-Gate falsche Positives produziert: Scope verkleinern statt Tool entfernen
  • Stryker-Config in einer Datei (stryker.config.mjs) — einfacher Revert

Security Notes

  • Stryker mutiert Source-Code in temporären Ordnern — sicherstellen, dass .gitignore .stryker-tmp/ enthält (gleich beim Setup)
  • Nightly-CI-Runner braucht read-only Code-Access, keine Secrets — Stryker macht keine Network-Calls
  • HTML-Report enthält Source-Code-Snippets — als private GitHub-Action-Artifact halten, nicht öffentlich

Subagent Recommendations

  • Planning: Plan-Subagent mit Critical-Path-Modul-Liste als Input
  • Research: Explore-Subagent für Stryker-Best-Practices in Monorepos (insb. wie man Scope sinnvoll begrenzt)
  • Implementation: ein general-purpose-Subagent pro Step
  • Tests (Fix-Sprint): ein general-purpose-Subagent pro Critical-Path-Modul für das Kill-Mutants-Refactoring
  • Verification: gsd-verifier für Threshold-Enforcement-Test (bewusst leerer Test → Nightly muss fail)
  • Code-Review: gsd-code-reviewer nach jedem Fix-Sprint-Modul

Staging-Deployment-Steps

  1. Branch agent/11-backlog-stryker pushen
  2. Lokaler Stryker-Run auf Auth-Modul, Report sichten
  3. Nightly-Workflow auf Branch testen (manueller Trigger via workflow_dispatch)
  4. HTML-Report-Artifact downloaden, manuell inspizieren
  5. Bewusst leeren Test einbauen, Nightly muss failen — danach revertieren

Deviations from Plan

(Wird vom ausführenden Agent gefüllt.)

Progress Log

(Wird vom ausführenden Agent gefüllt.)