How to test a surface
directDispatch is the identity transport: it takes the served
surface itself and invokes its handlers in-process, with no
socket and no subprocess. That makes it the tool for testing a surface. The face
you drive in the test is the exact face a socket consumer would hold.
Build an in-process client
Hand directDispatch the value implementSurface returned (it needs only the
bound handlers, so pass the runtime bare) and wrap it in buildSurfaceFace for
the nested client.surface.<member>.<verb> addressing. Nothing is finalized and
nothing is re-prefixed — a tag carries its own route. directDispatch is also the
one dispatch surfaceClient accepts without a watchdog, because with no transport
there is nothing that could half-open.
The face is deliberately structural: each leaf types as unknown, because
per-member precision lives in the spec-derived hooks a Solid consumer gets. So a
test names the shape of each member it uses once, as a UnaryEffect<I, O, E> or
a StreamingProcedure<I, O>, after which every call site is fully typed.
function makeTestClient() {
const runtime = implementSurface(surface, {
cells: { load: { store: inMemoryStore(ZERO) } },
collections: {
processes: {
readAll: () => table,
upsert: (pid, proc) => {
table.set(pid, proc);
},
remove: (pid) => {
table.delete(pid);
},
},
},
streams: {
nodeLog: {
source: (nodeId) =>
Stream.succeed({
kind: "snapshot" as const,
text: `opened ${nodeId}`,
done: false,
}),
},
},
events: { autosave: {} },
procedures: {
proc: {
kill: ({ input, ctx }) =>
Effect.sync(() => {
ctx.collections.processes.remove(input.pid);
return { ok: true };
}),
},
},
});
// The wire face, in-process. `implementSurface` already returns everything a
// dispatch needs, so pass the runtime bare — `directDispatch` is the one
// dispatch `surfaceClient` accepts without a watchdog.
return buildSurfaceFace(surface, directDispatch(runtime));
}
Assert on a snapshot
A cell or stream read opens with a snapshot and then sends deltas, as an Effect
Stream. The current value is therefore the first frame, and Stream.runHead
is the one-shot read: it interrupts the subscription as soon as that frame
lands.
Wrap it in a helper that fails on an empty stream, so a broken read fails the
test instead of asserting on undefined. firstFrameOrThrow in
@kolu/surface/first-frame is that helper, already written. It takes the member
Stream and gives you an Effect that fails with your message on an empty one.
const load = await snapshot(
loadGet(undefined),
"load cell yielded no snapshot frame — link failure",
);
expect(load).toEqual(ZERO);
Drive a procedure and assert the effect
A procedure call is an Effect, so a test runs it the same way it runs any
other. Call one, then read the affected cell or collection back and assert the
new snapshot.
// A procedure call is an `Effect` — a description. `await` on one yields the
// description itself and dispatches NOTHING, so the run is what makes it happen.
await Effect.runPromise(kill({ pid: 4321 }));
const alive = await snapshot(
keys(undefined),
"processes keys yielded no snapshot frame — link failure",
);
expect(alive).not.toContain(4321);
Read a run of stream frames
When the value under test is a stream that emits over time, run it and collect
the frames you care about. Stream.takeUntil ends it on the terminal frame, the
Stream-native break. Ending the stream finalizes the subscription, so there is
no signal to thread and none to forget. Because there is no socket, delivery is
deterministic: no timers, no flushing.
const frames: LogFrame[] = [];
await Effect.runPromise(
Stream.runForEach(
// `takeUntil` ends the stream on the terminal frame, which finalizes the
// subscription — the Stream-native `break`.
Stream.takeUntil(nodeLog("node-1"), (frame) => frame.done),
(frame) => Effect.sync(() => frames.push(frame)),
),
);
expect(frames[0]?.kind).toBe("snapshot");