ParallelMultiNodeSpec
ParallelMultiNodeSpec is the worker-thread variant of
MultiNodeSpec. Each
“node” runs in its own worker_threads Worker (or a Web Worker
on Bun/Deno), connected through an in-process broker. Same test
shape as MultiNodeSpec, but with real OS threads so
concurrency bugs the single-threaded variant papers over can
surface.
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);
// Drive the worker-side scenario over an RPC:const result = await spec.runIn('a', 'compute', { x: 42 });
await spec.stop();When to use it
Section titled “When to use it”For tests that need true parallelism:
- Real threads — catches races the in-process variant serialises away on a single event loop (concurrent journal writes, scheduler-thread interleaving).
- Serialization — every message crosses a worker boundary via structured clone, so non-serializable payloads (functions, class instances) fail here just as they would on a real wire.
- Thread isolation — each node has its own heap and event loop.
For most cluster tests, MultiNodeSpec is faster + simpler — use ParallelMultiNodeSpec only when single-threaded tests don’t cover the case. Neither variant uses TCP; for real network conditions, use an external Docker-Compose cluster.
Configuration
Section titled “Configuration”type ParallelMultiNodeSpecOptionsType = { roles: ReadonlyArray<string>; // one worker per role; must be unique seedRoles?: ReadonlyArray<string>; // bootstrap seeds — defaults to [roles[0]] scenarioModule?: URL; // module each worker loads (setup + commands) scenarioInitDataFor?: (role: string) => unknown; // per-role data passed to setup() addresses?: Record<string, { host: string; port: number }>; failureDetector?: Partial<FailureDetectorOptionsType>; failureDetectorAutoDown?: boolean; // default unset = the shipped true gossipIntervalMs?: number; awaitTimeoutMs?: number; // default 30_000 (worker bootstrap is slower) controlRpcTimeoutMs?: number; // default 5_000 (one control RPC) logLevel?: LogLevel; bootstrapModule?: URL; // override the bundled worker bootstrap};| Field | Purpose |
|---|---|
roles | Node list — one worker per role; the string is the worker’s system name. Must be unique. |
seedRoles | Which roles act as bootstrap seeds. Defaults to the first role. |
scenarioModule | URL of the module each worker imports — it owns the actor-shaped setup and the commands map runIn dispatches to. |
scenarioInitDataFor | Per-role data forwarded to the scenario’s setup(context). |
failureDetector | Failure-detector overrides. |
failureDetectorAutoDown | Whether every role’s failure detector removes a peer it declares down. Unset keeps the shipped true: a crashed role is removed at down-after, which is what a spec that exercises crash failover needs — this spec has no downing strategy option. false is the opt-out, under which a crashed role stays a member at unreachable and nothing ever removes it. |
awaitTimeoutMs | Default await* timeout. Default 30 s — worker bootstrap is slower than in-process. |
controlRpcTimeoutMs | How long one control RPC (getMembers, getLeader, leave, runIn) may go unanswered before it fails naming the role that went silent. Default 5 s — much shorter than awaitTimeoutMs on purpose: an RPC that does not come back means the worker is wedged, and a fast deadline surfaces that instead of hanging the test. Both are scaled by the time factor. |
bootstrapModule | Override the bundled worker entry point (advanced) — it takes over the control channel, so see the contract below. Held to the same spelling rule as every other worker entry in the framework: an absolute, host-less file: URL naming a file, which new URL('./my-bootstrap.ts', import.meta.url) produces. A data:, blob: or remote specifier, a file: URL with a host or with a path beginning //, or a directory is refused with an OptionsError when the spec is constructed. The scheme-relative file:worker.js is not, and cannot be: the field is typed URL, and new URL('file:worker.js') is already file:///worker.js before the spec sees it — that spelling is only refused where the option also takes a string. |
The scenario module
Section titled “The scenario module”Each worker joins the cluster automatically — the harness owns
the ActorSystem + Cluster bootstrap. Your test-specific
actor code lives in a scenario module: a plain module that
exports an optional setup(context) hook and a commands map.
The worker imports it by URL, runs setup once after the cluster
joins, then dispatches runIn(role, command, args) calls to the
matching command.
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' }); }, // Commands may return any JSON-serialisable value back to the harness: ping(): string { return 'pong'; },};The module owns everything actor-shaped (entity classes, sharding regions, …). The harness only ever exchanges JSON-serialisable command/response pairs with it — closures can’t cross the worker boundary, which is why scenario code lives in its own file loaded by URL rather than inline in the test.
The custom bootstrap contract
Section titled “The custom bootstrap contract”A scenario module rides on top of the bundled bootstrap. bootstrapModule
replaces that bootstrap outright, which means it also takes over the
control channel — the postMessage protocol the harness drives every
worker through, on the same socket as the cluster handshake. There are four
requests, and each reply is named after the request it answers with
-response appended:
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? }Three rules decide whether a reply is accepted, and all three are checked:
- Echo the
reqId. Every request carries one; the reply carries the same number back. It is what the harness keys its pending calls on. - Use the matching kind. The harness builds the name it will accept by
appending
-responseto the kind it sent, so a well-formed payload under a different name is not a reply. - Answer from the worker that was asked. A reply to role
a’s question posted by roleb’s worker is refused even when the kind and thereqIdboth match.
A reply that breaks any of them is dropped, not rejected: the harness
writes a console.warn naming the frame it discarded and the call that
reqId really belongs to, leaves the call pending in case the genuine reply
is still coming, and fails it 5 s later with a message naming the role and
the request that went unanswered.
Only the first rule has always been enforced. Before the correlation fix a
reply was matched on reqId alone, so a bootstrap that answered under a
different name, or from the wrong worker, happened to work — the reason this
contract is written down rather than left implied.
Driving the workers
Section titled “Driving the workers”The test can’t touch a worker’s in-memory actors directly, so it drives them through the harness:
// Invoke a scenario command on a specific role and await its result:await spec.runIn('a', 'increment');const reply = await spec.runIn<string>('a', 'ping'); // → 'pong'
// Inspect each worker's cluster view (JSON snapshots, not live objects):const members = await spec.getMembers('a');const leader = await spec.getLeader('a');runIn(role, command, args?) calls into the scenario module’s
commands map and returns whatever that handler returns. Because
systemFor / clusterFor can’t hand back objects that live in
another thread, membership is exposed as getMembers(role) /
getLeader(role) snapshots instead.
When to use which
Section titled “When to use which”| Test concept | MultiNodeSpec | ParallelMultiNodeSpec |
|---|---|---|
| Cluster membership semantics | ✓ | ✓ |
| Sharding distribution | ✓ | ✓ |
| Singleton failover | ✓ | ✓ |
| Gossip convergence | ✓ | ✓ |
| Serialization round-trip | ✗ | ✓ |
| Per-worker heap isolation | ✗ | ✓ |
| True parallelism (OS threads) | ✗ | ✓ |
| Real TCP semantics | ✗ | ✗ |
| CI speed | very fast | slow |
For 90 % of tests, MultiNodeSpec. For the 10 % where fidelity matters, ParallelMultiNodeSpec.
Spinning up worker threads:
- Per-node startup: 200-500 ms (worker spawn + cluster handshake).
- 3-node spec: ~1.5 s total.
- Compared to MultiNodeSpec: sub-100 ms total.
For tight test loops (many test cases), the cost adds up. Use ParallelMultiNodeSpec sparingly — one or two key tests for real parallelism / serialization, MultiNodeSpec for the rest.
Cleanup
Section titled “Cleanup”await spec.stop();// → terminates every worker thread (awaited, so none leak)// → unblocks the test process to exitAlways call stop() — orphaned worker threads leak and can
starve later tests. The test framework may clean them up if the
test crashes, but explicit teardown is safer.
The broker between the workers drops what it cannot route rather than
throwing: a frame whose to or from is not a valid node address, and a
frame for a worker crash() has already terminated, are both discarded.
Until #701 either one threw inside the harness’s own message listener,
where nothing catches it, so one bad frame failed the whole test process
rather than the scenario that sent it. The trade is the one above in
another guise: a scenario that posts a malformed frame gets silence, not a
diagnostic.
Where to next
Section titled “Where to next”- Testing overview — the bigger picture.
- MultiNodeSpec — the faster in-process variant.
- TestKit — for single-system tests.
- Diagnosing test flakes — the quarantine, and how it is lifted.
