# 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 mutants in ` 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.)_