JsonUI
GuidesContract gapsBranch contracts say what a method does for the outcomes they list. `jsonui-test contracts coverage` asks the reverse: of every response status the OpenAPI documents for an operation a screen reaches, which does a contract answer, which are excluded and why, and which does nobody answer. It comes with the declarations that let a contract say "on purpose", and with a bound that makes generated branch tests fail on a call no row reaches.11 min read
1. What it answersA branch contract says what a method does for the outcomes its rows list. Nothing said which outcomes it leaves out — and an operation that documents five response statuses gives the method five outcomes to handle, whether or not anyone wrote them down. `jsonui-test contracts coverage` reads the contract from that side: for every screen and platform, every status the OpenAPI documents for an operation the screen reaches, and who answers it. Answering is not only writing a row. A plain difference between the documented statuses and the rows cannot tell "forgot" from "does not tell these apart on purpose" — an absence means both — so the second meaning gets somewhere to be written: a row can claim more statuses, a method can exclude one with a reason, a screen can say why no method here reaches an operation, and the app can admit the calls its network layer makes on its own. This page covers the command, those declarations, and the other half of the check that comes with them: every generated branch test fails when the method calls a declared route its rows do not reach. `jsonui-test validate` reports the same result on every run, and fails on entries not in a recorded baseline (section 8).What it needs, each measured as a refusal rather than read from a list: `mock.swagger` in jui.config.json naming the OpenAPI documents, or it cannot start; the platforms, declared in jui.config.json or named with `--platform` — with neither it exits 2 with `jui.config.json declares no platforms — name one with --platform`; and mocks for the operations. An operation is one that a repositories or useCases method names as its `endpoint` — the same set the branch tests route; an endpoint listed only in `dataFlow.apiEndpoints` is counted apart as an unbound endpoint (section 7). Agents reach the same report through the MCP tool `test_contracts_coverage`, which returns the command's JSON and treats its `exit` as the verdict.
2. A worked exampleThe branch-contracts guide's example, carried one step further. `updateProfile` documents 200, 401, 409, 422 and 500. The method already answers 200 (the success row) and 500 (the failure row). The view model shows the same failure message for a 409 conflict, so the failure row claims that status too with `alsoStatuses`. The app signs the user out on a 401 whatever the screen, so the method excludes that status with a reason. 422 is left unanswered on purpose:
ProfileScreen.spec.json — branchContracts.methods
// mock scenarios: success 200 · failure 500 · conflict 409 · invalid 422 · expired 401
"onTapSave": {
"baseline": { "isSaving": false },
"branches": [
{ "when": { "cond": "!formValid" },
"then": { "data.errorMessage": "@profile_screen_invalid", "api": "none" } },
{ "when": { "cond": "formValid", "api.updateProfile": "success" },
"then": { "transition": "HomeScreen",
"api.updateProfile.request": { "nickname": "@data.form" } } },
{ "when": { "cond": "formValid", "api.updateProfile": "failure" },
"alsoStatuses": { "api.updateProfile": ["409"] },
"then": { "data.errorMessage": "@profile_screen_failed",
"api.updateProfile": "called" } },
{ "note": "double-tap guard: second tap while isSaving is dropped" }
],
"excludedOutcomes": {
"api.updateProfile": {
"401": { "by": "unit",
"reason": "the session layer signs the user out on 401 for every screen" }
}
}
}
Run on that fixture, the web block puts every status in a bucket and names the one nobody answered. `partial` means the method answers other statuses of the same operation — the most common gap, and the one a reader of the contract is least likely to notice:
contracts coverage — the example, web block
$ jsonui-test contracts coverage --platform web
contracts coverage (project platforms: web, android, ios)
app contracts: docs/screens/json/app_contracts.spec.json · apiOutcomeRules 1
[platform=web] spec=profile_screen units 1 contracted methods 1 of 1
statuses required 5 = row 3 (alsoStatuses 1) + unit 1 + unreachable 0 + unexpressible 0 + not-evaluated 0 + uncovered 1
uncovered 1 = partial 1 + default-only 0 + unattributed 0
uncovered partial onTapSave × api.updateProfile PUT /api/items 422
info guard-only 1 · note branches 1 · also_statuses_rows 1 · also_statuses_arrange_differs 0 · side_calls_admitted 0 · reference_holds_on_success_row 0 · route_overlaps 0 · dataFlow methods without endpoint 0
outside required 0 = unreached-op 0 + n/a(default response) 0 + n/a(no scenario) 0 + n/a(platform-excluded) 0
n/a (E) no mock 0 · not in OpenAPI 0 · unbound endpoint 0 · non-HTTP 0
[platform=web] total n/a(no mock) 0 (screens 0) · n/a(not in OpenAPI) 0 (screens 0) · n/a(unbound endpoint) 0 (screens 0) · n/a(non-HTTP) 0 (screens 0)
[platform=web] total units 1 · statuses required 5 = row 3 + unit 1 + unreachable 0 + unexpressible 0 + not-evaluated 0 + uncovered 1 (partial 1 + default-only 0 + unattributed 0)
[platform=web] baselined 0 (matched 0 · new 1 · stale 0) — no baseline file: every entry is new
[platform=web] data (report only) units 0 · arranged 0 · produced 0 · neither 0 · screens evaluated 1 of 1 (layout not linked 0 · layout missing 0 · unresolved include 0) · Bool not in layout 1 · visibleElements not in layout 0 (cannot check 0) · cells not bound 0
[platform=web] exit 1 (uncovered)
exit 1 (composed 2 > 1 > 3 > 0) statuses required 5: 1 uncovered — write a row (alsoStatuses if the VM treats it like another status), or an exclusion with a reason
A row for the 422 — the form's validation message — closes it: `row 4 (alsoStatuses 1)`, `uncovered 0`, exit 0. The generator counts the copy as well: for the contract above its summary reads `3 declared branch(es), 1 more from alsoStatuses, 1 note-only listed as comments`, and the 409 copy is a test of its own, served from the mock scenario whose status is 409 (`[+409 via conflict]` in its title), so the claim is checked rather than taken on trust.
one row for the 422, and the block again
// one more row, before the note
{ "when": { "cond": "formValid", "api.updateProfile": "invalid" },
"then": { "data.errorMessage": "@profile_screen_invalid" } }
 
