Ir al contenido
Español

ParallelMultiNodeSpec

Esta página aún no está disponible en tu idioma.

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();

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.

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
};
FieldPurpose
rolesNode list — one worker per role; the string is the worker’s system name. Must be unique.
seedRolesWhich roles act as bootstrap seeds. Defaults to the first role.
scenarioModuleURL of the module each worker imports — it owns the actor-shaped setup and the commands map runIn dispatches to.
scenarioInitDataForPer-role data forwarded to the scenario’s setup(context).
failureDetectorFailure-detector overrides.
failureDetectorAutoDownWhether 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.
awaitTimeoutMsDefault await* timeout. Default 30 s — worker bootstrap is slower than in-process.
controlRpcTimeoutMsHow 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.
bootstrapModuleOverride 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.

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.

my-scenario.ts
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.

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 -response to 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 role b’s worker is refused even when the kind and the reqId both 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.

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.

Test conceptMultiNodeSpecParallelMultiNodeSpec
Cluster membership semantics✓✓
Sharding distribution✓✓
Singleton failover✓✓
Gossip convergence✓✓
Serialization round-trip✗✓
Per-worker heap isolation✗✓
True parallelism (OS threads)✗✓
Real TCP semantics✗✗
CI speedvery fastslow

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.

await spec.stop();
// → terminates every worker thread (awaited, so none leak)
// → unblocks the test process to exit

Always 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.