Test-Flakes diagnostizieren
Der Testing-Überblick sagt dir, wie du einen Test schreibst, der nicht flakt. Diese Seite ist die andere Hälfte: Du hast einen Test, der es bereits tut, und musst wissen, welche Sorte es ist.
Zuerst: flaky oder einfach kaputt?
Abschnitt betitelt „Zuerst: flaky oder einfach kaputt?“Ein Test, der einmal umfällt und beim erneuten Lauf grün ist, ist keine Kategorie — er ist eine Beobachtung mit Stichprobengröße eins. Lass ihn absichtlich noch einmal laufen:
# 20 repeats of one file, naming anything that failed at least oncebun run test:stress -- --runs=20 tests/unit/http/websocket/WebsocketServerActor.test.tsbun run test:stress (scripts/stress-test.mjs) lässt die Suite N-mal
laufen, hebt JUnit-Report und Log jedes Laufs auf und aggregiert Fehlschläge
nach Test-Identität. Die Ausgabe trennt die beiden Fälle, auf die es
ankommt:
| Urteil | Bedeutung | Was zu tun ist |
|---|---|---|
| flaky — in einigen Läufen umgefallen | Das Ergebnis hängt an Timing, Reihenfolge oder Maschine. | Gegen den Katalog unten halten. |
| durchgehend rot — in jedem Lauf umgefallen | Kaputt. Wiederholung sagt dir nichts Neues. | Reparieren oder ein Issue aufmachen. Das ist kein Flake. |
Ein Test, der innerhalb eines einzelnen Laufs mehr als einmal umfiel, fiel
früher aus beiden Kategorien heraus — der Harness schrieb dann „No test failed
in any run that reported“ und endete mit Exit-Code 0, über sechzehn Läufen, von
denen keiner grün war, zwei Zeilen unter einer Fehlerrate von 100 % (#1359).
failedRuns zählt jetzt Läufe, jeden Lauf einmal, gleich wie viele Testfälle die
Identität getragen haben, und die Zahl der Vorkommen steht daneben
(4 failing testcases in total), statt in die Klassifikation einzufließen. Ein
Hook-Timeout erzeugt die Form weiterhin am leichtesten: ein describe, dessen
beforeAll und afterAll beide ihr Budget sprengen, liefert zwei
(unnamed)-Fälle unter einem Classname.
Das Urteil fällt jetzt außerdem über Läufe, nicht nur über Tests. Ein Lauf,
der nicht grün war und den kein tolerierter Offender erklärt, ist rot, egal was
die Tabellen sagen — und genau in diesem Feld ist das Ausstiegskriterium der
Quarantäne formuliert (greenRuns == runs), das das alte Urteil berechnete,
ausgab und dann nicht anwandte.
Drei weitere Dinge benennt es, statt sie zu schlucken: einen Lauf, der nie beendet wurde (siehe unten), einen Lauf, der gar keinen JUnit-Report erzeugt hat (Bun starb, bevor der Reporter geflusht hat — die Fehlschläge fehlen in den Summen, statt nicht zu existieren), und einen Lauf, der mit Exit-Code ≠ 0 endete, ohne dass ein Test umgefallen ist (ein Absturz im Teardown, ein nicht freigegebenes Handle). Alle drei lesen sich für eine naive Schleife als „grün“.
bun run test:stress # 10 repeats of the whole suitebun run test:stress -- --runs=3 # 3 repeatsbun run test:stress -- --concurrency=4 # 4 at once, for real CPU contentionbun run test:stress -- --run-timeout=300000 # call a run hung after 5 minutesEin Hänger ist ein Messwert, kein Abbruch. Der Fehler, den die
quarantänisierten Suites auf Hosted Runnern zeigen, ist kein roter Test —
Worker starten, machen den Handshake und laufen dann nie los, bun test
beendet sich also gar nicht. --run-timeout (standardmäßig 20 Minuten)
tötet so einen Lauf, verbucht ihn als HUNG — getrennt von einem Fehlschlag
und von einem abgeschnittenen Report, weil jedes auf eine andere Ursache
zeigt — und macht mit der nächsten Wiederholung weiter. Ohne das blieb die
Schleife beim ersten Hänger stehen, und der Job wurde von seinen eigenen
timeout-minutes getötet, ohne irgendetwas vorzuweisen: Die eine Messung,
für die es das Harness gibt, war genau die, die es nicht überlebte. Hängende
Läufe stehen im summary.json unter runsTimedOut; eine Nacht mit auch nur
einem davon ist rot.
Reports, Logs und ein maschinenlesbares summary.json landen in .stress/.
Warum man dem Harness glauben kann
Abschnitt betitelt „Warum man dem Harness glauben kann“Alles oben ist ein berechnetes Urteil, und ein Klassifikator, der falsch liegt, sieht genau wie eine Messung aus, die überrascht. Deshalb wird das Harness gegen Eingaben geprüft, deren Antwort vor dem Lauf feststeht:
tests/unit/ci/StressHarnessAggregation.test.tstreibt den JUnit-Parser und die Aggregation über Fixtures — ein Pass, ein<failure>, ein<error>, ein<skipped/>, ein maskierter Testname, und derselbe Test mit POSIX-Pfad, Windows-Pfad und absolutem Pfad geschrieben, was zu einer Identität zusammenfallen muss, sonst werden aus „ist in 3 von 5 Läufen fehlgeschlagen” drei unabhängige Rot-Meldungen.tests/unit/ci/StressHarnessClassification.test.tsführt das echte Skript über eine synthetische Suite aus, deren Verhalten eine Zählerdatei bestimmt: Ein Test schlägt in Lauf 3 von 5 fehl, einer in allen fünf, einer nie, einer wird übersprungen. Das erwartete Urteil ist damit eine Tatsache und keine Einschätzung — die einzige Art, „als flaky gemeldet” von „falsch klassifiziert” zu unterscheiden.tests/unit/ci/StressHarnessWatchdog.test.tstreibt es gegen eine Suite, die tatsächlich nie fertig wird.
Die Unterscheidung, die diese drei schützen, ist die, auf der diese Seite aufbaut. Ein Skip, der als Pass zählt, oder ein Hänger, der als grün zählt, erzeugt eine sauber aussehende Zahl für eine Nacht, in der nichts gemessen wurde — und genau diese Zahl würde dann hier zitiert.
Was Wiederholung findet — und was nicht
Abschnitt betitelt „Was Wiederholung findet — und was nicht“Eine Schleife treibt die Wahrscheinlichkeit eines lastabhängigen Flakes hoch: ein fester Sleep, der auf einer unbeschäftigten Maschine lang genug ist und unter Last zu kurz. Das ist hier die dominante Familie, und die Schleife findet sie.
Über einen deterministischen Reihenfolge-Fehler sagt sie nichts. Das
klarste Beispiel in diesem Repository ist ein Test, der auf den
aufgezeichneten Zustand des einen Actors wartete und dann den eines anderen
prüfte — zwei Zustände, getrennt durch einen Dispatcher-Hop. Eine
Wegwerf-Probe ließ die kaputte Bedingung 200-mal laufen: 0 Fehlschläge bei
5 ms Poll-Intervall und weiterhin 0 bei 1 ms. Die Probe lief, als der
Default-Dispatcher jeden Zug über setImmediate schedulte; der heutige
Hybrid-Default übergibt die meisten Züge als Microtasks, also noch früher.
So oder so steht der Zug des zweiten Actors vor dem nächsten Timer des
Pollers in der Queue und gewinnt jedes Mal, solange Arbeit zügig
abgearbeitet wird. Das Rennen ist konstruktionsbedingt real und lokal nicht
reproduzierbar.
Ein grüner Stress-Lauf ist also Evidenz über eine Familie, kein Freibrief. Die zweite Familie findet man durch Lesen:
Liegt zwischen dem Zustand, auf den du wartest, und dem Zustand, den du prüfst, ein Message-Send?
Wenn ja, ist das Warten ein Stellvertreter, den ein halb fertiger Schritt bereits erfüllt — warte stattdessen auf den geprüften Zustand.
Wo die Wiederholung bezahlt wird
Abschnitt betitelt „Wo die Wiederholung bezahlt wird“An drei Stellen, jede mit einer anderen Frage.
- Bei jedem Commit führen
test.ymlundmulti-runtime.ymldie ganze Suite einmal, gemischt aus — „hängt irgendetwas davon ab, nach etwas anderem zu laufen”. - Bei jedem Pull Request wiederholt eine Sonde die geänderten Testdateien des Branches fünfmal — „hängt ein Test, den dieser Branch hinzufügt, von dem Lauf ab, in dem er geschrieben wurde”. Das ist der Moment, in dem ein neuer Flake am billigsten zu beheben ist, und der einzige, in dem er einen offensichtlichen Verantwortlichen hat.
- Jede Nacht schleift
nightly-flakes.ymldie ganze Suite und aggregiert nach Test-Identität — die lastabhängige Familie von oben, über eine Population, die kein Branch anfasst. Eine Nacht, die nicht grün ist, öffnet ein Issue, und eine grüne schließt es wieder.
Der letzte Punkt hat am längsten gebraucht, und es lohnt sich zu sagen, warum.
Die Nightly hat diese Suite monatelang gemessen, und die Messung erreichte
niemanden: beide Jobs waren continue-on-error, und das Urteil ging in eine
Step-Summary und eine Run-Annotation. Der Workflow hat sein eigenes Versagen in
einem Kommentar vorhergesagt — „Nichts akkumuliert die Serie. Sie wird von einem
Menschen gezählt, der diese Annotations liest — dasselbe Versagen, das die
Quarantäne überhaupt erst dauerhaft gemacht hat.” Niemand zählte. Das
Vierzehn-Nächte-Kriterium stand bei einundzwanzig, bevor jemand nachsah.
Ein Issue hat einen Verantwortlichen, eine Historie und eine Benachrichtigung — was eine Annotation nie hatte. Und weil der Befund damit handhabbar ist, ist ein roter Job eine Tatsache statt Rauschen: die Unterdrückung ist weg. An einem geplanten Workflow hängt nichts, und Rot dort blockiert keinen Pull Request.
Die Sonde folgt den geänderten Testdateien und nicht allem, was eine Änderung
erreicht — und die Zahlen sind der Grund. bun test --changed folgt Importen
transitiv: gemessen an diesem Baum wählte eine Änderung an einem
Persistence-Modul 346 Dateien und 5 505 Tests in 209 s aus, und eine Basis,
deren Diff einen tests/util/-Helper berührte, 468 Dateien und 8 777 Tests in
252 s. Fünf Wiederholungen davon sind ein halbstündiger Job, und was er
gegenüber der nächtlichen Schleife hinzufügt, ist dieselbe Frage über eine
kleinere Population. Wiederholung zahlt sich dort aus, wo der Code neu ist —
also folgt die Sonde dem neuen Code, und eine Änderung unter src/ deckt
weiterhin die gemischte Suite einmal ab, genau wie zuvor.
Generative Tests laufen gegen einen fixierten Seed
Abschnitt betitelt „Generative Tests laufen gegen einen fixierten Seed“Ein Property-Test mit zufälligem Seed kann in einem Lauf umfallen und im
nächsten durchgehen. Das ist per Definition ein Flake, und die schlimmste
verfügbare Sorte: Das Gegenbeispiel existiert nur im Run-Log, und wenn das
rotiert, ist der fehlschlagende Fall weg und niemand kann reproduzieren, was
passiert ist. Vor #1372 hatte dieses Repository ~52 fc.assert-Aufrufstellen,
keinen seed, kein endOnFailure und nirgends einen Regressions-Korpus.
tests/setup/property-seed.ts fixiert den Seed für den ganzen Prozess über
fc.configureGlobal, geladen durch preload in bunfig.toml — eine Stelle
statt zweiundfünfzig, sodass eine neue Property-Datei die Policy bekommt, ohne
dass ihre Autorin von ihr wissen muss.
Der Preis ist real und gehört ausgesprochen: Ein fester Seed erkundet in jedem
Lauf dieselben Fälle, die Suite findet also von selbst keine neuen
Gegenbeispiele mehr. Das ist vertretbar, weil sie das nie wirklich tat. Ein
Fall, den eine unglückliche Nacht fand und den die Log-Rotation dann verschluckte,
wurde nie zu einem Regressionstest — die Erkundung produzierte rote Builds statt
Wissen. Neue Fälle kommen jetzt daher, dass jemand PROPERTY_RUNS erhöht oder
PROPERTY_SEED ändert: eine Entscheidung, in einem Diff, von der man erwartet,
dass sie der Commit ist, der etwas findet.
Wenn eine Property doch umfällt, kopiere das geschrumpfte Gegenbeispiel als schlichten Beispieltest daneben — bevor du irgendetwas reparierst. Die Property beweist das Gesetz; das Beispiel verhindert, dass genau dieser Fall zurückkommt, und überlebt anders als eine Log-Zeile.
tests/unit/ci/PropertySeedPolicy.test.ts hält beide Hälften verdrahtet, und
seine letzte Assertion ist die entscheidende: Sie fragt fast-check, mit welchem
Seed es tatsächlich läuft — ein Preload, der eingetragen und nie geladen
wurde, fällt damit um, statt still den Zufalls-Default wiederherzustellen.
Der Katalog
Abschnitt betitelt „Der Katalog“Ursachen, die diese Suite tatsächlich hatte, mit ihrem jeweiligen Stand.
| Familie | Stand | Signatur |
|---|---|---|
| Fester Sleep vor einer Assertion | Wird umgestellt, mit Ratsche | await sleep(N), dann expect(...) auf Zustand, den ein Hintergrundschritt erzeugt |
| Ein Budget, das der Test-Timeout nie erreicht | Geprüft | this test timed out after 5000ms, wo ein awaitCondition-Label erwartet war |
| Echte Arbeit in einem Hook, gegen ein Limit, das niemand gesetzt hat | Geklärt | (unnamed) und „a beforeEach/afterEach hook timed out“, ohne Testnamen |
| Echte Arbeit in einem Test-Body, gegen ein Limit, das niemand gesetzt hat | Geklärt | this test timed out after 5000ms mit einem Testnamen, der begrenzte Arbeit tut und allein durchläuft |
| Buns Timer-Quantum | Frühe Hälfte mit bun 1.4 erledigt | Eine Elapsed-Time-Assertion fällt um ~15 ms daneben, auf unbeschäftigter Maschine |
| Dispatcher-Hop zwischen Warten und Prüfen | Geklärt | Isoliert nie reproduzierbar; fällt nur im großen Parallel-Lauf um |
| Port-Kollisionen | Geklärt | EADDRINUSE, nur wenn Suites sich überlappen |
| Filesystem-Races | Geklärt | Zwei Suites lesen die Fixtures der jeweils anderen |
| Eine Assertion über prozessweiten Zustand | Geklärt | Läuft isoliert durch, fällt im Lauf der ganzen Suite um, und es ist kein Timing beteiligt |
| Ein Test, der davon abhängt, nach einem anderen zu laufen | Geklärt, geprüft | Grün in Deklarationsreihenfolge, rot unter --seed=N; ein Wiederholungslauf wiederholt dieselbe Reihenfolge und findet ihn nie |
| Worker-Respawn auf Hosted Runnern | Erledigt, nächtlich bewacht | Worker starten, machen den Handshake, laufen dann nie — in 63 gemessenen Ausführungen kein einziges Mal |
Fester Sleep vor einer Assertion
Abschnitt betitelt „Fester Sleep vor einer Assertion“Mit Abstand die dominante Form. N stammt aus einem Lauf, der grün war,
kodiert also die Latenz einer Maschine an einem Tag; unter Last dauert der
Schritt länger, und die Assertion liest einen Wert, der nie geschrieben
wurde.
// ✗ the sleep is a bet on how fast the machine isawait sleep(50);expect(stopped).toBe(true);// ✓ returns as soon as it holds; the timeout only bounds the broken caseawait awaitCondition(() => stopped, { label: 'the failing child was stopped' });expect(stopped).toBe(true);tests/util/AwaitCondition.ts ist der gemeinsame Helper, und
Auf Zustand warten, nicht auf verstrichene Zeit
behandelt, wann ein Sleep weiterhin richtig ist — eine Abwesenheit, der man
nur ein Zeitfenster geben kann, eine Dauer, die selbst die Assertion ist,
eine Verschränkung, die ein Test braucht.
Die Umstellung ist im Wesentlichen angekommen, und die Form des Rests ist
der nützliche Teil. 486 Wartezeiten mit fester Dauer bleiben unter tests/ —
440 als await sleep(N) geschrieben, 46 als direktes Bun.sleep(20) —, aber
483 davon nennen inzwischen einen Grund für die Verzögerung. Drei tun es
nicht, und alle drei stehen in Helper-Dateien statt in einem Test:
tests/util/AwaitCondition.ts (das gemeinsame sleep selbst) und zwei im
Integration-Scenario-Baum.
Die beiden Doppelungen, die diese Seite früher meldete, sind praktisch weg.
Eine Datei deklariert noch ihr eigenes sleep —
tests/integration/scenarios/Types.ts, die es für diesen Baum exportiert —
gegen 129, die das gemeinsame importieren, und 11 Module bauen sich noch
eine while (Date.now() < deadline)-Schleife, statt awaitCondition zu rufen.
Behandle ein sleep-dann-expect-Paar in einem umgefallenen Test als
Verdächtigen, bevor du nach etwas Raffinierterem suchst — und lies zuerst
seinen Begründungskommentar: meist sagt er dir, ob das Warten die Wette ist
oder die Assertion.
Diese Zahlen sind nicht nur Dokumentation.
tests/unit/ci/SleepRatchet.test.ts misst sie bei jedem bun test nach und
schlägt fehl, sobald eine steigt — pro Modul. Die Schuld kann also schrumpfen
und nicht wieder wachsen. Verboten wird dabei nicht das Warten — eine
Abwesenheit lässt sich nicht pollen, und auf viele der Wartezeiten folgt eine
Assertion, dass etwas nicht passiert ist —, sondern eine unbegründete
Wartezeit, ein neu deklariertes sleep und eine neu erfundene Poll-Schleife;
für alle drei nennt die Fehlermeldung eine einzeilige Abhilfe.
Erhoben am 08.09.2026 auf 5c7064f5, über Quelltext mit ausgeblendeten
Kommentaren und String-Literalen — genau das, was der Scanner der Prüfung tut.
Ein rohes grep -ro '<pattern>' tests/ --include=*.ts | wc -l misst grob nach
und liegt zu hoch, weil es auch die Prosa und die zitierten Beispiele mitzählt —
diese Seite eingeschlossen.
Die früheren Zahlen auf dieser Seite wurden am 18.08.2026 auf 95db877c
erhoben, bevor die Umstellungs-Welle aus #418 gemergt wurde — sie
beschrieben also den Baum vor genau der Arbeit, um die es auf dieser Seite
geht. Zwei von ihnen waren nicht nur veraltet, sondern invertiert: Die Seite
sagte einer Mitwirkenden, 93 Dateien deklarierten sleep neu, „statt das
gemeinsame zu importieren (8 importieren es)” — heute deklariert es eine Datei
und 129 importieren es (#1313). Eine gemessene Behauptung trägt genau deshalb
die Revision mit sich, auf der sie erhoben wurde.
Ein Budget, das der Test-Timeout nie erreicht
Abschnitt betitelt „Ein Budget, das der Test-Timeout nie erreicht“Bun bricht einen Test nach 5 000 ms ab, sofern der Test nichts anderes
angibt, und nichts in diesem Repository hebt das global an. Ein
awaitCondition-Budget ab 5 s ist also nicht großzügig, sondern
unerreichbar: Der Lauf meldet this test timed out after 5000ms statt des
Labels — genau das eine, wofür es den Helper gibt. Schlimmer noch, die
Ablehnung des Budgets landet später trotzdem, als unbehandelter Fehler ohne
zugehörigen Test.
Gib dem Test stattdessen den Platz:
test('shards rebalance when a node leaves', async () => { await awaitCondition(/* … */, { timeoutMs: 10_000, label: '…' });}, 30_000); // the cap is a backstop; the budget is what reportstests/unit/ci/AwaitConditionBudgets.test.ts prüft das über den ganzen Baum —
größtes erreichbares Budget plus 1 s muss in den Cap passen — und verfolgt
auch Budgets, die über einen modulweiten Helper erreicht werden. Buns
Verhalten misst der Test in einem Kindprozess nach, statt es anzunehmen: Ändert
Bun das, sagt die Prüfung es, statt still bedeutungslos zu werden.
Echte Arbeit in einem Hook, gegen ein Limit, das niemand gesetzt hat
Abschnitt betitelt „Echte Arbeit in einem Hook, gegen ein Limit, das niemand gesetzt hat“Bun deckelt einen Hook bei 5 000 ms, genau wie einen Test — und das Mittel
aus dem vorigen Abschnitt hat ein Gegenstück, von dem man leicht nichts weiß:
beforeAll(fn, timeoutMs) nimmt ein zweites Argument, so wie test() ein
drittes nimmt.
tests/unit/docs/DocSampleHarnessEndToEnd.test.ts ist der Fall, den diese Suite
hatte (#1282). Sein beforeAll schreibt einen Fixture-Dokumentationsbaum und
lässt dann zweimal den Doc-Sample-Harness laufen — und jeder dieser Läufe startet
zweimal bunx tsc, weil die Fixture bewusst einen nicht parsebaren Fence enthält
und das erneute Prüfen des Rests ohne ihn genau die Eigenschaft ist, für die es
die Datei gibt. Der Hook treibt also vier Compiler nacheinander: 3,1 s im
Leerlauf, 4,3 s in einem vollen bun test, 9,0 s, wenn mehrere Kopien der Datei
um die Maschine konkurrieren. Gegen ein Limit von 5 000 ms ist das kein langsamer
Test, sondern ein Münzwurf — allein lief die Datei jedes Mal durch, und im Lauf
der ganzen Suite fiel sie in etwa drei von vier Läufen um.
Zwei Dinge machen diese Familie schwerer lesbar als die Test-Timeout-Familie oben:
- Der Fehlschlag benennt nichts. Er erscheint als
(fail) <describe> > (unnamed) [5001.31ms]mit „a beforeEach/afterEach hook timed out for this test“ — die falsche Hook-Art, und kein Testname, weil kein Test schuld ist. Im Log nach dem Dateinamen zu greppen findet ihn; nach einem Testnamen zu greppen nicht. - Er meldet zu wenig davon, was nicht lief. Jeder Test des Blocks fällt aus, und ein Fehlschlag wird verbucht. Grün führt dieselbe Datei 13 Tests pro Lauf aus; rot war es einer.
Das Mittel sind gestaffelte Budgets, keine einzelne größere Zahl:
const RUN_BUDGET_MS = 30_000; // what one spawned run may takeconst HOOK_BUDGET_MS = 3 * RUN_BUDGET_MS; // a backstop, not the budget
function run(): Run { const startedAt = performance.now(); const result = spawnSync(command, args, { encoding: 'utf8', timeout: RUN_BUDGET_MS }); if (result.error !== undefined || result.signal !== null) { const elapsed = Math.round(performance.now() - startedAt); throw new Error(`${command} did not complete after ${elapsed} ms`); } return { status: result.status ?? -1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };}
beforeAll(() => { /* … */}, HOOK_BUDGET_MS); // reached only if the stall was not in a spawnDass der Cap des Hooks über dem Budget der Arbeit selbst liegt, ist Absicht. Ein geworfener Fehler trägt das Kommando, die verstrichene Zeit und das gerissene Budget; Buns Hook-Timeout trägt nichts davon. Dasselbe Prinzip wie im Abschnitt darüber — der Cap ist ein Auffangnetz, das Budget ist das, was meldet — nur eine Ebene weiter außen, auf einen Hook angewandt.
Die Größe ist eine Messung, keine Schätzung. Miss den Hook unter der Last, die ihn tatsächlich umbringt (mehrere Kopien der Datei gleichzeitig laufen zu lassen ist der billigste Weg dorthin), lass dann ein Vielfaches des schlechtesten Werts stehen und schreib die Zahlen neben die Konstante — damit die nächste Person ein gemessenes Budget von einem unterscheiden kann, das so lange verdoppelt wurde, bis das Rot weg war.
Echte Arbeit in einem Test-Body, gegen ein Limit, das niemand gesetzt hat
Abschnitt betitelt „Echte Arbeit in einem Test-Body, gegen ein Limit, das niemand gesetzt hat“Dasselbe Limit, eine Ebene weiter innen. tests/unit/CoreStaticImports.test.ts
sichert die Invariante aus #1005 — import { ActorSystem } darf Fastify niemals
statisch erreichen — indem es den statischen Import-Graphen der Quellen abläuft.
Dieser Lauf stand im Test-Body: 148 Dateien, 1,28 MiB Quelltext, 29 ms auf
unbeschäftigter Maschine. Ein vollständiger bun test --coverage-Lauf hat
daraus 6 723,89 ms gemacht (#1392):
(fail) core static import closure (#1005) > ActorSystem never statically reaches fastify [6723.89ms] ^ this test timed out after 5000ms.Rund 230x — bei einer Datei, die allein 276 ms braucht. Die Invariante stand nie in Frage, die Maschine war beschäftigt.
Keines der beiden Mittel von oben passt, und danach zu greifen ist die Falle. Ein drittes Argument bemisst ein Fehlerbudget: ein Warten, das ablaufen und ein Label ausgeben soll. Ein Closure-Lauf hat kein Budget — er ist begrenzte Arbeit, die immer fertig wird, also gibt es nichts zu melden und keine ehrliche Zahl, die man gegen eine Spanne von 230x wählen könnte. Gestaffelte Budgets brauchen eine Spawn-Grenze, damit die innere Operation ihr eigenes Timeout tragen kann — die gibt es hier nicht.
Das Mittel ist, die Arbeit ganz von der Uhr zu nehmen. Modul-Scope hat gar keinen Test-Timeout:
// Walked once, here, and not inside the tests that assert on it.const coreClosure = staticClosure('src/ActorSystem.ts');
describe('core static import closure', () => { test('ActorSystem never statically reaches fastify', () => { const reached = [...coreClosure.files].filter((f) => f.endsWith('FastifyBackend.ts')); expect(reached).toEqual([]); // the body is an assertion, nothing more });});Das ist gemessen, nicht angenommen: Eine Fixture mit 6 s synchroner Arbeit im
Modul-Scope läuft durch, während dieselben 6 s im Test-Body bei 5 000 ms
abgebrochen werden. Es ist außerdem das, was die übrigen Repo-Datei-Prüfungen
hier längst tun — AwaitConditionBudgets und WorkflowHygiene lesen den Baum
im Modul-Scope und halten ihre test()-Bodies bei Assertions, und
NoDeadConfigKeys berechnet seine ganze Perturbationsmatrix, jedes Blatt der
reference.conf gegen jeden registrierten Leser, ebenfalls im Modul-Scope. Die
beiden CoreStaticImports-Bodies fielen von
29,15 ms und 1,24 ms auf 0,41 ms und 0,04 ms, womit dieselbe Last bei rund
95 ms gegen den Cap landet.
Der Preis ist, dass ein Wurf im Modul-Scope die ganze Datei umwirft statt eines einzelnen Tests. Für eine Prüfung, die den Baum liest und über das Gefundene urteilt, ist das die richtige Seite des Tauschs — die drei Geschwister oben gehen ihn längst ein.
Eine Warnung zum Reproduzieren dieser Familie. Der Rat aus dem vorigen Abschnitt — mehrere Kopien der Datei gleichzeitig laufen zu lassen — überträgt sich hier nicht. Gemessen: Die Datei vor dem Fix lief unter 12 gleichzeitigen CPU-Lastprozessen weiterhin in 31,45 ms durch. Externe Last konkurriert mit gespawnter Arbeit; Arbeit innerhalb des Bun-Prozesses wird durch dessen eigenen Heap, Garbage Collection und Coverage-Zähler langsam, und die stellt nur ein echter Lauf der ganzen Suite her. Klär den Mechanismus stattdessen per Messung — die Modul-Scope-Fixture oben entscheidet ihn in einem einzigen Lauf, ohne den Flake je zu reproduzieren.
Buns Timer-Quantum — die frühe Hälfte ist erledigt
Abschnitt betitelt „Buns Timer-Quantum — die frühe Hälfte ist erledigt“Die Standard-Timer-Auflösung unter Windows ist 15,625 ms, und Buns Event-Loop
entschied in 1.3 auf dieser Tick-Grenze, dass ein Timer fällig ist — ein
setTimeout, dessen Deadline knapp unter einem Tick-Vielfachen lag, feuerte
also einen ganzen Tick zu früh. Ein setTimeout(30) wurde auf einer
unbeschäftigten Maschine mit 18,67 ms gemessen; 30 ms war pathologisch, weil es
knapp unter 2 × 15,625 liegt.
Bun 1.4 hat das behoben. Neu gemessen am 08.09.2026, 60 Stichproben bei je
5, 20, 30 und 60 ms: kein einziges Feuern unter dem Nominalwert, und die
30-ms-Zeile kam mit minimal 30,04 ms zurück. minimumElapsedMs() gibt daher
kein Quantum mehr her — sein Spielraum gilt nur noch der Verspätung, und
tests/util/TimerTolerance.ts trägt beide Messungen, denn eine Toleranz, die
nur festhält, was heute gilt, erklärt nicht, warum es sie gibt.
Eine Folge, die zu nennen sich lohnt, weil sie Arbeit streicht: ein 30-ms-Sleep ist kein zu vermeidender Wert mehr. Er stand auf der Liste der Dinge, die aus der Suite gefegt werden sollten; der Sweep entfällt, weil sein Grund weg ist und 44 Stellen für eine Zahl umzuschreiben, die sich jetzt benimmt, nichts einbrächte.
Die späte Hälfte ist nicht verschwunden, und sie ist die wichtigere. Eine sichere Obergrenze gibt es weiterhin nicht — derselbe 30-ms-Timer wurde unter CPU-Last mit 201 ms gemessen, Verspätung ist das, was der OS-Scheduler entscheidet, und eine Grenze, die locker genug ist, das zu überleben, kann die geprüfte Verzögerung nicht mehr von einer längeren unterscheiden. Prüfe stattdessen virtuelle Zeit mit dem ManualScheduler, der inzwischen fast überall hinreicht, wo das Framework wartet.
Dispatcher-Hop zwischen Warten und Prüfen
Abschnitt betitelt „Dispatcher-Hop zwischen Warten und Prüfen“Oben beschrieben. Das Erkennungsmerkmal: er ist isoliert nie reproduzierbar — bei keinem Poll-Intervall, auch nicht unter CPU-Last — und fällt nur innerhalb eines großen Parallel-Laufs um, wo die Macrotask-Queue verstopft genug ist, dass sich die Reihenfolge umdreht. Verbring keinen Nachmittag mit Reproduktionsversuchen; lies die beiden Zustände und frage, ob dazwischen eine Nachricht läuft.
Port-Kollisionen und Filesystem-Races
Abschnitt betitelt „Port-Kollisionen und Filesystem-Races“Beides geklärt — und wissenswert, weil ein neuer Test beides wieder einschleppen kann.
- Ports. Binde
0, lies den zugewiesenen Port vom Listener zurück und gib diesen an jeden Client im Test. Ein fest verdrahteter Port ist eine Kollision, die auf eine zweite Suite wartet. - Temp-Verzeichnisse.
mkdtempoder einrandomUUID-Suffix pro Test, niemals ein geteilter Fixture-Pfad. Rund zwei Dutzend Suites machen das heute; kopiere eine der Object-Storage-Suites, wenn du ein Muster brauchst.
Eine Assertion über prozessweiten Zustand
Abschnitt betitelt „Eine Assertion über prozessweiten Zustand“Die einzige Familie, in der überhaupt kein Timing steckt — und damit die, die ein Wiederholungslauf am schlechtesten diagnostiziert: Der Test hat über sein eigenes Objekt recht und über seinen Geltungsbereich unrecht.
bun test führt den ganzen Baum in einem Prozess aus, also teilen sich alle
Suites darin jede static-Collection. Eine Assertion über den Inhalt einer
solchen ist eine Assertion über alles, was vorher lief:
// ✗ InMemoryTransport.registry ist eine `private static Map`, und peers() gibt// jeden Eintrag außer sich selbst zurück — das sagt also „nirgends in diesem// Prozess ist ein anderer Transport registriert". 75 Testdateien erzeugen einen.await transportA.shutdown();expect(transportA.peers()).toEqual([]);// ✓ der Übergang, den dieser Test ausgelöst hat, über einen lebenden Peer gelesenawait transportA.shutdown();expect(transportB.peers().some((peer) => peer.port === 40501)).toBe(false);Die Signatur ist unverkennbar, sobald man sie kennt: läuft isoliert durch, fällt
nur im vollen Lauf um, und keine Menge Warten ändert etwas — weil nichts
unterwegs ist. Frage, was der Nenner der Assertion ist. Ist es ein
static-Feld, eine modulweite Registry oder ein prozessweiter Zähler, dann
verenge sie auf den Eintrag, der diesem Test gehört.
Ein Test, der davon abhängt, nach einem anderen zu laufen
Abschnitt betitelt „Ein Test, der davon abhängt, nach einem anderen zu laufen“Das Geschwister des Eintrags darüber — und das, was ein Wiederholungslauf gar
nicht finden kann: Ein Wiederholungslauf wiederholt dieselbe Reihenfolge. Nur
ein Shuffle stellt die Frage, und bun test --seed=N impliziert --randomize
und reproduziert genau eine Reihenfolge:
bun test --seed=413044451Vier Suites fielen um, als das zum ersten Mal gefragt wurde — in drei Formen.
Ein Wert, der von einem Test in den nächsten getragen wird. Der Block
meinte „die Fixture bootet einmal, nicht einmal pro Test” und sagte das, indem
er in einem Test schrieb und im nachfolgenden Geschwister las. Gemischt lief
der Leser zuerst und verglich gegen ein ungeschriebenes null.
// ✗ die Prämisse ist die Reihenfolge des eigenen Blockslet observed: ActorSystem | null = null;test('returns a live system', () => { observed = sys(); });test('returns the SAME instance', () => { expect(sys()).toBe(observed); });// ✓ gegen das vergleichen, was der Block gebootet hat — das sieht jeder Testlet booted!: ReturnType<typeof sys>;beforeAll(() => { booted = sys(); });test('returns the SAME instance the block booted', () => { expect(sys()).toBe(booted); });Ein Modul-Mock, der seine Datei überlebt hat. mock.restore() macht
mock.module() nicht rückgängig — ein Modul-Mock ist prozessweit und
dauerhaft. Eine Datei, die node:zlib ersetzt, um eine Fähigkeit als abwesend
erscheinen zu lassen, reicht das an die nächste Datei weiter. Zwei Suites in
tests/unit/persistence/object-storage/ brachten einander zu Fall, je nachdem,
in welche Richtung der Shuffle sie stellte. Also: das echte Modul vor dem
Mocken schnappschussen, es im afterEach zurücklegen und alles zurücksetzen,
was der Produktivcode daraus memoisiert hat:
const REAL_NODE_ZLIB = { ...nodeZlibModule };
afterEach(() => { mock.module('node:zlib', () => REAL_NODE_ZLIB); resetCompressionCache();});Die beforeEach-Hälfte gehört genauso dazu: Ein Memo, das aus der vorherigen
Datei geerbt wurde, ist genauso falsch wie eines, das an die nächste durchsickert
— und nur eines von beiden ist die Schuld der eigenen Datei. Auf beiden Kanten
zurücksetzen.
Das repariert die Datei, die geleckt hat. Für die Datei, die verschoben wurde, tut es nichts — und genau dort landete der Schaden: Drei Fälle, die die Allokationszeit-Schranke aus #580 festnageln, liefen weiter auf einer Sprosse, die gar keine solche Schranke hat, und prüften dort deren Sicherheitseigenschaft. Dass sie umfielen statt still durchzulaufen, war Glück — das Ende der Fehlermeldung war das Einzige, was „abgelehnt vor der Allokation” von „allokiert, dann abgelehnt” trennte, und eine anders formulierte Assertion wäre vom falschen Pfad erfüllt worden.
Eine Suite, die eine aufgelöste Fähigkeit nur benutzt, sollte deshalb sagen können, welche sie bekommen hat — und das einmal vorab prüfen:
beforeAll(async () => { expect(await zstdDecompressorRung()).toBe('node-zlib');});Ein falscher Pfad ist dann ein Fehlschlag, der die Ursache benennt, statt fünf Meldungs-Abweichungen, die es nicht tun. Die allgemeine Form: Ist das Thema eines Blocks eine Eigenschaft einer Implementierung hinter einem Resolver, dann muss der Resolver sagen können, welche Implementierung geantwortet hat — sonst prüft der Block genau das, was er erst herstellen will.
Eine feste Anzahl Microtask-Runden. Ein Test stieß eine Operation an, ohne
sie abzuwarten, ließ zwei Promise.resolve() verstreichen und prüfte dann, dass
ein lazy importierter SDK-Client konstruiert worden war. Das ist eine Wette
darauf, wie viele Runden ein dynamisches import() braucht — eine Zahl, wenn
der Specifier schon in der Modul-Registry liegt, und eine andere, wenn dies die
erste Auflösung im Lauf ist.
// ✗ zwei Runden sind eine Vermutung über den Zustand der Modul-Registryvoid backend.list({ prefix: '' }).catch(() => {});await Promise.resolve(); await Promise.resolve();expect(clientsConstructed.length).toBe(1);// ✓ eine abgeschlossene Operation hat den Client genauso konstruiertexpect(await backend.list({ prefix: '' })).toEqual([]);expect(clientsConstructed.length).toBe(1);Beide Per-Commit-Suites mischen jetzt, mit einem Seed, den der Workflow zieht
und ausgibt. Er wird dort gezogen und nicht bun überlassen, und zwar mit
Absicht: bun meldet seinen Seed im abschließenden Summary-Block, und unter
GitHub Actions hört es auf, diesen Block zu drucken, und meldet die Summen out
of band — dieselbe Falle, die einmal aus einer unlesbaren Pass-Zahl ein grünes
tests-0 of 0-Badge gemacht hat. Ein Seed, den niemand lesen kann, ist keine
Reproduktion.
Offene Einträge
Abschnitt betitelt „Offene Einträge“Tests, die zeitweise umfallen und deren Ursache noch nicht geklärt ist. Ursachen auszuschließen ist nicht dasselbe wie eine zu belegen, deshalb stehen sie hier ohne Urteil statt mit einer Vermutung. Einer der fünf ist nicht mehr offen — seine Ursache ist unten belegt — und bleibt in der Tabelle, weil er der Eintrag ist, den ein Lauf der ganzen Suite am ehesten wieder nennt:
| Test | Datei | Sleep ausgeschlossen? |
|---|---|---|
stoppingStrategy stops a failing child | tests/Actor.test.ts | Ja — Warten umgestellt |
shards rebalance when a node leaves | tests/Cluster.test.ts | Ja — Warten umgestellt |
explicit seeds bypass discovery | tests/ClusterBootstrap.test.ts | Ja — Deadline-Schleife umgestellt |
peers list is empty after shutdown | tests/unit/InMemoryTransport.test.ts | Ja — der Test ist vollständig synchron |
partition + heal flips reachability without dropping the workers | tests/unit/testkit/ParallelMultiNodeSpec.test.ts | Ja — die Datei hat kein Warten zum Umstellen |
Ports und Dateisystem-Pfade sind für alle fünf ausgeschlossen, und „der Sleep war zu kurz” ebenfalls — aber nicht bei jedem mit demselben Argument, und der Unterschied sagt, wo als Nächstes zu suchen ist:
-
Drei hatten ein Warten, und es wurde umgestellt.
Actor,ClusterundClusterBootstrapwarteten je auf eine feste Verzögerung —ClusterBootstrapüber eine handgeschriebene Deadline-Schleife, die still durchfiel — und warten jetzt auf den Zustand, den die Assertion liest. -
Zwei hatten nie eines.
peers list is empty after shutdownist von Anfang bis Ende synchron: Jeder Schritt ist awaited, es gibt kein Polling und keine Verzögerung. Seine Ursache ist überhaupt nicht Timing — es ist eine prozessweite Assertion, und die ist geklärt und nicht offen.InMemoryTransport.registryist eineprivate static Map, undpeers()gibt jeden Eintrag darin außer sich selbst zurück.expect(transportA.peers()).toEqual([])behauptet also, dass nirgends im Prozess ein anderer Transport registriert ist. 75 Testdateien erzeugen einen. Eine einzige Suite, die einen registriert zurücklässt — oder derenshutdown()noch nicht gelaufen ist — bringt diesen Test zu Fall, und nur in einem Lauf der ganzen Suite, was genau die beobachtete Signatur ist.Das ist eine fünfte Familie, und man erkennt sie an ihrer Form: Eine Assertion über eine
static-Collection prüft den ganzen Prozess und nicht die Einheit. Der Test ist inzwischen auf den Übergang verengt, den er auslöst — dass diese Adresse die Registry verlassen hat, gelesen über einen anderen lebenden Transport — und heißt jetztshutdown removes the transport from a live peer's view; der alte Name bleibt in der Tabelle oben, weil das die Identität ist, die die Messung erfasst hat.Wissenswert, warum die Verengung nicht bloß aufgeräumter ist. Entfernt man die Zeile
registry.delete(…)ausInMemoryTransport.shutdown(), bleibt die alte Assertion grün, wenn sie allein läuft:peers()filtert sich selbst heraus, A’s eigene übrig gebliebene Registrierung ist für sie also unsichtbar. Rot wurde sie nur innerhalb ihrer eigenen Datei, und nur weil die Tests darüber Registrierungen zurücklassen — sie hat also ihre Geschwister erkannt und nicht ihren Gegenstand. Die verengte Form wird bei dieser Mutation in beiden Fällen rot.ParallelMultiNodeSpec.test.tsenthält überhaupt kein Warten auf eine feste Verzögerung; es wartet über die Budgets vonspec.awaitMembers/spec.awaitMemberStatus.Für den zweiten gibt es inzwischen eine Messung statt einer Vermutung. Ein lokaler Lauf der drei quarantänisierten Suites mit 15 Wiederholungen (2026-08-18) hat
partition + healeinmal erwischt, und der Fehlschlag ist überhaupt keine Assertion:InvalidStateError: Worker has been terminatedat postMessage (src/runtime/worker/WebWorkerBackend.ts:88)at postMessage (src/testkit/ParallelMultiNodeSpec.ts:409)at onMessage (src/testkit/internal/MultiNodeBroker.ts:90)Der Broker hat eine Nachricht an einen Worker weitergereicht, der schon beendet war, und die Ablehnung wurde dem Test zugeschrieben, der gerade lief. Das ist ein Teardown-Race im Harness, keine Zeit-Wette im Test — also kann kein Warten, welcher Form auch immer, die Ursache gewesen sein.
Dieser Trace kann nicht mehr entkommen.
MultiNodeBroker.onMessageroutet inzwischen innerhalb desselben try/catch, das der Produktions-Broker seit #701 trägt: Ein Ziel-Port, der wirft — der Fall, der dort ankommt, ist ein voncrash()bereits beendeter Worker — zählt als das nicht zustellbare Ziel, das er ist, und der Frame wird verworfen. Das Race selbst bleibt unverändert; weg ist der Teil, der es zu einem Flake gemacht hat, nämlich ein unbeteiligter Test, der daran scheitert. Lies den Eintrag oben als Aufzeichnung des Symptoms, nicht als etwas, das noch zu reproduzieren wäre.
Genau dafür lohnt es sich, einen offenen Eintrag aufzuschreiben statt zu raten:
Ein Eintrag, dessen Sleep umgestellt wurde, und einer, der nie einen hatte,
führen zu verschiedenen nächsten Schritten, und nur die Zahl im summary.json
unterscheidet „einmal gesehen” von „oft gesehen”. Trag die Zahl hier nach,
statt von vorn anzufangen.
Die Quarantäne, und was sie gekostet hat
Abschnitt betitelt „Die Quarantäne, und was sie gekostet hat“Monatelang liefen drei Suites in keinem einzigen CI-Job.
ACTOR_TS_SKIP_FLAKY_MNS=1 stand in test.yml, multi-runtime.yml und
publish.yml, und drei Dateien übersprangen sich selbst, wenn es gesetzt war:
tests/multi-node/LeaseMajority.test.tstests/multi-node/ParallelPubSub.test.tstests/unit/testkit/ParallelMultiNodeSpec.test.ts
Die angegebene Begründung: Bun könne auf GitHubs Hosted Runnern nach dem ersten
Worker-Test keine funktionsfähigen Worker-Threads mehr starten — sie starten,
machen den Handshake und laufen dann nie — und dieselbe Ressourcenknappheit
verzögere den Renewal-Timer von LeaseMajority über die Lease-TTL hinaus, so
dass beide Seiten einer Partition die Lease bekämen und der Test ein falsches
Split-Brain sähe.
Alle drei laufen wieder in CI, und wie es dazu kam, ist mehr wert als die Tatsache selbst.
- Die beiden Worker-Thread-Suites haben es sich erarbeitet, durch Messung.
Das Ausstiegskriterium waren vierzehn aufeinanderfolgende grüne Nächte von
nightly-flakes.yml, das genau diese Suites ohne das Flag ausführt. Erreicht wurden einundzwanzig — 63 Ausführungen aufubuntu-latest, kein einziger Hänger. Das Kriterium war erfüllt, und niemand hatte nachgesehen — genau das Versagen, das der Workflow über sich selbst vorhergesagt hatte: „Nichts akkumuliert die Serie. Sie wird von einem Menschen gezählt, der diese Annotations liest — dasselbe Versagen, das die Quarantäne überhaupt erst dauerhaft gemacht hat.” LeaseMajoritywar nie ein Runner-Problem. Die Ursache war ein Produktdefekt in der Split-Brain-Auflösung: eine Partition, die Peer für Peer erkannt wurde, wurde als Folge von Mehrheits-Entscheidungen aufgelöst statt als eine Gleichstands-Entscheidung — beide Hälften überlebten, und die Lease wurde überhaupt nie angefragt. Jede Hypothese über Renewal-Timer und TTLs sah auf Maschinerie, die nicht gelaufen war. Behoben durch das Stabilitätsfenster in Downing-Strategien; die Suite geht von 8 Fehlschlägen in 15 Läufen auf 0 in 30.
Zwei Mechanismen sind daraus entstanden, und die sind der Teil zum Merken.
- Eine Umgebungsvariable darf nicht entscheiden, ob ein Test läuft.
tests/unit/ci/NoEnvironmentGatedSkips.test.tsweist das zurück, denn genau das ist es, was ein Workflow setzen kann — und es zu setzen ist der Weg, auf dem aus einer roten Suite eine abwesende wird. Ein Capability-Probe ist in Ordnung und die Form, zu der man stattdessen greift:available ? describe : describe.skipfragt die Maschine, was sie kann, und kein Workflow kann das für sie beantworten. Ein Eintrag in der Allow-List dieses Guards braucht eine Begründung, warum er keinen Fehlschlag verstecken kann. - Jeder Job trägt
timeout-minutes. Eine Suite, die keinen Fortschritt mehr macht, fällt jetzt innerhalb einer Stunde um, statt GitHubs Sechs-Stunden-Default aufzubrauchen — genau das Versagen, mit dem die Quarantäne ursprünglich begründet wurde.
nightly-flakes.yml führt diese drei Suites weiterhin einzeln aus, dreimal pro
Nacht. Es ist jetzt der Regressions-Guard und nicht mehr die
Bewährungskommission: eine durch Messung widerlegte Behauptung bleibt nur so
lange widerlegt, wie jemand weitermisst.
Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Testing-Überblick — wie man einen Test schreibt, der gar nicht erst flakt.
- ManualScheduler — virtuelle Zeit prüfen statt der Wanduhr.
- TestProbe — auf eine Nachricht warten statt auf eine Dauer.
- ParallelMultiNodeSpec — das Worker-Thread-Harness, das zwei der quarantänisierten Suites ausüben.
