nudo test
nudo test 是 debug / 场景报告器,不是 CI 门禁。 门禁是 nudo check(L1 契约 + L2 入口 throws)——只有签名、约束违例与 throws 进入 CI。用 test 来查看 Nudo 如何执行用例(call@ / entry@ / debug 见证)、驱动声明的 @nudo:case 断言,或用 --freeze 钉住回归。
读完你将获得: 默认 case 报告的读法(call@ / entry@ / debug 见证)、声明断言 —— 唯一能让运行失败的东西 —— --freeze 见证固化,以及 test 与 check 的清晰分工。
nudo test 是 Nudo 的 case 报告:Abs 上逐调用点的真值。它是观察面,不是 CI 门禁。
- 所有推导出的 case 默认全部打印 —— 合成
call@L…/entry@L…case 和debug见证。 - 只有声明断言(
@nudo:case "…" (args) => expected)进入 pass/fail;只有它们的失败才置 exit1。 - 分析诊断在报告之后上屏供知悉 —— 它们不决定退出码。
门禁在 nudo check(L1 契约 + L2 入口 throws)。观察不需要独立动词:它就是 check 签名、test case 报告和 IDE hover。
nudo test <path> [--watch|-w] [--from paths…] [--freeze[=mode]] [--dry-run] [--exit-on-diff] [--both-paths [--only names]] [--json] [--abs]
默认输出
export function subtract(a, b) {
return a - b;
}
subtract(5, 3);
subtract(1, 10);
nudo test math.js
nudo test math.js
=== subtract ===
call@L5 (5, 3) => 2
call@L6 (1, 10) => -9
assertions
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; 2 synthetic case(s) printed above)
这些 case 没有人写过。Nudo 用每个调用点实际传入的参数执行了 subtract,并报告结果。各节读法:
| 行 | 含义 |
|---|---|
=== fn === | 每个被分析函数一节;导入的模块归在 --- <module> (imported) --- 下 |
call@L… | 真实调用点(L 为被分析文件或 --from 使用处文件中的行号),以实际实参执行 |
entry@L… | 无人调用的函数的 fallback —— 参数默认 any(无约束),绝不是 unknown。存在 call@ case 时,该函数不再合成 entry@ |
debug "name" | 一条 @nudo:case 见证(见下) |
throws TypeError | 追加在路径可能抛出的 case 上 |
无人调用时的 entry-only fallback:
export function getName(user) {
return user.name;
}
=== getName ===
entry@L1 (any) => any throws TypeError
当这个无人调用的函数持有受 check 执法的契约(手写 *.nudo.js 侧车或 @nudo:contract)时,同一区块会多出一行注解。诚实的 (any) => any throws TypeError 保留——那正是无约束入口 face——注解解释了为什么 nudo check 对该函数仍然全绿:契约作用于 check/export 面,而不是这个回退 case。
export function greet(u) {
return u.name;
}
export const greet = fn({ u: shape({ name: string() }) });
=== greet ===
entry@L1 (any) => any throws TypeError
(entry@ runs the unconstrained entry face — this contract gates check/export; add @nudo:case or call sites for a constrained case)
assertions 汇总
assertions 块只统计声明 case —— 合成 call@ / entry@ 永不进入:
- 存在声明期望时为
✓ N passed · N failed · N unchecked(有失败则✗); - 没有声明时为
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; N synthetic case(s) printed above)。
unchecked 指不带 => expected 的 @nudo:case:Nudo 执行并报告的见证,但不下判断。分析诊断存在时在报告之后以 [severity] file:line:col message (code) 上屏 —— 供知悉;退出码仍由声明断言驱动。
声明断言
@nudo:case "name" (args) => expected 声明一个期望。Nudo 执行该 case 并用实际结果对照期望 Abs 检查(leqAbs):
/**
* @nudo:case "double" (2) => 4
* @nudo:case "bad" (3) => 7
*/
export function double(x) {
return x * 2;
}
nudo test dbl.js
nudo test dbl.js
=== double ===
debug "double" (2) => 4
debug "bad" (3) => 6
assertions
✗ 1 passed · 1 failed · 0 unchecked
[ok] double case "double" → 4
[FAIL] double case "bad"
expected: 7
actual: 6
diagnostics
[error] dbl.js:3:0 debug "bad": expected 7, got 6. The inferred return type does not match the expected type declared in the @nudo:case witness (nudo:case-expected)
exit 1 —— 一条声明断言失败了。
case 也可以用 !! throws 后缀申报有意的 throw 域(@nudo:case "neg" (0) !! throws 申报任意 throw;!! throws Error 按类型申报)。它与 @nudo:throws 在 core 的 refine.ts 中同路解析 —— 完整语法见指令参考。@nudo:case 仍是 debug/test/LSP 面;契约产品是 *.nudo.js / @nudo:contract。
| 码 | 含义 |
|---|---|
0 | 全部声明断言通过(或未声明) |
1 | 任一声明断言失败 —— 合成 call@ / entry@ case 永不挡 exit |
完整退出码契约:CLI 参考。
固化见证(--freeze)
合成 case 只存在于产出它的那次运行里。--freeze 把它们作为真正的 @nudo:case 指令写回被分析文件,让这些形状在运行之外存活:
nudo test lib/ --from tests/ --freeze # add(默认):只填充没有 case 指令的函数
nudo test lib/ --from tests/ --freeze=update # 重新同步此前生成的 call@ 指令
- 手写 case(名字不以
call@开头)绝不被触碰;call@是保留前缀。 --dry-run打印 unified diff 而不写盘:
freeze: would write cases → math.js (dry run)
subtract: call@L5, call@L6
--- a/math.js
+++ b/math.js
@@ -1,3 +1,7 @@
+ /**
+ * @nudo:case "call@L5" (5, 3)
+ * @nudo:case "call@L6" (1, 10)
+ */
export function subtract(a, b) {
return a - b;
}
--exit-on-diff(需要--dry-run)在 diff 非空时 exit1—— 固化见证的 CI 漂移门禁。
合并策略(各模式触碰什么、可序列化形状的限制)规定在 Call-Site Discovery。想持续守望这种漂移而不是手动刷新:nudo health 重跑同一条再固化链,一旦生成指令会变就 exit 1。
同轮对照两条路径(--both-paths)
默认口径下,两种见证按函数按轮互斥:带 @nudo:case 指令的函数只打印指令见证,调用点见证(call@ / entry@)只对没有指令的函数合成。--both-paths 打开教学对照面 —— 同一函数的指令见证与合成调用点见证在同一轮里并排出现:
nudo test src/math.js --both-paths
nudo test src/ --both-paths --only add,clamp # 只对指定函数开启合成
=== add ===
debug "add-lit" (2, 3) => 5
call@L11 (10, 20) => 30
- 退出语义不变:合成 case 依旧不挡 exit,只有声明断言能让运行失败。
--only <names>(逗号分隔)把合成收敛到指定函数 —— 名单外的指令函数保持默认互斥口径。--only不带--both-paths是用法错误。--freeze与--both-paths互斥(用法错误):freeze 固化的是指令见证,是另一种产品面。--json面每条 case 的source字段分辨路径:"directive"/"callsite"/null(entry@兜底)。
使用处(--from)
--from <paths…> 指向使用处文件 —— 测试、示例、上游应用。Nudo 采集它们的真实调用记录,并把每条匹配的调用注入为 call@L case,于是实参形状来自代码实际被怎么用,而不是手写指令。两阶段采集、归因门与试跑数据见 Call-Site Discovery。
机器可读与代数面
--json 输出 CaseJson v1 —— 仅单文件;不能与 --abs 或 --freeze 组合 —— 含 version / file / summary / functions[].cases[](外延的 args / result / throws,以及可得时无损的 argsAbs / resultAbs / intension),并在其上加 assertions 汇总。节选(有裁剪):
{
"version": 1,
"file": "dbl.js",
"summary": { "functions": 1, "externalFunctions": 0, "cases": 3, "diagnostics": 1 },
"functions": [
{
"name": "double",
"entryOnly": false,
"cases": [
{
"name": "double",
"args": ["2"],
"result": "4",
"throws": null,
"source": "directive",
"argsAbs": ["2 #exact"],
"resultAbs": "4 #exact",
"intension": {
"display": "double: (x: A1) => number = (A1 * 2)",
"abs": "4 #exact",
"term": "(A1 * 2)",
"conf": "exact"
}
}
]
}
],
"assertions": { "passed": 1, "failed": 1, "unchecked": 1 }
}
声明断言失败时 --json 仍 exit 1。
--abs 先打印 check --abs 代数面(逐函数 shape + conf),再打印 case 报告 —— 声明断言失败保持可见且仍挡 exit。--watch / -w 变更时重跑(模式旗标,不是动词)。
test 与 check 的分工
nudo check | nudo test | |
|---|---|---|
| 职责 | 门禁:L1 显式契约 + L2 入口 may-throw | 报告:逐 case 真值 + 声明断言 |
| 打印 | Signatures(始终,成功也是)+ issues | 全部 case(call@ / entry@ / debug)+ assertions 汇总 |
Exit 1 | 任一 error 级诊断 | 任一声明断言失败 |
| CI | 产品门禁(对标 tsc --noEmit) | 可选:声明断言、freeze 漂移 |
观察不是独立动词 —— 它落在 check 签名、test case 报告和 IDE hover 里。
选项
| 选项 | 说明 |
|---|---|
--watch / -w | 变更时重跑(旗标,不是动词) |
--from <paths…> | 使用处文件,其调用成为 call@L case |
--freeze[=mode] | 把合成 case 写回为 @nudo:case 指令(默认 add / update) |
--both-paths | 同一轮并排打印同一函数的指令见证与合成 call@/entry@ 见证(退出语义不变;不与 --freeze 组合) |
--only <names> | 搭配 --both-paths:把合成收敛到指定函数(逗号分隔) |
--dry-run | 搭配 --freeze:打印 unified diff 而不写盘 |
--exit-on-diff | 搭配 --freeze --dry-run:diff 非空时 exit 1 |
--json | CaseJson(单文件;不能与 --abs / --freeze 组合) |
--abs | 代数面(同 check --abs),随后是 case 报告 |
完整旗标与退出码表:CLI 参考。
下一步
- nudo check —— CI 门禁详解
- Call-Site Discovery ——
--from采集、归因门、freeze 合并策略 - nudo health —— 漂移作为 CI 门禁
- CLI 参考 —— 全部旗标与退出码