$ jsonui-test contracts coverage --platform web
…
statuses required 5 = row 4 (alsoStatuses 1) + unit 1 + unreachable 0 + unexpressible 0 + not-evaluated 0 + uncovered 0
uncovered 0 = partial 0 + default-only 0 + unattributed 0
…
[platform=web] total units 1 · statuses required 5 = row 4 + unit 1 + unreachable 0 + unexpressible 0 + not-evaluated 0 + uncovered 0 (partial 0 + default-only 0 + unattributed 0)
[platform=web] exit 0 (pass)
exit 0 (composed 2 > 1 > 3 > 0) statuses required 5
3. Where each status landsEvery documented status lands in exactly one bucket, per screen, view-model method, operation and platform. The arithmetic is printed on every block, so a count can be checked rather than trusted: required = row + unit + unreachable + unexpressible + not-evaluated + uncovered, uncovered = partial + default-only + unattributed, and what is not required is listed apart as outside required.
every documented status, exactly one bucket
bucket | a status lands here when
row | a row serves it in `when` by scenario name — the route's default scenario is
| not an answer — and the row's `then` says more than "the op was reached";
| an alsoStatuses copy counts here and is reported apart
unit | excludedOutcomes, by: unit — a unit test covers it
unreachable | excludedOutcomes, by: unreachable — it cannot arrive here
unexpressible | excludedOutcomes, by: unexpressible — only a note branch could say it
not-evaluated | the method's row for the op could not be bound
uncovered · partial | the method answers other statuses of the op, not this one
uncovered · default-only | the method reaches the op but answers none of its statuses
uncovered · unattributed | no method's rows reach the op, and unreachedOps does not say why
outside required | unreached-op (unreachedOps says why) · n/a(default response)
| · n/a(no scenario) · n/a(platform-excluded)
4. Answering a statusEvery uncovered status has three honest answers, in order of preference, and the command's closing line names them: write a row; if the view model treats the status like one a row already serves, add it to that row's `alsoStatuses`; if no row can be written, exclude it with a reason. Only the first two are checked by anything.• A row — the status gets its own branch with its own `then`. This is the answer the rest of the toolchain can verify: the generated test serves the status and checks the outcome.• `alsoStatuses` on a row — `{ "api.<op>": ["409"] }`: the row's `then` holds for these statuses of that operation too. Each status becomes its own generated test, served from the mock scenario with that status, so the claim is checked rather than excluded. The key must be an `api.<op>` that the row's `when` names with a scenario, and the statuses are plain numbers — no ranges, no `default`.• `excludedOutcomes` on a method — `{ "api.<op>": { "<status>": { by, reason, platforms? } } }`: the method reaches the operation but has no row for that status, and why. `by` is closed: `unit` (a unit test covers it), `unreachable` (the status cannot arrive here), `unexpressible` (only a note branch could say it). There is no `distinguish: false` — folding a status into another outcome is `alsoStatuses`, which a test then checks — and no `by: method`: the method reaches the operation, so its own row can always be written. Exclusions are claims nothing verifies, which is why they come last and are counted apart.• `branchContracts.unreachedOps` — `{ "api.<op>": { reason, platforms? } }`: no contracted method on this screen calls the operation (the parent screen does, say). Measured: an operation no row reaches puts its two statuses under `unattributed` and exits 1; with a reason in `unreachedOps` they move to `outside required 2 = unreached-op 2` and it exits 0. The bound in section 6 keeps the claim honest — a method that does call the operation is calling a declared route its rows do not reach.• `metadata.platforms` — the platforms the screen exists on. A block for any other platform does not count the screen: measured with `["ios", "android"]`, the web block prints `screens on web 0 of 1 (metadata.platforms)` and exits 0 (empty).• A harness condition — for a call the method makes only under a precondition the test harness does not have, such as a signed-in session. No mock can arrange that, so an exclusion would not be true of the status and `unreachedOps` would be false. Declare the condition once in the app contracts spec's `harnessConditions` and name it in a row's `when` as `"harness.<name>": "<value>"`; coverage counts such rows as ordinary rows and reports how many as `condition_rows` (1 for one such row, measured). The Branch tests guide covers the declaration and the hook that arranges it.`jsonui-doc validate spec` checks the shape of all of these — keys, types, the closed sets, and references inside the same document — and a shape error fails validation. It does not check whether an excluded status still exists or whether an operation resolves: that needs the OpenAPI document and the mocks, and belongs to the coverage command. One mistake at a time, seeded into the example:
jsonui-doc validate spec — one seeded mistake each
# excludedOutcomes with by: "method"
[ERROR] branchContracts.methods.onTapSave.excludedOutcomes.api.updateProfile.401.by:
'method' is not an exclusion: this method reaches the operation, so its own row
can always be written — write the row
# alsoStatuses with a range
[ERROR] branchContracts.methods.onTapSave.branches[2].alsoStatuses.api.updateProfile[0]:
'4XX' is a range — alsoStatuses takes plain statuses (v1: a range would make the
generator read OpenAPI to know which statuses it stands for). List the statuses
# apiOutcomeRules written into the screen spec
[ERROR] apiOutcomeRules: apiOutcomeRules belongs in the app_contracts_spec — it admits the
calls the app's network layer makes for every screen. A screen's own handling of a
status is a row in branchContracts (alsoStatuses for statuses the row treats alike)
# an app contracts spec with rules and no unitContracts
[ERROR] unitContracts: Required field 'unitContracts' is missing
[ERROR] apiOutcomeRules[0].verifiedBy[0]: 'signs_out_on_401' is not a case in this file's
unitContracts
5. What the app does for every screen: apiOutcomeRulesSome calls are not the screen's doing. When a request ends in a terminal 401, the app's network layer may post a logout on its own, from any screen — and once calls are bounded (section 6), that post would turn a generated test that serves a 401 red for a reason no screen contract can fix. `apiOutcomeRules` is where the app admits those calls, once, in the app contracts spec: a document of `"type": "app_contracts_spec"` that holds the app-wide `unitContracts`. Each rule has five keys, all required: `id`; `statuses`, plain numbers; `sideCalls`, operationIds (not `VERB /path`); `verifiedBy`, names of unit cases declared in the same file; and `reason`. That is why `unitContracts` is required beside `apiOutcomeRules` — a rule names the unit test that proves the side call, so a file of rules alone is refused. An app contracts spec that holds only `harnessConditions` needs none. A rule in a screen spec is refused too: a screen's own handling of a status is a row.
app_contracts.spec.json
{
"type": "app_contracts_spec",
"version": "1.0",
"metadata": { "name": "AppContracts", "description": "app-wide behaviour" },
"unitContracts": [
{ "target": "SessionInterceptor",
"cases": [ { "name": "signs_out_on_401",
"intent": "a terminal 401 posts a logout and clears the session" } ] }
],
"apiOutcomeRules": [
{ "id": "session-expired",
"statuses": ["401"],
"sideCalls": ["postLogout"],
"verifiedBy": ["signs_out_on_401"],
"reason": "the network layer posts a logout after a terminal 401" }
]
}
A rule only admits calls; it says nothing about how the screen handles the status. Measured on the example with a row serving the 401 and a screen that also routes the logout endpoint: with the rule, that one test's bound allows `logout` next to `updateProfile`, every other test is unchanged, and the coverage info line counts `side_calls_admitted 1`; without it, the 401 test allows only `updateProfile`. The rule also works when the screen does not declare the side call at all: the generated test serves it anyway as a side route — under its operationId, with its mock's default scenario — and `generate branch-tests` says so on a `side routes:` line. It is admitted only in the tests whose served statuses the rule names, so a call to it anywhere else is the bound's red, and coverage requires nothing of it. A row may also say the side call must not happen — `"api.postLogout": "not-called"` in its `then`, even though the screen does not declare the operation (the only word allowed for it). Measured on the failure row: the row and its 409 copy each assert `api.postLogout: this row says not-called — called N time(s)`. Measured on the same example without the logout route: the 401 test allows `postLogout` next to `updateProfile`, every other test allows `updateProfile` alone, and the line reads `side_calls_admitted 1`. And `sideCalls` resolve only through generated mocks: a rule whose operationId no generated mock carries is a declaration error that tells you to run `jsonui-test mock generate`.
6. The bound in generated testsThe coverage command counts which statuses a method's rows answer. The generated tests hold the other side: a method may not call a declared route its rows do not reach. Both read the same set, so deleting the row that reaches an operation does not make that operation's statuses disappear from the count — the test that stopped declaring the call fails while the call still happens. On all three platforms each generated test installs the mock, builds the harness, lets the construction settle, writes the arranged state, calls `rec.mark()`, runs the act, and checks the bound before the `then` entries. The act ends when its work has landed instead of after a fixed drain — no request in flight, 400 ms of quiet, and every op the row expects recorded — and the bound's message names that window (branch tests guide, section 1). Verbatim from the generator (on web the act's wait is `settleQuiet`, and the wait after the harness is built is `settleHarness`), the 409 copy of the example's failure row:
profile_screen.branches.test.ts — @generated, web
it("branch 3: cond=\"formValid\" & api.updateProfile=\"failure\" [+409 via conflict]", async () => {
const rec = installFetchMock(ROUTES, {"updateProfile": "conflict"}, apiOriginsOf(harnessModule), "profile_screen.onTapSave branch 3: cond=\"formValid\" & api.updateProfile=\"failure\" [+409 via conflict]");
try {
const h = createHarness();
await settleHarness();
h.setState({"isSaving": false, "form": {"nickname": "a"}});
rec.mark();
await (h.vm as any).onTapSave();
await settleQuiet({ rec, expect: ["updateProfile"] });
expect(rec.unexpectedOps(["updateProfile"]), "declared routes called (within the act and until no request was in flight for 400 ms after it) outside what this method's rows reach — if the method makes the call, say so in the row whose act makes it (then api.<op>: \"called\"); that allows <op> in every row of this method that does not mention it, so a row that must not make the call says api.<op>: \"not-called\". If the app's network layer makes it, admit it with apiOutcomeRules").toEqual([]);
reportUnmatched(rec.unmatchedCalls(), null, "profile_screen.onTapSave branch 3: cond=\"formValid\" & api.updateProfile=\"failure\" [+409 via conflict]");
reportUnmatchedForeign(rec.unmatchedForeign(), "profile_screen.onTapSave branch 3: cond=\"formValid\" & api.updateProfile=\"failure\" [+409 via conflict]");
reportEarlierRowCalls(rec.earlierRowCalls(), "profile_screen.onTapSave branch 3: cond=\"formValid\" & api.updateProfile=\"failure\" [+409 via conflict]");
expect(h.readField("errorMessage")).toEqual(resolveString(h, "profile_screen_failed"));
expect(rec.countFor("updateProfile")).toBeGreaterThan(0);
} finally {
rec.restore();
}
}, ROW_TIMEOUT_MS);
When the bound fails, the message is the instruction. If the method makes the call, say so in the row whose act makes it (`then api.<op>: "called"`). If the app's network layer makes it, admit it with `apiOutcomeRules`. Calls to routes the screen does not declare are recorded as `(unmatched)` and bounded by nothing — neither here nor in the coverage count.Read the allowance correctly, because it is wider than one row. It is per method: a `called` in one row allows the operation in every row of the method that does not mention it. So a regression in which a sibling row starts making the call stays green unless that row says `api.<op>: "not-called"`. The failure message states both halves; the contract keeps the second only if someone writes it. The same release made the reads count only the act — `countFor`, `matchedCalls` and `lastBodyFor` see the calls after the mark, and `api: "none"` means none during the act — and the Branch tests guide covers that window and what it changes for hand-written tests.
7. Reading the exit, the totals and the floorExit is per platform block, composed 2 > 1 > 3 > 0 for the process: 0 pass (or empty, when no screen exists on the platform), 1 something uncovered or a declaration error, 2 cannot start, 3 something could not be evaluated and nothing was found uncovered. Each block ends with two totals lines. One carries the n/a counts — `n/a(no mock)`, `n/a(not in OpenAPI)`, `n/a(unbound endpoint)`, `n/a(non-HTTP)`, each with the number of screens it came from. The other carries the statuses summed over the block's screens — units, statuses required, and its breakdown; measured on a block of two screens with 5 required each, it reads `statuses required 10 = row 7 + unit 2 + … + uncovered 1`. The process's last line repeats the required count. Each block also prints a `baselined` line, which compares its entries with the recorded baseline (section 8), and a `data` line, which is report only and never moves the exit: it counts the Bool fields and state values the screen's layout binds, and whether rows arrange or assert them. Read the per-screen `n/a (E)` lines as each screen's own: the one right above a block's exit line is the last screen's, not the total. When a block exits 1 and something could not be evaluated as well, `uncovered` is a floor — the statuses behind the unevaluated part were never counted — and the block says so on its own line. The JSON carries the same per platform: `totals` holds units, contracted methods, statuses required, the uncovered and outside-required breakdowns and `na_endpoints`, next to `floor`. Measured by adding an endpoint to `dataFlow.apiEndpoints` only, first with the 422 row in place, then without it:
an endpoint only in dataFlow.apiEndpoints — with the 422 row, then without
# with the 422 row in place
n/a (E) no mock 0 · not in OpenAPI 0 · unbound endpoint 1 · non-HTTP 0
note GET /api/items/{id} is in dataFlow.apiEndpoints but is the endpoint of no repositories / useCases method — branch tests do not route it (a call is recorded as (unmatched)); bind it to the method that calls it
[platform=web] total n/a(no mock) 0 (screens 0) · n/a(not in OpenAPI) 0 (screens 0) · n/a(unbound endpoint) 1 (screens 1) · n/a(non-HTTP) 0 (screens 0)
[platform=web] total units 1 · statuses required 5 = row 4 + unit 1 + unreachable 0 + unexpressible 0 + not-evaluated 0 + uncovered 0 (partial 0 + default-only 0 + unattributed 0)
[platform=web] exit 3 (unmeasured)
exit 3 (composed 2 > 1 > 3 > 0) statuses required 5: some statuses could not be evaluated — see not-evaluated and n/a above
 
