Skip to main content

nudo test

nudo test is a debug / scenario reporter, not the CI gate. The gate is nudo check (L1 contracts + L2 entry throws) — only signatures + constraint violations + throws enter CI. Use test to inspect how Nudo executed cases (call@ / entry@ / debug witnesses), to drive declared @nudo:case assertions, or to pin regressions via --freeze.

You'll leave with: the default case report (call@ / entry@ / debug witnesses), declared assertions — the only thing that fails the run — witness solidification with --freeze, and a clean split between test and check.

nudo test is Nudo's case report: per-call-site ground truth computed on Abs. It is the observation face, not the CI gate.

  • Every inferred case prints by default — synthetic call@L… / entry@L… cases and debug witnesses.
  • Only declared assertions (@nudo:case "…" (args) => expected) enter pass/fail; only their failures set exit 1.
  • Analysis diagnostics print after the report for awareness — they do not set the exit code.

The gate lives in nudo check (L1 contracts + L2 entry throws). Observation needs no verb of its own: it is check signatures, test case reports, and IDE hover.

nudo test <path> [--watch|-w] [--from paths…] [--freeze[=mode]] [--dry-run] [--exit-on-diff] [--both-paths [--only names]] [--json] [--abs]

Default output​

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)

Nobody wrote those cases. Nudo executed subtract with the arguments each call site actually passed and reported the results. Reading the sections:

LineMeaning
=== fn ===One section per analyzed function; imported modules group under --- <module> (imported) ---
call@L…A real call site (line L in the analyzed file or a --from usage site), executed with its actual arguments
entry@L…The fallback for functions nobody calls — parameters default to any (unconstrained), never unknown. When call@ cases exist, no entry@ is synthesized for that function
debug "name"An @nudo:case witness (see below)
throws TypeErrorAppended to any case whose path may throw

The entry-only fallback, on a function with no call sites anywhere:

export function getName(user) {
return user.name;
}
=== getName ===
entry@L1 (any) => any throws TypeError

When that never-called function holds a check-enforced contract (a handwritten *.nudo.js sidecar or @nudo:contract), the same block grows one annotation line. The honest (any) => any throws TypeError stays — that is the unconstrained entry face — and the note explains why nudo check is still green for this function: the contract gates the check/export faces, not this fallback 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)

The assertions summary​

The assertions block counts declared cases only — synthetic call@ / entry@ never enter it:

  • ✓ N passed · N failed · N unchecked when declared expectations exist (✗ when any failed);
  • — 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; N synthetic case(s) printed above) when none are declared.

unchecked is a @nudo:case without => expected: a witness Nudo executes and reports, but does not judge. Analysis diagnostics, when present, print after the report as [severity] file:line:col message (code) — for awareness; the exit code stays driven by declared assertions.

Declared assertions​

@nudo:case "name" (args) => expected declares an expectation. Nudo executes the case and checks the actual result against the expected 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 — a declared assertion failed.

A case may also declare its intentional throw domain with the !! throws suffix (@nudo:case "neg" (0) !! throws declares any throw; !! throws Error declares by kind). It is parsed alongside @nudo:throws in core's refine.ts — full syntax in the directive reference. @nudo:case stays debug/test/LSP surface; the contract product is *.nudo.js / @nudo:contract.

CodeMeaning
0All declared assertions passed (or none declared)
1Any declared assertion failed — synthetic call@ / entry@ cases never block exit

Full exit-code contract: CLI Reference.

Freeze witnesses (--freeze)​

Synthetic cases exist only inside the run that produced them. --freeze writes them back into the analyzed file as real @nudo:case directives, so the shapes survive outside the run:

nudo test lib/ --from tests/ --freeze # add (default): fill functions that have no case directives
nudo test lib/ --from tests/ --freeze=update # re-synchronize previously generated call@ directives
  • Hand-written cases (names not starting with call@) are never touched; call@ is a reserved prefix.
  • --dry-run prints a unified diff instead of writing:
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 (requires --dry-run) exits 1 when the diff is non-empty — the CI drift gate for frozen witnesses.

The merge policy (what each mode touches, serializable-shape limits) is specified in Call-Site Discovery. To watch that drift continuously instead of refreshing by hand, nudo health re-runs the same re-solidify chain and exits 1 as soon as generated directives would change.

Both paths in one round (--both-paths)​

By default the two witness kinds are mutually exclusive per function per round: a function with @nudo:case directives prints only its directive witnesses, while call sites are synthesized (call@ / entry@) only for functions that have none. --both-paths opens the teaching comparison face — the directive witness and the synthesized call-site witness for the same function, in the same round:

nudo test src/math.js --both-paths
nudo test src/ --both-paths --only add,clamp # limit synthesis to named functions
=== add ===
debug "add-lit" (2, 3) => 5
call@L11 (10, 20) => 30
  • Exit semantics are unchanged: synthetic cases still never block exit; only declared assertions fail the run.
  • --only <names> (comma-separated) limits synthesis to the named functions — a directive function outside the list keeps the default exclusive behavior. --only without --both-paths is a usage error.
  • --freeze + --both-paths is a usage error: freeze solidifies directive witnesses, a different product face.
  • In --json, each case's source field separates the paths: "directive" / "callsite" / null (entry@ fallback).

Usage sites (--from)​

--from <paths…> points at usage-site files — tests, examples, upstream apps. Nudo harvests their real call records and injects each matched call as a call@L case, so argument shapes come from how the code is actually used rather than from hand-written directives. The two-phase harvest, the attribution gate, and trial numbers live in Call-Site Discovery.

Machine-readable and algebra faces​

--json emits CaseJson v1 — single file only; cannot combine with --abs or --freeze — with version / file / summary / functions[].cases[] (extensional args / result / throws, plus lossless argsAbs / resultAbs / intension where available) and an assertions summary on top. Excerpt (trimmed):

{
"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 still exits 1 when a declared assertion fails.

--abs prints the check --abs algebra face (per-function shape + conf) first, then the case report — declared assertion failures stay visible and still block exit. --watch / -w re-runs on file changes (a mode flag, not a verb).

test vs check​

nudo checknudo test
RoleGate: L1 explicit contracts + L2 entry may-throwReport: per-case ground truth + declared assertions
PrintsSignatures (always, even on success) + issuesEvery case (call@ / entry@ / debug) + assertions summary
Exit 1Any error-level diagnosticAny declared assertion failed
CIThe product gate (analogue of tsc --noEmit)Optional: declared assertions, freeze drift

Observation is not a separate verb — it lives in check signatures, test case reports, and IDE hover.

Options​

OptionDescription
--watch / -wRe-run on changes (flag, not a verb)
--from <paths…>Usage-site files whose calls become call@L cases
--freeze[=mode]Write synthesized cases back as @nudo:case directives (add default / update)
--both-pathsDirective + synthesized call@/entry@ witnesses for the same function in one round (exit semantics unchanged; not with --freeze)
--only <names>With --both-paths: limit synthesis to the named functions (comma-separated)
--dry-runWith --freeze: print a unified diff instead of writing
--exit-on-diffWith --freeze --dry-run: exit 1 when the diff is non-empty
--jsonCaseJson (single file; not with --abs / --freeze)
--absAlgebra face (as check --abs), then the case report

Full flag and exit-code tables: CLI Reference.

Next​