MultiNodeSpec
MultiNodeSpec lässt N Cluster-Nodes innerhalb eines
Test-Prozesses laufen. Jeder ist ein echtes ActorSystem; sie
kommunizieren via einen In-Process-Transport (kein TCP). Nützlich zum
Testen von Cluster-Verhalten — Sharding, Singletons, Gossip-
Konvergenz, Failover — ohne Docker.
import { MultiNodeSpec, TestProbe } from 'actor-ts/testkit';
// Jeder Rollenname ist ein Node — und zugleich dessen System-Name.const spec = new MultiNodeSpec({ roles: ['a', 'b', 'c'] });await spec.start();await spec.awaitMembers('a', 3); // warten, bis der Cluster konvergiert
// Das ActorSystem jedes Nodes via systemFor(role) erreichen:const node2 = spec.systemFor('b');
// Actor auf einem bestimmten Node spawnen und mit einer Probe asserten:const probe = new TestProbe(spec.systemFor('a'));const remote = node2.spawnAnonymous(Worker);
remote.tell({ kind: 'do', replyTo: probe });await probe.expectMessage({ kind: 'done' });
await spec.stop();Wann nutzen
Abschnitt betitelt „Wann nutzen“Drei primäre Fälle:
- Cluster-Verhalten testen — Sharding-Rebalances, Singleton-Failover, Gossip-Konvergenz — diese ohne echtes Netzwerk-Setup verifizieren.
- Verteilte Bugs reproduzieren — leichter zu isolieren, wenn der gesamte Cluster in einem Prozess läuft.
- CI-freundliche Cluster-Tests — schnell (sub-Sekunde), kein Docker, keine Ports.
Für Tests, die echte Parallelität brauchen (echte OS-Threads — nebenläufige Journal-Schreibvorgänge, Scheduler-Interleaving), nutze ParallelMultiNodeSpec. Für echtes TCP/TLS oder Cross-Host-Latenz nutze einen externen Docker-Compose-Cluster.
Konfiguration
Abschnitt betitelt „Konfiguration“type MultiNodeSpecOptionsType = { roles: ReadonlyArray<string>; // ein Node pro Rolle; müssen eindeutig sein seedRoles?: ReadonlyArray<string>; // Bootstrap-Seeds — Default [roles[0]] addresses?: Record<string, { host: string; port: number }>; failureDetector?: ClusterOptionsType['failureDetector']; gossipIntervalMs?: number; // Default 100 (vs. 1 s in Produktion) awaitTimeoutMs?: number; // Default 10_000 — wie lange await*-Helfer warten logLevel?: LogLevel; // Default: ein leiser NoopLogger downing?: (role: string) => DowningProvider | undefined; failureDetectorAutoDown?: boolean; // Default ungesetzt = das ausgelieferte true stableAfterMs?: number; // Default 100 (vs. 20 s in Produktion)};| Feld | Zweck |
|---|---|
roles | Node-Liste — jeder Eintrag ist ein Node, und der String ist zugleich dessen System-Name. Müssen eindeutig sein. |
seedRoles | Welche Rollen als Bootstrap-Seeds dienen. Default ist die erste Rolle. |
addresses | Per-Rolle Host/Port-Overrides. Automatisch vergeben, wenn ausgelassen. |
failureDetector | Failure-Detector-Overrides — Tests ziehen diese meist enger, damit Crashes schnell erkannt werden. |
gossipIntervalMs | Gossip-Runden-Intervall. Default 100 ms. |
awaitTimeoutMs | Default-Timeout für die await*-Helfer. Default 10 s. |
logLevel | Log-Level — standardmäßig leise. |
downing | Per-Rolle Split-Brain-Resolver-Factory. |
failureDetectorAutoDown | Ob der Failure Detector jedes Nodes einen Peer entfernt, den er für down erklärt. Ungesetzt bleibt es beim ausgelieferten true: Eine abgestürzte Rolle wird bei down-after entfernt, ein Spec, der Crash-Failover ohne downing-Strategie prüft, braucht also nichts weiter. false ist das Opt-out, das ein Spec setzt, um eine abgestürzte Rolle auf unreachable geparkt zu sehen, wo sie Mitglied bleibt. Der downing-Provider einer Rolle entscheidet deren Entfernungen, was immer dieser Schalter sagt. |
stableAfterMs | Wie lange das Bild stillstehen muss, bevor downing gefragt wird. Default 100 ms — die ausgelieferten 20 s sind das Doppelte von awaitTimeoutMs, ein Spec mit dem Produktionswert liefe also ins Timeout, bevor sein Resolver überhaupt gefragt wurde. |
Übergib ein einfaches Objekt wie gezeigt, oder baue es fluent mit
MultiNodeSpecOptions.create().withRoles(['a', 'b', 'c']).
Rollen, Seeds und Adressen
Abschnitt betitelt „Rollen, Seeds und Adressen“Jeder Eintrag in roles ist ein eigener Node — der String
ist die Identität dieses Nodes und sein ActorSystem-Name, muss
also eindeutig sein (der Konstruktor wirft bei Duplikaten oder
leerer Liste). Standardmäßig ist die erste Rolle der einzige
Bootstrap-Seed; überschreibe das mit seedRoles:
const spec = new MultiNodeSpec({ roles: ['seed', 'worker-1', 'worker-2'], seedRoles: ['seed'],});await spec.start();Ports werden automatisch auf 127.0.0.1 vergeben; fixiere
bestimmte via addresses, wenn ein Test feste Endpunkte braucht:
const spec = new MultiNodeSpec({ roles: ['a', 'b'], addresses: { a: { host: '127.0.0.1', port: 2551 } },});Was geteilt wird
Abschnitt betitelt „Was geteilt wird“Alle Nodes teilen sich:
- Einen gemeinsamen In-Process-Nachrichtenbus — sie können miteinander reden.
- Dasselbe Gossip-Protokoll — Membership konvergiert.
- Unabhängige Actor-Systeme — separate Dispatcher, Scheduler, Supervisor-Bäume.
Das heißt:
- Echte Cluster-Semantik — Mitglieder kommen hoch, Gossip konvergiert, Failure-Detector beobachtet, Sharding rebalancet.
- Keine Serialisierung — Nachrichten zwischen „Nodes” werden per Referenz übergeben (in-process). Kein Fit zum Testen serialisierungs-abhängigen Verhaltens.
Failover-Tests
Abschnitt betitelt „Failover-Tests“Zwei Wege, einen Node herunterzunehmen: crash(role) reißt
dessen Transport abrupt weg (Peers erkennen das über den
Failure-Detector), und leave(role) führt einen sauberen
Cluster-Austritt durch.
// Singleton-Failover verifizieren:const spec = new MultiNodeSpec({ roles: ['a', 'b', 'c'], failureDetector: { heartbeatIntervalMs: 50, unreachableAfterMs: 200, downAfterMs: 400 }, // Keine Downing-Strategie: Das ausgelieferte auto-down entfernt den abgestürzten Node bei downAfterMs.});await spec.start();await Promise.all([ spec.awaitMembers('a', 3), spec.awaitMembers('b', 3), spec.awaitMembers('c', 3),]);
// ... den Singleton auf jedem Node starten ...
// Den aktuellen Host ermitteln, dann crashen:const host = spec.clusterFor('a').leader().toNullable();await spec.crash('a');
// Warten, bis die Überlebenden ohne 'a' neu konvergieren:await spec.awaitMembers('b', 2);
// ... asserten, dass der Singleton zu einem Überlebenden umgezogen ist ...
await spec.stop();crash(role) entfernt den Node abrupt; die Detectors der anderen
markieren ihn nach unreachableAfterMs als unreachable und
erreichen bei downAfterMs das Urteil down. Was dieses Urteil
bewirkt, entscheidet der Spec: Per Default entfernt der Detector den
Node, wie oben — failureDetectorAutoDown ungesetzt bleibt beim
ausgelieferten true; die downing-Strategie einer Rolle entscheidet
stattdessen; und mit failureDetectorAutoDown: false ohne Strategie
bleibt der Node Mitglied auf unreachable — kein Shard wird neu
vergeben, und kein entfernter Watcher bekommt Terminated. Die await*-Helfer ersetzen
fragile setTimeout-Schlafphasen — sie pollen, bis die Bedingung gilt
(oder werfen nach awaitTimeoutMs).
Einen Node neu starten
Abschnitt betitelt „Einen Node neu starten“restart(role) bringt eine Rolle an derselben Adresse als neuen Prozess
zurück — die Form eines Pod-Austauschs. Das alte System wird gecrasht und
beendet, ein frisches System mit Cluster tritt an seiner Stelle mit einer
neuen Inkarnation bei, und die anderen Mitglieder sehen den alten Lauf enden,
bevor der neue beitritt. withNodeSetup läuft auf jedem Node nach seinem
Beitritt und erneut auf einem neu gestarteten, sodass die Sharding-Typen,
Singletons und Abonnements, die ein Test startet, auch auf dem neuen Node
existieren.
const spec = new MultiNodeSpec(MultiNodeSpecOptions.create() .withRoles(['a', 'b', 'c']) // Läuft auf jedem Node, sobald er beigetreten ist — und erneut auf einem neu gestarteten. .withNodeSetup((role, system, cluster) => { cluster.sharding.start(shardingOptions); }));await spec.start();
const oldRun = spec.clusterFor('a').selfAddress.incarnation;await spec.restart('a'); // gleiche Adresse, neuer Prozessawait spec.awaitMembers('b', 3);expect(spec.clusterFor('a').selfAddress.incarnation).not.toBe(oldRun);Die Seeds des neu gestarteten Nodes sind die anderen laufenden Rollen, ein neu
gestarteter Seed tritt also wieder dem Cluster bei, den er gegründet hat. Mit
restart(role, { seeds: [] }) gründet er stattdessen einen eigenen — die
Gabelung, um die es in
Issue #1176 geht.
Referenzen aus systemFor / clusterFor von vor dem Neustart benennen den
alten Node; danach erneut abfragen.
Ein Netz, das schlecht funktioniert
Abschnitt betitelt „Ein Netz, das schlecht funktioniert“partition und crash beschreiben ein Netz, das perfekt oder durchtrennt ist.
Dazwischen liegt jeder Zustand, in dem ein Cluster tatsächlich läuft: ein
Fünftel der Gossip-Pushes verloren, Frames, die einander überholen, ein Peer,
der langsam statt tot ist. degrade(roleA, roleB, profile) ist diese Mitte,
restore(roleA, roleB) nimmt sie zurück.
Eine partition, die downAfterMs überdauert, verhält sich wie in Produktion:
Ohne downing-Strategie entfernt jede Seite die andere und läuft allein weiter,
und ein späteres heal bringt die beiden nicht wieder zusammen
(Issue #930). Ein Spec, der
eine Seite gewinnen lassen will, gibt den Rollen über downing eine Strategie.
const spec = new MultiNodeSpec(MultiNodeSpecOptions.create() .withRoles(['a', 'b', 'c']) .withScheduler(new ManualScheduler()) .withFaultSeed(20_231));
await spec.start();
// Der Cluster bildet sich auf einem sauberen Netz, danach wird es schlechter.spec.degrade('a', 'b', { dropProbability: 0.2, // ein Fünftel der Frames kommt nie an duplicateProbability: 0.1, // ein Zehntel kommt doppelt an reorderWindow: 4, // bis zu vier Frames dürfen einander überholen latencyMs: 50, // auf dem Scheduler der Spec gemessen});
await spec.advanceUntil( () => spec.clusterFor('a').getMembers().filter((m) => m.status === 'up').length === 3, { budgetMs: 60_000, description: 'die Sicht konvergiert trotz der Verluste' },);
spec.restore('a', 'b');Jedes Feld ist optional und steht per Default auf „kein Fehler”, ein Profil
nennt also nur, was es ändert. degrade wirkt beidseitig wie partition; für
eine einseitige Verschlechterung greifst du zu
spec.faultsFor(role).degradeTo(address, profile).
Die Fehler sind deterministisch
Abschnitt betitelt „Die Fehler sind deterministisch“Jede Entscheidung stammt aus einem geseedeten Generator pro Node, gezogen in
Sende-Reihenfolge — und unter einem geteilten ManualScheduler ist diese
Reihenfolge selbst deterministisch. Ein rot gewordener Lauf reproduziert also
exakt, und die Timeout-Meldungen der Spec nennen den Seed dazu:
MultiNodeSpec: timeout after 10000 ms — awaitMembers(a, expected=3) — current: 2 Faults were injected on: a, b. Reproduce with withFaultSeed(20231).Das ist kein Detail. Ein nicht reproduzierbarer Chaos-Test ist ein
Flake-Generator; ein fester Seed macht den Unterschied — der Preis ist, dass die
Suite von sich aus keine neuen Netze mehr findet. Variiere den Seed bewusst
(eine Schleife über withFaultSeed), wenn die Frage „gilt das für viele Netze”
lautet und nicht „gilt das für das Netz, das kaputtging”.
latencyMs braucht einen Scheduler
Abschnitt betitelt „latencyMs braucht einen Scheduler“Eine Verzögerung von der Wanduhr würde genau die Timing-Abhängigkeit
zurückholen, die ManualScheduler beseitigen
soll — sie wird deshalb abgelehnt statt stillschweigend genommen: ein
latencyMs ungleich null ohne Scheduler wirft schon bei der Konstruktion. Die
anderen drei Fehler brauchen gar keine Uhr.
reorderWindow ist eine Tiefe, kein Shuffle
Abschnitt betitelt „reorderWindow ist eine Tiefe, kein Shuffle“Ein Fenster von n hält bis zu n Frames zurück und gibt sie als eine
permutierte Charge frei; ein Frame verschiebt sich also um weniger als n
Positionen. Genau diese Schranke ist der Punkt: ein Shuffle könnte einen Frame
ans Ende des Laufs permutieren und einen Test auf etwas warten lassen, das nie
kommt. Die letzte unvollständige Charge geben restore, stop und die nächste
volle Charge frei — kontinuierliches Gossip erledigt Letzteres von allein.
Es funktioniert auf jedem Transport
Abschnitt betitelt „Es funktioniert auf jedem Transport“FaultyTransport ist ein Dekorator: InMemoryTransport, MultiNodeTransport
und MessageChannelTransport bekommen dieselben Regler, ohne dass einer von
ihnen Fehler-Logik dazubekommt. Außerhalb einer Spec:
const link = new FaultyTransport(new InMemoryTransport(address), { dropProbability: 0.2 });Per-Node-TestProbe
Abschnitt betitelt „Per-Node-TestProbe“MultiNodeSpec hat keine Probe-Factory — konstruiere eine
TestProbe gegen das System des Nodes, den du beobachten willst:
const probeA = new TestProbe(spec.systemFor('a')); // Probe auf Node 'a'const probeB = new TestProbe(spec.systemFor('b')); // Probe auf Node 'b'Jede Probe ist an das Actor-System eines Nodes gebunden. Nützlich beim Testen von Routing — verifizieren, dass eine Nachricht auf dem erwarteten Node landet.
Sharding-Tests
Abschnitt betitelt „Sharding-Tests“Starte eine Sharding-Region auf jedem Node über dessen Cluster
— erreiche jede via clusterFor(role):
const spec = new MultiNodeSpec({ roles: ['a', 'b', 'c'] });await spec.start();await spec.awaitMembers('a', 3);
const startShardingOptions = StartShardingOptions.create<Command>() .withTypeName('entity') .withEntityActor(Entity) .withExtractEntityId((message) => message.id);const regions = spec.allRoles().map((role) => spec.clusterFor(role).sharding.start(startShardingOptions));
// Entities spawnen; verifizieren, dass sie sich über Nodes verteilen:for (const id of ['e1', 'e2', 'e3', 'e4', 'e5']) { regions[0].tell({ id, kind: 'wake-up' });}
await spec.stop();Der Koordinator des Frameworks verteilt Shards über die Nodes wie in einem echten Cluster.
Was MultiNodeSpec nicht testet
Abschnitt betitelt „Was MultiNodeSpec nicht testet“Wo es weitergeht
Abschnitt betitelt „Wo es weitergeht“- Testing — Überblick — das größere Bild.
- TestKit — Single-System- Testing.
- ParallelMultiNodeSpec — die Worker-Thread-Variante.
- Cluster — Überblick — was MultiNodeSpec simuliert.
