ParallelMultiNodeSpec
ParallelMultiNodeSpec ist die Worker-Thread-Variante
von MultiNodeSpec. Jeder „Node”
läuft in seinem eigenen worker_threads-Worker (oder einem
Web-Worker auf Bun/Deno), verbunden über einen In-Process-Broker.
Dieselbe Test-Form wie MultiNodeSpec, aber mit echten
OS-Threads, sodass Nebenläufigkeits-Bugs, welche die
single-threaded Variante überdeckt, auftauchen können.
import { ParallelMultiNodeSpec } from 'actor-ts/testkit';
const spec = new ParallelMultiNodeSpec({ roles: ['a', 'b', 'c'], scenarioModule: new URL('./my-scenario.ts', import.meta.url),});await spec.start();await spec.awaitMembers('a', 3);
// Das Worker-seitige Szenario über einen RPC ansteuern:const result = await spec.runIn('a', 'compute', { x: 42 });
await spec.stop();Wann nutzen
Abschnitt betitelt „Wann nutzen“Für Tests, die echte Parallelität brauchen:
- Echte Threads — fängt Races, die die In-Process-Variante auf einer einzelnen Event-Loop wegserialisiert (nebenläufige Journal-Schreibvorgänge, Scheduler-Thread-Interleaving).
- Serialisierung — jede Nachricht überquert eine Worker-Grenze via Structured Clone, sodass nicht-serialisierbare Payloads (Funktionen, Klasseninstanzen) hier genauso scheitern wie über eine echte Wire.
- Thread-Isolation — jeder Node hat seinen eigenen Heap und seine eigene Event-Loop.
Für die meisten Cluster-Tests ist MultiNodeSpec schneller + einfacher — nutze ParallelMultiNodeSpec nur, wenn single-threaded Tests den Fall nicht abdecken. Keine der beiden Varianten nutzt TCP; für echte Netzwerkbedingungen nutze einen externen Docker-Compose-Cluster.
Konfiguration
Abschnitt betitelt „Konfiguration“type ParallelMultiNodeSpecOptionsType = { roles: ReadonlyArray<string>; // ein Worker pro Rolle; müssen eindeutig sein seedRoles?: ReadonlyArray<string>; // Bootstrap-Seeds — Default [roles[0]] scenarioModule?: URL; // Modul, das jeder Worker lädt (setup + commands) scenarioInitDataFor?: (role: string) => unknown; // Per-Rolle-Daten für setup() addresses?: Record<string, { host: string; port: number }>; failureDetector?: Partial<FailureDetectorOptionsType>; failureDetectorAutoDown?: boolean; // Default ungesetzt = das ausgelieferte true gossipIntervalMs?: number; awaitTimeoutMs?: number; // Default 30_000 (Worker-Bootstrap ist langsamer) controlRpcTimeoutMs?: number; // Default 5_000 (ein Control-RPC) logLevel?: LogLevel; bootstrapModule?: URL; // überschreibt den gebündelten Worker-Bootstrap};| Feld | Zweck |
|---|---|
roles | Node-Liste — ein Worker pro Rolle; der String ist der System-Name des Workers. Müssen eindeutig sein. |
seedRoles | Welche Rollen als Bootstrap-Seeds dienen. Default ist die erste Rolle. |
scenarioModule | URL des Moduls, das jeder Worker importiert — es besitzt das actor-förmige Setup und die commands-Map, an die runIn dispatcht. |
scenarioInitDataFor | Per-Rolle-Daten, die an das setup(context) des Szenarios weitergereicht werden. |
failureDetector | Failure-Detector-Overrides. |
failureDetectorAutoDown | Ob der Failure Detector jeder Rolle 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, und genau das braucht ein Spec, der Crash-Failover prüft — dieser Spec hat keine Option für eine Downing-Strategie. false ist das Opt-out, unter dem eine abgestürzte Rolle als Mitglied auf unreachable bleibt und nichts sie je entfernt. |
awaitTimeoutMs | Default-await*-Timeout. Default 30 s — Worker-Bootstrap ist langsamer als in-process. |
controlRpcTimeoutMs | Wie lange ein einzelner Control-RPC (getMembers, getLeader, leave, runIn) unbeantwortet bleiben darf, bevor er unter Nennung der verstummten Rolle fehlschlägt. Default 5 s — bewusst viel kürzer als awaitTimeoutMs: Ein RPC, der nicht zurückkommt, heißt, dass der Worker feststeckt, und eine kurze Frist zeigt das, statt den Test hängen zu lassen. Beide werden mit dem Zeitfaktor skaliert. |
bootstrapModule | Überschreibt den gebündelten Worker-Einstiegspunkt (fortgeschritten) — übernimmt damit den Control-Channel, siehe den Vertrag weiter unten. Es gilt dieselbe Schreibweisen-Regel wie für jeden anderen Worker-Einstiegspunkt im Framework: eine absolute file:-URL ohne Host, die eine Datei benennt — genau das erzeugt new URL('./my-bootstrap.ts', import.meta.url). Ein data:-, blob:- oder entfernter Specifier, eine file:-URL mit Host oder mit einem Pfad, der mit // beginnt, oder ein Verzeichnis wird beim Konstruieren der Spec mit einem OptionsError abgelehnt. Ein schema-relatives file:worker.js dagegen nicht — und kann es auch nicht: Das Feld ist als URL typisiert, und new URL('file:worker.js') ist bereits file:///worker.js, bevor die Spec es sieht; diese Schreibweise wird nur dort abgelehnt, wo die Option auch eine Zeichenkette annimmt. |
Das Szenario-Modul
Abschnitt betitelt „Das Szenario-Modul“Jeder Worker joint den Cluster automatisch — die Harness besitzt
den ActorSystem- + Cluster-Bootstrap. Dein test-spezifischer
Actor-Code lebt in einem Szenario-Modul: einem schlichten
Modul, das einen optionalen setup(context)-Hook und eine
commands-Map exportiert. Der Worker importiert es per URL, führt
setup einmal nach dem Cluster-Join aus und dispatcht dann
runIn(role, command, args)-Aufrufe an das passende Kommando.
import type { ScenarioModule } from 'actor-ts/testkit';import { type ActorRef } from 'actor-ts';
export const setup: ScenarioModule['setup'] = (context) => { // context = { role, system, cluster, initData, state } context.state.counter = context.system.spawnAnonymous(Counter);};
export const commands: ScenarioModule['commands'] = { increment(args, context): void { (context.state.counter as ActorRef<Command>).tell({ kind: 'increment' }); }, // Kommandos dürfen jeden JSON-serialisierbaren Wert an die Harness zurückgeben: ping(): string { return 'pong'; },};Das Modul besitzt alles Actor-Förmige (Entity-Klassen, Sharding-Regionen, …). Die Harness tauscht mit ihm nur JSON-serialisierbare Kommando/Antwort-Paare aus — Closures können die Worker-Grenze nicht überqueren, weshalb Szenario-Code in einer eigenen, per URL geladenen Datei lebt statt inline im Test.
Der Vertrag für einen eigenen Bootstrap
Abschnitt betitelt „Der Vertrag für einen eigenen Bootstrap“Ein Szenario-Modul setzt auf dem gebündelten Bootstrap auf.
bootstrapModule ersetzt diesen Bootstrap vollständig — und übernimmt damit
auch den Control-Channel: das postMessage-Protokoll, über das die
Harness jeden Worker ansteuert, auf demselben Socket wie der
Cluster-Handshake. Es gibt vier Requests, und jede Antwort trägt den Namen
des Requests, den sie beantwortet, mit angehängtem -response:
type ControlRequestKind = | 'mns-test.query-members' // → 'mns-test.query-members-response' { reqId, members } | 'mns-test.query-leader' // → 'mns-test.query-leader-response' { reqId, leader } | 'mns-test.leave' // → 'mns-test.leave-response' { reqId, error? } | 'mns-test.run-command'; // → 'mns-test.run-command-response' { reqId, result, error? }Drei Regeln entscheiden, ob eine Antwort angenommen wird, und alle drei werden geprüft:
- Die
reqIdzurückspiegeln. Jeder Request trägt eine; die Antwort gibt dieselbe Zahl zurück. Daran schlüsselt die Harness ihre offenen Aufrufe. - Den passenden Kind verwenden. Die Harness bildet den Namen, den sie
akzeptiert, indem sie
-responsean den gesendeten Kind anhängt — eine wohlgeformte Payload unter einem anderen Namen ist keine Antwort. - Aus dem Worker antworten, der gefragt wurde. Eine Antwort auf die
Frage an Rolle
a, gepostet vom Worker der Rolleb, wird abgelehnt, selbst wenn Kind undreqIdbeide passen.
Eine Antwort, die eine davon verletzt, wird fallen gelassen, nicht
zurückgewiesen: Die Harness schreibt eine console.warn, die den verworfenen
Frame und den Aufruf benennt, zu dem diese reqId wirklich gehört, lässt den
Aufruf offen — falls die echte Antwort noch kommt — und lässt ihn 5 s später
mit einer Meldung scheitern, die Rolle und unbeantworteten Request nennt.
Nur die erste Regel galt schon immer. Vor dem Korrelations-Fix wurde eine
Antwort allein über die reqId zugeordnet, sodass ein Bootstrap, der unter
einem anderen Namen oder aus dem falschen Worker antwortete, zufällig
funktionierte — der Grund, warum dieser Vertrag hier steht statt nur
implizit zu gelten.
Die Worker ansteuern
Abschnitt betitelt „Die Worker ansteuern“Der Test kann die In-Memory-Actor eines Workers nicht direkt anfassen, also steuert er sie über die Harness:
// Ein Szenario-Kommando auf einer bestimmten Rolle aufrufen und das Ergebnis abwarten:await spec.runIn('a', 'increment');const reply = await spec.runIn<string>('a', 'ping'); // → 'pong'
// Die Cluster-Sicht jedes Workers inspizieren (JSON-Snapshots, keine Live-Objekte):const members = await spec.getMembers('a');const leader = await spec.getLeader('a');runIn(role, command, args?) ruft in die commands-Map des
Szenario-Moduls und gibt zurück, was dieser Handler zurückgibt.
Weil systemFor / clusterFor keine Objekte zurückreichen
können, die in einem anderen Thread leben, wird Membership
stattdessen als getMembers(role)- / getLeader(role)-Snapshots
bereitgestellt.
Wann was nutzen
Abschnitt betitelt „Wann was nutzen“| Test-Konzept | MultiNodeSpec | ParallelMultiNodeSpec |
|---|---|---|
| Cluster-Membership-Semantik | ✓ | ✓ |
| Sharding-Verteilung | ✓ | ✓ |
| Singleton-Failover | ✓ | ✓ |
| Gossip-Konvergenz | ✓ | ✓ |
| Serialisierungs-Roundtrip | ✗ | ✓ |
| Per-Worker-Heap-Isolation | ✗ | ✓ |
| Echte Parallelität (OS-Threads) | ✗ | ✓ |
| Echte TCP-Semantik | ✗ | ✗ |
| CI-Geschwindigkeit | sehr schnell | langsam |
Für 90 % der Tests, MultiNodeSpec. Für die 10 %, wo Fidelity zählt, ParallelMultiNodeSpec.
Worker-Threads hochfahren:
- Per-Node-Startup: 200-500 ms (Worker-Spawn + Cluster- Handshake).
- 3-Node-Spec: ~1,5 s gesamt.
- Im Vergleich zu MultiNodeSpec: sub-100 ms gesamt.
Für enge Test-Loops (viele Test-Fälle) summieren sich die Kosten. Nutze ParallelMultiNodeSpec sparsam — ein oder zwei Schlüssel-Tests für echte Parallelität / Serialisierung, MultiNodeSpec für den Rest.
Cleanup
Abschnitt betitelt „Cleanup“await spec.stop();// → terminiert jeden Worker-Thread (awaited, sodass keiner leakt)// → entsperrt den Test-Prozess zum BeendenRufe immer stop() — verwaiste Worker-Threads leaken und
können spätere Tests aushungern. Das Test-Framework räumt sie
womöglich auf, wenn der Test crasht, aber explizites Teardown ist
sicherer.
Der Broker zwischen den Workern verwirft, was er nicht zustellen kann,
statt zu werfen: Ein Frame, dessen to oder from keine gültige
Node-Adresse ist, und ein Frame für einen Worker, den crash() schon
beendet hat, werden beide fallen gelassen. Bis #701 warf beides im
message-Listener des Harness selbst, wo es nichts abfängt — ein einziger
schlechter Frame ließ also den ganzen Test-Prozess scheitern statt des
Szenarios, das ihn geschickt hat. Der Handel ist derselbe wie oben, nur in
anderer Gestalt: Ein Szenario, das einen malformten Frame postet, bekommt
Schweigen statt einer Diagnose.
Wo es weitergeht
Abschnitt betitelt „Wo es weitergeht“- Testing — Überblick — das größere Bild.
- MultiNodeSpec — die schnellere In-Process-Variante.
- TestKit — für Single-System- Tests.
- Test-Flakes diagnostizieren — die Quarantäne und wie sie aufgehoben wird.
