跳到主要内容

模拟外部依赖

@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 }"

下一步​

  • 指令 —— @nudo:mock / @nudo:mock-module / @nudo:env
  • 语言语义 —— mock 边界与仍会降级的部分
  • 示例 —— env 与 mock 配方及真实输出
  • nudo test —— 可选调试见证