模拟外部依赖
@nudo:mock 在求值期间用 mock 替换外部依赖。用于 fetch、文件系统 API 或 Nudo 无法直接执行的其他代码。(模块级替换见 @nudo:mock-module。)
语法
支持五种形式。每个内联表达式必须写在一行内——见下方警告。
1. 单行箭头函数。 函数体是普通 JavaScript;参数接收 Abs 值:
@nudo:mock name = (arg) => body
2. Mock 帮助函数 — stub()、spy()、mock(),可链式 .returns(...)、.resolves(...)、.rejects(...)、.withArgs(...)、.callsFake(...):
@nudo:mock name = stub().returns(value)
3. Sinon 风格等价物 — sinon.stub() / sinon.spy(),链式相同:
@nudo:mock name = sinon.stub().returns(value)
4. 约束构造器表达式(或具体值):
@nudo:mock name = number()
@nudo:mock retries = 3
5. 从模块 — 模块必须定义与被 mock 名称相同的绑定:
@nudo:mock name from "path"
- name — 要 mock 的标识符(如
fetch、fs)。 - path — 提供 mock 的模块路径。
mock 模块会像普通依赖一样被装载求值;其中与 mock 同名的绑定被种入求值作为该 mock。若文件缺失、mock 模块求值失败、或不存在同名绑定,nudo check 报 nudo:module-missing 错误,而不是静默丢弃 mock。
警告:表达式必须单行。 解析器只读到行尾,多行表达式会在第一行截断并报 nudo:mock-invalid。下面这种写法不生效:
@nudo:mock fetch = (url) => ({ ok: true,
json: () => ({ id: 1 })
})
截断行的真实诊断:
[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)
警告:箭头函数 mock 体内不能调用构造器。 约束构造器只存在于指令类型表达式(case 参数、@nudo:skip、@nudo:as……)中。mock 体内写普通 JavaScript——普通对象与闭包——或改用 stub().returns(...) / stub().resolves(...) 帮助函数。
警告:未 mock 的宿主副作用全局量在分析期不会被执行。 会发起真实网络 I/O 或排真实定时器的宿主函数——fetch / XMLHttpRequest / WebSocket / EventSource / setTimeout / setInterval / setImmediate / queueMicrotask / requestAnimationFrame / requestIdleCallback——被求值引擎拦下:它们不会带着 Abs 实参真实执行,结果拓宽为 unknown#opaque,并上报 nudo:host-effect-blocked(Info)。整轮不会崩溃、退出码不受影响,只是类型精度退化。把分析代码调用的这些全局量都 mock 掉以保住精确类型:@nudo:mock fetch = (url) => ({ ok: true, json: () => ({ ... }) })。
示例
用箭头函数 mock fetch。函数体是单行普通 JavaScript:
/**
* @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();
}
推断输出:
=== fetchUser ===
debug "user" (1) => promise<{ id: 1, name: "Alice" }>
解析 promise 的 mock 帮助函数——stub().resolves(value) 让每次调用返回 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();
}
与箭头 mock 结果相同: stub().resolves(value) 把 value 包进 promise,且对象的闭包槽会被桥接,所以本示例推断出 promise<{ id: 1, name: "Alice" }>——包括可调用的 json 槽。哪种形式读起来更顺就用哪种。同步帮助函数:
/**
* @nudo:mock getPort = stub().returns(8080)
* @nudo:case "default" ()
*/
function readPort() {
return getPort();
}
推断输出:
=== readPort ===
debug "default" () => 8080
约束构造器表达式直接把名称绑定到抽象域:
/**
* @nudo:mock retries = number()
* @nudo:case "plan" ()
*/
function plan() {
return retries + 1;
}
推断输出:
=== plan ===
debug "plan" () => number
从模块——模块必须定义与被 mock 名称相同的绑定:
/**
* @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 }" };
推断输出:
=== readConfig ===
debug "read" (string) => "{ \"port\": 3000 }"