Mocking External Dependencies
@nudo:mock replaces external dependencies with mocks during evaluation. Use it for fetch, file system APIs, or other code Nudo cannot execute directly. (Module-level replacement lives in @nudo:mock-module.)
Syntax
Five forms are supported. Every inline expression must fit on a single line — see the warnings below.
1. Single-line arrow function. The body is plain JavaScript; the parameters receive Abs values:
@nudo:mock name = (arg) => body
2. Mock helpers — stub(), spy(), mock(), chainable with .returns(...), .resolves(...), .rejects(...), .withArgs(...), .callsFake(...):
@nudo:mock name = stub().returns(value)
3. Sinon-style equivalents — sinon.stub() / sinon.spy() with the same chains:
@nudo:mock name = sinon.stub().returns(value)
4. Constraint-builder expression (or a concrete value):
@nudo:mock name = number()
@nudo:mock retries = 3
5. From module — the module must define a binding with the same name as the mock:
@nudo:mock name from "path"
- name — The identifier to mock (e.g.
fetch,fs). - path — Path to a module that provides the mock.
The mock module is loaded and evaluated like any other dependency; its binding with the matching name is seeded into evaluation as the mock. If the file is missing, the mock module fails to evaluate, or no binding with that name exists, nudo check reports a nudo:module-missing error instead of silently dropping the mock.
Warning: the expression must be a single line. The parser only reads up to the end of the line, so a multi-line expression is truncated at its first line and reported as nudo:mock-invalid. The following does not work:
@nudo:mock fetch = (url) => ({ ok: true,
json: () => ({ id: 1 })
})
The real diagnostics for the truncated line:
[warning] example.js:0:0 Mock expression "(url) => ({ ok: true," could not be parsed as a known pattern (nudo:mock-invalid)
[warning] example.js:10:9 Cannot resolve 'json' on unknown value (nudo:unknown-recv)
Warning: no builder calls inside an arrow-function mock body. Constraint builders exist only in directive type expressions (case args, @nudo:skip, @nudo:as, …). Inside a mock body write plain JavaScript — plain objects and closures — or use stub().returns(...) / stub().resolves(...) helpers instead.
Warning: an unmocked host side-effect global is not executed during analysis. Host functions that would perform real network I/O or schedule real timers — fetch / XMLHttpRequest / WebSocket / EventSource / setTimeout / setInterval / setImmediate / queueMicrotask / requestAnimationFrame / requestIdleCallback — are blocked by the evaluator: they never run with Abs arguments, the result is widened to unknown#opaque, and the run reports nudo:host-effect-blocked (Info). The analysis does not crash and the exit code is unaffected — only type precision degrades. Mock any of them your analyzed code calls to keep the inferred type precise: @nudo:mock fetch = (url) => ({ ok: true, json: () => ({ ... }) }).
Examples
Mock fetch with an arrow function. The body is plain JavaScript on one line:
/**
* @nudo:mock fetch = (url) => ({ ok: true, json: () => ({ id: 1, name: "Alice" }) })
* @nudo:case "user" (1)
*/
async function fetchUser(id) {
const res = await fetch(`/api/users/${id}`);
return res.json();
}
Inferred output:
=== fetchUser ===
debug "user" (1) => promise<{ id: 1, name: "Alice" }>
A mock helper for resolved promises — stub().resolves(value) makes every call return promise<value>:
/**
* @nudo:mock fetch = stub().resolves({ ok: true, json: () => ({ id: 1, name: "Alice" }) })
* @nudo:case "user" (1)
*/
async function fetchUser(id) {
const res = await fetch(`/api/users/${id}`);
return res.json();
}
Same result as the arrow mock: stub().resolves(value) wraps value in a promise and the object's closure slots are bridged, so this example infers promise<{ id: 1, name: "Alice" }> — including the callable json slot. Use whichever form reads better. A synchronous helper:
/**
* @nudo:mock getPort = stub().returns(8080)
* @nudo:case "default" ()
*/
function readPort() {
return getPort();
}
Inferred output:
=== readPort ===
debug "default" () => 8080
A constraint-builder expression binds the name to an abstract domain directly:
/**
* @nudo:mock retries = number()
* @nudo:case "plan" ()
*/
function plan() {
return retries + 1;
}
Inferred output:
=== plan ===
debug "plan" () => number
From a module — the module must define a binding with the mocked name:
/**
* @nudo:mock fs from "./mocks/fs.js"
* @nudo:case "read" (string())
*/
function readConfig(path) {
return fs.readFileSync(path, "utf-8");
}
// mocks/fs.js
const fs = { readFileSync: (path, encoding) => "{ \"port\": 3000 }" };
Inferred output:
=== readConfig ===
debug "read" (string) => "{ \"port\": 3000 }"
Next
- Directives —
@nudo:mock/@nudo:mock-module/@nudo:env - Language semantics — the mock boundary and what still degrades
- Examples — env and mock recipes with real output
- nudo test — optional debug witnesses