Remote mocks and the client test runtime

The remote mock and the client test runtime are test tooling in the DataMind Oda source. The mock answers the web client's calls to the host side with responses that a test scripts; the runtime boots the real web client against it, in process and with no server in the loop. To choose between the test tiers, see Testing tiers.

Answer calls by endpoint

• One rule per endpoint. A rule names one endpoint, a namespace and a method. A unary rule is a default answer, returned exactly as given, or a handler that computes the answer from the caller's arguments; a rule that throws fails the call with that error.
• One table, both paths. The same rule answers a direct call and a call over the client's connection; a call carries its arguments as an array, or in the single-object form the host's caller path uses.
• The envelopes. A success answer is { ok: true, value }; a failure carries { ok: false, error } with a code, a message and details.
• One default per endpoint. Re-registering an endpoint replaces its default, including an explicit undefined, and a queued one-shot answer is consumed before the default.

Script a stream

• Declare the mode first. Declare an endpoint as a stream before the code under test keeps a reference to its method; each endpoint, in each mode, owns its own mock. An endpoint left undeclared is dispatched as a unary call, so a forgotten declaration shows as a unary miss.
• The script sees the opening. A script receives the open arguments and a handle; it pushes items, and the stream stays open after the script returns until the test ends or fails it. A script that throws fails the stream, and opening a stream hands the script the uplink while keeping it out of the recorded arguments.
• Control from the test. push sends an item to every open stream of an endpoint; end and fail close that endpoint's open streams; each call reports how many streams changed.
• Wait for stream activity. opened resolves once an endpoint has been opened a given number of times; drained resolves once the consumer of every matching stream has caught up and is waiting for more. A stream nobody reads never drains.
• One consumer per stream. A second concurrent read on one stream is refused; a consumer that stops early ends the stream without throwing and records it as cancelled.

The call log

• Every request is recorded. Calls record as pending, answered or failed; streams as open, ended, failed or cancelled; a request that found no rule records as a miss with its mode, unary or stream.
• One counter orders everything. Calls and stream openings share a single sequence counter, so their order is exact.
• The request list. The log lists the first positional argument of each call and opening, oldest first, and leaves out the client's internal endpoints.

Boot the client against the mock

• Two tiers. The slot bench renders one part of the interface in isolation, on the real rendering machinery with test-owned stores and hosts. The whole-client tier boots the real web client in process over the mock, and never fetches bundles. The benches themselves are covered in Client test benches.
• Start options. mount is off by default; turn it on to mount into a fresh element. awaitConnected is on by default; turn it off to return as soon as the client is up. connectTimeoutMs is the budget for reaching connected, 5 seconds by default. Repeated start calls share one promise, so asking twice boots one client.
• A failed start names everything. A start that never reaches connected fails with the connection's state, the time it waited, the calls that found no answer and the streams that stayed open.
• Teardown runs its check last. Teardown disposes the tree and checks for unanswered calls last, so a failed assertion still cleans up; a start call made after its test closed is refused.
• Remote proxies. The tier provides one proxy per namespace over the client's own connection; a unary rejection is folded the way the client folds a carrier throw, and stream items pass through as yielded.

What the mock answers at startup

The mock is loaded with answers for the calls the client makes while it starts, so a fresh client boots with no sessions, no workspaces and default settings. A spec layers its own answers on top.

• The events frame is built in. Every opening of the events endpoint is answered with one ready frame that carries a client id and a default home path, and the stream stays open. That frame is what lets the assembled client reach connected.
• Untouched endpoints stay absent. An endpoint the startup never touches has no answer, so a new call fails loudly instead of waiting.

Failures you will meet

