JoseAntonioNuevo/test-suite-doctor

Was macht test-suite-doctor?

Verkleinern Sie eine überdimensionierte Test-Suite (z. B. 2.000+ Tests, viele davon KI-generierter Schrott) auf eine kleine, qualitativ hochwertige Suite, während ein konfigurierbarer Anteil der echten Codeabdeckung erhalten bleibt – gemessen, nicht geraten.

Harte Regeln

1. Metriken vor Meinungen. Schlagen Sie niemals vor, einen Test zu löschen, bevor collect und minimize einen Plan erstellt haben. Testcode zu lesen und als „nutzlos“ zu beurteilen ist kein Beweis – ein trivial aussehender Test kann die einzige Abdeckung für einen Branch sein.
2. Der Plan ist ein Vorschlag, kein Urteil. Codeabdeckung kann keine API-Verträge, dokumentierte Regressionsfälle oder Eigenschaftsinvarianten sehen. Jeder Löschkandidat wird vor der Löschung überprüft (Schritt 3).
3. Arbeiten Sie auf einem Branch. Überprüfen Sie vor dem Löschen von Tests, ob der Arbeitsbaum sauber ist, und erstellen Sie einen Branch (z. B. test-doctor/minimize). Löschen Sie niemals Tests in einem unsauberen Baum oder auf dem Standard-Branch.
4. Verifizieren oder zurücksetzen. Die Aufgabe ist erst abgeschlossen, wenn verify mit Exit-Code 0 beendet wird. Wenn es fehlschlägt, generieren Sie Tests für die gemeldeten Lücken neu und verifizieren Sie erneut – oder stellen Sie die gelöschten Tests wieder her.

Voraussetzungsprüfung (zuerst durchführen)

• Node.js ≥ 22 und eine package.json mit lokal installiertem Vitest oder Jest (node <skill-root>/dist/cli.mjs collect --help).
• Ein Coverage-Provider muss installiert sein (Vitest: @vitest/coverage-v8; Jest hat einen eingebaut). Falls nicht vorhanden, anbieten, ihn als dev-Abhängigkeit zu installieren.
• Mutationsverifikation benötigt zusätzlich @stryker-mutator/core, konfiguriert im Ziel-Repository – sie ist optional, installieren Sie sie nicht unaufgefordert.
• Die Test-Suite sollte vor dem Start grün sein. Wenn der Basis-Lauf Fehler meldet, informieren Sie den Benutzer und holen Sie Zustimmung ein, wie damit umzugehen ist, bevor Sie minimieren (fehlschlagende Tests liefern unzuverlässige Codeabdeckung).

Alle unten aufgeführten Befehle werden vom Stammverzeichnis des Ziel-Repositorys aus ausgeführt; $SKILL ist das Verzeichnis dieser Fähigkeit. Artefakte landen in .test-doctor/ (empfehlen Sie, es zur .gitignore hinzuzufügen).

Workflow

1. MESSEN (Skript – immer zuerst)

node "$SKILL/dist/cli.mjs" collect --cwd .

Erkennt den Test-Runner, führt die gesamte Suite einmal als Coverage-Baseline aus, führt dann jede Testdatei isoliert erneut aus und zeichnet abgedeckte Zeilen/Branches sowie Laufzeit auf. Schreibt .test-doctor/report.json.

• Standard-Granularität ist pro Testdatei (pro-Test-Isolation ist exakt, führt aber jeden Test einzeln aus – bieten Sie --granularity test nur für kleine oder bereits reduzierte Suiten an, oder eingeschränkt mit --filter).
• Bei einer Suite mit 2.000 Tests dauert das eine Weile; führen Sie es im Hintergrund aus und berichten Sie den Fortschritt. Nehmen Sie collectionErrors im Bericht ernst – diese Einheiten blockieren die Minimierung standardmäßig. Wenn der Benutzer explizit --keep-unmeasured wählt, ist jede betroffene Einheit ein Pflicht-Erhalt und der Plan wird als nicht vertrauenswürdig markiert.
• --filter erstellt eine bewusst eingeschränkte Baseline: Sammlung, Minimierung und Verifikation decken nur passende Testdateien ab. Geben Sie diesen Umfang in jeder Empfehlung an; er ist keine garantie für das gesamte Repository.

2. MINIMIEREN (Skript)

node "$SKILL/dist/cli.mjs" minimize --coverage-floor 0.97 --target-count 200

Gierige gewichtete Summenauswahl: Behält wiederholt die Einheit mit den meisten neu abgedeckten Zeilen/Branches pro Millisekunde Laufzeit, bis die Coverage-Schwelle erreicht ist. Schreibt .test-doctor/plan.json und eine menschenlesbare .test-doctor/plan.md mit einer Begründung pro erhaltener und gelöschter Einheit.

• Fragen Sie den Benutzer nach seinen Schwellenwerten, falls nicht angegeben; Standardwerte sind eine Zeilen-Schwelle von 0,97, keine Branch-Schwelle, keine Zielanzahl. --help listet alle Parameter auf.
• Erzwingen Sie das Behalten bekannter Vertrags-/Regressionstests von Anfang an: --keep 'contract' --keep 'regression' (Regex auf Einheiten-ID).
• Beachten Sie das warnings-Array des Plans – z. B. dass die Schwelle nicht erreichbar ist oder mehr Einheiten als die Zielanzahl erforderlich sind. Leiten Sie diese wörtlich an den Benutzer weiter.