# without it
uncovered partial onTapSave × api.updateProfile PUT /api/items 422
…
[platform=web] total n/a(no mock) 0 (screens 0) · n/a(not in OpenAPI) 0 (screens 0) · n/a(unbound endpoint) 1 (screens 1) · n/a(non-HTTP) 0 (screens 0)
[platform=web] total units 1 · statuses required 5 = row 3 + unit 1 + unreachable 0 + unexpressible 0 + not-evaluated 0 + uncovered 1 (partial 1 + default-only 0 + unattributed 0)
[platform=web] uncovered is a floor: n/a(unbound endpoint) 1 — not evaluated, so more may be uncovered
[platform=web] exit 1 (uncovered)
exit 1 (composed 2 > 1 > 3 > 0) statuses required 5: 1 uncovered — write a row (alsoStatuses if the VM treats it like another status), or an exclusion with a reason; uncovered is a floor on web
 
# --json, the same run: "floor": {"unbound": 1},
# "totals": {"units": 1, "statuses_required": 5, …, "na_endpoints": {"no_mock": 0, "not_in_openapi": 0, "unbound": 1, "non_http": 0}}
8. validate, the baseline, and the gate`jsonui-test validate` reports contracts coverage after its own summary, one line per platform, and fails on it. Measured with a 422 uncovered on all three platforms, the run is `Result: FAILED`, exit 1. `--no-coverage-check` skips the section and says so — on the same example `coverage skipped (--no-coverage-check)`, exit 0. For a project that already has uncovered statuses the gate would otherwise leave two ways out, closing everything at once or switching the check off, so `jsonui-test contracts baseline` gives a third: record today's entries once in `<spec_directory>/contracts_coverage_baseline.json`, commit it, and let the gate hold every new entry to the rule. The first write is the user's decision — without `--initial` the command refuses and says it would accept all current debt — and after that the file only shrinks: the command keeps what the file and the run both hold and never adds an entry. Validate fails on an entry not in the file (new), on a recorded one that is closed (stale, because it would silently swallow the same entry if it came back), and on a recorded one gone from the run (vanished — dropping an endpoint, a status or a platform is not a way out of the debt). What can never be baselined — a declaration error, a row that could not be evaluated — fails whatever the file says, and while it is present the command writes nothing. Measured on the example, three platforms each with the 422 unanswered:
validate and the baseline — the example, three platforms
$ jsonui-test validate --no-install --no-mock-check tests/screens
…
Result: FAILED
Files: 3, Errors: 0, Warnings: 0, Coverage: FAILED (exit 1; web: 1 not in the baseline (profile_screen 1); android: 1 not in the baseline (profile_screen 1); ios: 1 not in the baseline (profile_screen 1))
…
coverage: web units 1 · statuses required 5 · row 3 · excluded 1 · uncovered 1 · not evaluated 0 → exit 1 (uncovered) · baselined 0 (matched 0 · new 1 · stale 0) — no baseline file: every entry is new
(android and ios print the same line)
validate gates on contracts coverage: it fails on entries not in the baseline, on baselined entries that are closed, on baselined entries gone from the run, and on what cannot be baselined
# exit 1
 