• remote-mock: no rule for <endpoint>; registered: <sorted endpoints> The call found no default or script. The message lists what is registered, and the call records as a miss.
• remote-mock: <n> unmatched request(s): Teardown found calls that never had a rule; each is listed with its mode, unary or stream, then the registered endpoints. Add the missing rule or expect the call.
• remote-mock: payload of <endpoint> must be { args: unknown[] | object } The carrier got a payload in neither accepted shape. Pass an arguments array or a single object.
• remote-mock: call aborted The call was aborted before it settled; a call aborted while pending rejects with the abort reason.
• remote-mock: <endpoint> stream disposed A stream that was already disposed refused further use. Dispose a stream only after the reads and pushes in the test finish.
• remote-mock: <endpoint> stream has one consumer A second concurrent read started on one stream. Read each stream from one place.
• remote-mock: uplink was ended A send arrived after the uplink ended. Send before ending it; a repeated end is a no-op.
• remote-mock: <endpoint> uplink item is not a lossless JSON value An item sent over the uplink cannot round-trip as JSON. Send lossless values instead.
• A mount with a missing service. The mount reports the service names it could not resolve and asks you to provide them first; to test a deliberately delayed service, mount on the context directly.
• A slot key rendered before it is declared. Rendering is refused until the key is declared on the bench; declare the key first, or declare a custom frame for your own structure.
• A store read before the root is rendered. The lookup is refused because the host face exists only inside the installed renderer; resolve the store after rendering a root.
• client test runtime: file upload is not stubbed The bench's upload stub is still in place and rejects every call. Replace the upload function in a suite that exercises uploads.
• client-test-runtime: connection state is <state> after <ms>ms; unmatched: [<calls>]; streams: [<streams>] The whole-client start ran out of its budget before connected. The message carries the state, the budget, the unanswered calls and the open streams.
• client-test-runtime: start() called after its test fixture closed The start ran after its test closed. Start within the test; teardown already disposes the client.

Limits

• In process only. The mock is an in-process carrier: values cross by reference and are never checked, rules match on the endpoint and never on the payload, and its state lives in the test process. It never hits the network.
• A test-owned stream owns its own iterable. A native stream override stays outside the mock's stream control and drain helpers.
• Generated clients are skipped. The whole-client tier provides proxies instead, so calls have no wire-level validation or name mapping.
• Two clients, two mocks. Two whole-client clients in one test process keep separate mocks; the page globals the tier adds are shared and released when the last client disposes.

Questions, answered

Why did my call fail with no rule for an endpoint?

The endpoint has no default or script, so the call recorded as a miss (remote-mock: no rule for <endpoint>; registered: <sorted endpoints>). Register the endpoint, or expect the call; endpoints the startup never touches stay absent, so this is also how a call into unmocked territory fails.

How do I answer an endpoint's calls?

Register a rule for the endpoint: a value returned exactly as given, or a handler that computes the answer from the call's arguments. A success answer is { ok: true, value }, a failure { ok: false, error }; re-registering the endpoint replaces its default.

How do I declare and script a stream?

Declare the endpoint as a stream before the code under test keeps a reference to its method, then register a script for its openings. The script receives the open arguments and a handle, pushes items, and the stream stays open until the test ends or fails it.

Why did a second read on my stream fail?

A stream has one consumer, so a second concurrent read is refused (remote-mock: <endpoint> stream has one consumer). Read each stream from one place; a consumer that stops early ends the stream without throwing and records it as cancelled.

Why was my send refused after the uplink ended?

The uplink was already ended (remote-mock: uplink was ended). Ending it again is a no-op, but a later send is refused; send before you end it.

Why was my item refused as not a lossless JSON value?

Every item sent over the uplink must round-trip as JSON; a value that cannot, such as a bigint, is refused. Send lossless JSON values instead.

What does clearing the mock keep?

Clearing keeps every answer and queued reply, so later calls still get them; resetting instead drops overrides and restores the initial implementation, which reads the latest registered answer.

Why did the whole-client start fail waiting for the connection?

The readiness wait ran out. The failure names the connection's state, the budget it waited, the calls that found no answer and the streams still open; add a rule for a call the startup makes, or raise connectTimeoutMs.

Why is a start refused after my test closed?

A start call made after its test closed does not run (client-test-runtime: start() called after its test fixture closed). Start within the test; teardown already disposes the client.

What does the mock answer while the client boots?

The startup answers in the table above: an empty chat list, a successful default workspace setup, a writable settings description, a default model entry, an empty preset list, a signed-out account, and the follow stream declared. The built-in events frame is what lets the client reach connected.