3. ÜBERPRÜFEN (Beurteilung – Ihre)

Lesen Sie references/slop-patterns.md, überprüfen Sie dann die Löschliste in plan.md:

• Retten Sie jeden Test, der ein für die Abdeckung unsichtbares Verhalten verifiziert: öffentliche API-Verträge, Regressionen mit Verweis auf eine Issue/Bug-ID, Fehlermeldungs-Wortlaut, auf den sich Verbraucher verlassen, Eigenschafts-/Invariantenprüfungen. Führen Sie die Minimierung mit zusätzlichen --keep-Mustern erneut aus, anstatt den Plan von Hand zu bearbeiten.
• Bestätigen Sie, dass die restlichen Löschungen sicher sind; klassifizieren Sie sie nach Schrott-Muster, damit der Benutzer sieht, warum jedes stirbt (die Musterei hat den Katalog).

Überprüfen Sie dann die Behaltensliste anhand von references/quality-rules.md: behaltene Tests, die verdächtig riechen (Mock-des-Mocks, Tautologien, hohle Snapshots) werden direkt umgeschrieben – sie verdienen ihre Abdeckung, aber sie sollten sie sauber verdienen.

Erst nach dieser Überprüfung löschen Sie die gelöschten Testdateien/-fälle auf dem Branch. Löschen Sie ganze Dateien, wenn alle ihre Einheiten gelöscht werden; bearbeiten Sie Dateien, wenn nur einige Tests darin sterben (Test-Granularität).

4. REGENERIEREN (Beurteilung – Ihre)

Führen Sie verify einmal aus (erwarten Sie, dass es fehlschlagen kann), um den Coverage-Lückenbericht zu erhalten, dann schreiben Sie neue Tests für die am stärksten betroffenen Quelldateien, die von verify aufgelistet werden, gemäß references/quality-rules.md: AAA-Struktur, verhaltensgesteuerte Namen, ein Verhalten pro Test, Mocks nur an externen Grenzen. Bevorzugen Sie einen starken Test, der ein echtes, benutzersichtbares Verhalten abdeckt, gegenüber drei oberflächlichen.

5. VERIFIZIEREN (Skript – schließt ab)

node "$SKILL/dist/cli.mjs" verify --coverage-floor 0.97
# optional, nur für kritische Module (langsam):
node "$SKILL/dist/cli.mjs" verify --mutation --mutate "src/billing/**/*.ts" --mutation-floor 80

Führt die Suite erneut aus, erfordert grüne Ergebnisse und erfordert, dass der Zeilenrückhalt gegenüber der Baseline die Schwelle erreicht. Exit 0 = erledigt; Exit 1 = beheben und erneut ausführen (mehr Tests regenerieren oder Löschungen rückgängig machen); Exit 2 = Umgebungsproblem, anhalten und melden. Mutationstests sind optional pro Modul, weil sie langsam sind – bieten Sie sie für die Module an, die der Benutzer als kritisch bezeichnet.

Version 2 vergleicht den Fingerabdruck der abgedeckten Quellen, Runner-Konfiguration, Lockfile, Runner und Coverage-Provider. Wenn verify eine Abweichung der Herkunft meldet, sammeln Sie eine neue Baseline. Verwenden Sie --allow-provenance-drift nur mit ausdrücklicher Benutzerzustimmung und melden Sie das resultierende Ergebnis als nicht vertrauenswürdig. Legacy-v1-Baselines erfordern ebenfalls die explizite --allow-legacy-baseline-Notluke.

Rückmeldung

Fassen Sie für den Benutzer zusammen: Einheiten vorher → nachher, Zeilen-/Branch-Erhalt, Laufzeit vorher → nachher, gefundene Schrott-Muster (mit Anzahl), aus der Löschliste gerettete Tests und warum, regenerierte Tests und das endgültige verify-Ergebnis. Fügen Sie den Pfad zu plan.md für den vollständigen Prüfpfad hinzu.

Fehlermodi

• Runner nicht erkannt / mehrdeutig → die CLI wird mit Exit-Code 2 und Anleitung beendet; übergeben Sie --runner oder --cwd (Monorepos: pro Paket ausführen).
• Unvollständige Sammlung → beheben Sie die isolierten Fehler. Filtern Sie sie nicht einfach weg, nur um einen Plan durchzubringen; ein Filter ändert den deklarierten Baseline-Umfang. --keep-unmeasured ist die konservative Notluke.
• Verify schlägt nach Regeneration weiterhin fehl → stoppen Sie die Schleife nach etwa 3 Versuchen; präsentieren Sie die verbleibende Lücke dateiweise und lassen Sie den Benutzer zwischen Senken der Schwelle und Behalten weiterer Tests entscheiden.
• Suite war vor dem Start rot → „reparieren“ Sie nicht stillschweigend nicht zusammenhängende Fehler; melden Sie sie und klären Sie zuerst den Umfang.