$ jsonui-test contracts baseline
contracts baseline: nothing written — recording the first baseline accepts all current debt (3 entries) — the user's decision; run with --initial
$ jsonui-test contracts baseline --initial
wrote docs/screens/json/contracts_coverage_baseline.json
removed 0 · kept 3 · new 0 not added
$ jsonui-test validate --no-install --no-mock-check tests/screens
…
Result: PASSED
Files: 3, Errors: 0, Warnings: 0, Coverage: passed (exit 1)
# exit 0 — the uncovered 422 is in the baseline
 
# a row answers the 422; the recorded entries are now closed (stale)
$ jsonui-test validate --no-install --no-mock-check tests/screens
…
Result: FAILED
Files: 3, Errors: 0, Warnings: 0, Coverage: FAILED (exit 0; web: 1 baselined but closed (profile_screen 1); android: 1 baselined but closed (profile_screen 1); ios: 1 baselined but closed (profile_screen 1))
…
coverage: web units 1 · statuses required 5 · row 4 · excluded 1 · uncovered 0 · not evaluated 0 → exit 0 (pass) · baselined 1 (matched 0 · new 0 · stale 1) — stale entries are closed: run `jsonui-test contracts baseline` to drop them
(android and ios print the same line)
# exit 1
 
$ jsonui-test contracts baseline
updated docs/screens/json/contracts_coverage_baseline.json
removed 3 · kept 0 · new 0 not added
$ jsonui-test validate --no-install --no-mock-check tests/screens
…
Result: PASSED
Files: 3, Errors: 0, Warnings: 0, Coverage: passed (exit 0)
# exit 0
9. What it does not tell youWhat a clean run does not mean, stated where the command stops:• It gates `jsonui-test validate` and nothing else: validate fails on what the baseline does not hold. Neither the build, nor the verify step, nor a CI that does not run `jsonui-test validate` ever looks at it, and `--no-coverage-check` switches it off in validate too, saying so (`coverage skipped (--no-coverage-check)`, exit 0 on the example).• Exclusions are claims. `by: unit` is not checked against any unit test and `unreachable` is not checked against the server; they are counted apart so that the share of a screen resting on them stays visible.• It reads the OpenAPI you point it at. A response the server really sends but the document does not list is invisible here.• The population is the operations bound as an `endpoint` on a repositories or useCases method. A call the screen makes through anything else is outside both the count and the bound.• The bound is per method, not per row (section 6), and traffic to routes the screen does not declare is bounded by nothing.
10. Closing the gaps with an agentThe agents pack ships the procedure as `jsonui-define`'s Task 6, Close contract coverage. The conductor routes there when coverage reports uncovered outcomes, and `jsonui-test` sends that work there too, because it is spec work. The agent drafts, you decide, and the spec records: every decision lands as a row, an `alsoStatuses`, an `excludedOutcomes`, an `unreachedOps` or an endpoint binding — there is no other place a decision is kept. In four steps:• Measure one screen with the MCP tool `test_contracts_coverage` and read `exit`. 0 is quoted with its units and statuses required — units 0 means nothing was measured. 1 goes on to drafting. 2 is a config problem, and the agent stops. 3 means fixing what could not be evaluated: binding an endpoint, adding a scenario, adding a document to `mock.swagger`. A report whose `exit` is null is never read as a pass.• Draft from the spec, the OpenAPI document and the mock files only — the agent does not open ViewModel, Repository or UseCase source to decide how a status is handled. One draft per method, operation and status, in this order: `alsoStatuses` when the spec's own words say the view model treats the status like an existing row's; a new row whose `then` states what the spec says results; an exclusion only when neither can be written; for an unattributed operation, a row in the method that calls it, or `unreachedOps` with a reason; for a call made only under a precondition, a harness condition; and a question to you when the spec does not say. Prose that describes a state no field carries comes back as a gap in the spec, not as a draft.• Show, then write: one table per screen — method, operation, status, the draft, the JSON to add, the spec words it rests on — and only what you accept is written. What you do not accept stays uncovered, visibly; an exclusion is never added to make the number go down.• Close the loop: validate, measure again, and quote before and after from `platforms[].totals`. A new row that reaches an operation the method did not reach before adds a unit, so statuses required can grow; another round drafts those. Then the work goes to `jsonui-test` to regenerate the branch tests — each new row and each `alsoStatuses` copy is a new test, and one that goes red against the implementation is a finding for `jsonui-debug`, not a row to weaken.The drafts are only as good as the spec: reading the spec rather than the code is the point, so a behaviour the spec never states comes back as a question instead of being read off the implementation. And nothing here runs by itself — the agent takes this up when you ask it to close coverage, or when the MCP tool reports anything other than a pass; what the command reports gates `jsonui-test validate` only (section 8).
Keep going
Branch contractsThe declaration side: vocabulary, validate, and the decision table./guides/branch-contracts
Branch testsThe generated tests, their harness, and the act window./guides/branch-tests
Unit contractsThe unitContracts that `verifiedBy` points at./guides/unit-contracts