Skip to main content

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:

engine-verifiedRun in Playground
/**
* @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:

engine-verifiedRun in Playground
/**
* @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:

engine-verifiedRun in Playground
/**
* @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:

engine-verifiedRun in Playground
/**
* @nudo:mock fs from "./mocks/fs.js"
* @nudo:case "read" (string())
*/
function readConfig(path) {
return fs.readFileSync(path, "utf-8");
}
engine-verifiedRun in Playground
// mocks/fs.js
const fs = { readFileSync: (path, encoding) => "{ \"port\": 3000 }" };

Inferred output:

=== readConfig ===

debug "read" (string) => "{ \"port\": 3000 }"

Next​