JsonUI
GuidesBranch testsOne branchContracts declaration, three platforms of real-stack unit tests: `jsonui-test generate branch-tests` emits vitest for web, JUnit4 (Robolectric) for Android, and XCTest for iOS from the same branch tables — mocking nothing but the HTTP boundary. This page covers the command, the generated files and who owns them, the harness contract on each platform, the errors that stop generation, and how to trust the result.13 min read
1. One declaration, three platforms`jsonui-test generate branch-tests <screen>` resolves `<spec_directory>/<screen>.spec.json` (from jui.config.json; `--spec` overrides) and emits three files per platform: an @generated test file — one test per declared branch (arrange = baseline, then the condition's witness, then when's data entries, later wins — a baseline that does not actually set up the pre-state is how a contract ends up asserting nothing, see section 12; act = the method plus settle(); assert = the then entries — and one inferred assert ahead of them when `when` carries `api.<op>: "<scenario>"`: that the route was hit at least once, failing as `route '<op>' declared in when was never hit (0 requests)`. Without it, a branch could arrange an error scenario and still go green off a local failure path that never issued the request. It is placed before the then entries so an unreached route is reported as the cause rather than as a data mismatch. It is inferred, not sovereign: write anything about that surface in `then` — `called`, `not-called`, `.request`, or `api: "none"` — and it is not emitted, measured on both `called` and `api: "none"`; an inferred assertion never contradicts or duplicates a written one), with note-only branches listed as numbered comments so the coverage boundary stays visible — an @generated shared runtime, and a consumer-owned harness skeleton emitted only when the file does not exist. Common prerequisites: `endpoint` declarations on the dataFlow methods the contract references, and mock files under the mocks directory (*.mock.json with source.method/path and named scenarios) — resolved as `--mocks-dir` first, then `mock.mockDir` from jui.config.json, then `tests/mocks`; when nothing binds, the error names the directory it searched and how many mock files it found there. Each platform then needs its own runner (sections 3–5). Agents reach the same generator through the `test_generate_branch_tests` MCP tool, which maps every flag above — restart Claude Code after updating the server so the new tool is visible.Ownership at a glance: the test file and the runtime are @generated — regenerate after every spec edit, they are rewritten in place; the harness (one per screen) is yours, and re-generation never overwrites it. `jui lint-generated` accepts the @generated pair with their one-line banner and leaves the harness out of its count, so a project that keeps them in a Generated folder is not red there.Validate also holds these endpoint declarations against the project's API canon — structurally opt-in: it fires only when the project has an api_directory with OpenAPI documents. Three warning classes: a path no document declares, a path declared but not for that HTTP method (the declared methods are listed), and parameter-spelling differences (the canonical spelling is quoted). Non-HTTP declarations (`RTDB onValue(...)` and the like) are always legal and never checked, and validation stays PASSED — these are warnings:
endpoint vs OpenAPI canon — one seeded drift each (validate stays PASSED)
[WARNING] ...methods[2].endpoint: Endpoint 'POST /api/ghosts' is not declared in any
OpenAPI document under api_directory — update the spec to the canonical route,
or document the route
[WARNING] ...methods[3].endpoint: Endpoint path '/api/items/{itemId}' is declared in the
API document but not for DELETE (declared: GET, PUT)
[WARNING] ...methods[1].endpoint: Endpoint path parameters differ from the API document:
spec '/api/items/{item_id}' vs canonical '/api/items/{itemId}'
The check is opt-in on the canon, not on the declarations — and it says so. If a spec declares endpoints and no OpenAPI document is found under api_directory, validate warns on that file and names both the directory it searched and the config that answered. The count carries its unit, because there are two: `N endpoint(s), declared in M place(s)`. Routes are unique on verb plus normalized path, so two spellings of one path parameter are one route; places count every site that declares one, and a spec listing a route in `apiEndpoints` as well as on a method declares it twice. Read routes for how much contract is unchecked and places for how much work the check skipped — measured on one fixture, dropping the `apiEndpoints` block took it from `2 endpoint(s), declared in 4 place(s)` to `2 endpoint(s), declared in 2 place(s)`. A run's total is the sum of what the batch prints; the notice is per file. Only one of the two columns survives that sum, though: places add up, because a declaring site belongs to exactly one file, while routes are made unique within a file and a route two specs both declare is reported by both. Measured — two specs sharing a single route each print `1 endpoint(s), declared in 1 place(s)` over a corpus of one route and two places. A parent spec contributes nothing of its own here: measured on a parent with two subs, only the subs' files carry the notice. It is not 'every route matches' — nothing was compared. A declared api_directory answers even when it holds nothing, so the walk does not fall through to a shallower config and borrow its canon. Measured on one fixture with a broken api_directory: one warning naming the broken path. A config that says nothing about the API still falls through to an ancestor's, which is what keeps a monorepo layout working — same fixture, one key removed, ancestor canon in force again. So on a face that declares api_directory, losing the canon produces either the notice or an unreachable-declaration error; the remaining silence is the case where no spec declares an endpoint at all, where there is nothing to compare and the zero is an honest zero. This site is that case: 103 specs, no endpoint declarations, no warnings.
two units, and what a broken api_directory looked like before it was named
docs/screens/json/Items.spec.json
[WARNING] dataFlow: 2 endpoint(s), declared in 4 place(s), were not checked: no
OpenAPI document was found under api_directory ('…/sub/docs/api', from
'…/sub/jui.config.json'). This is not 'every route matches' — nothing
was compared.
 
# drop the apiEndpoints block — the same two routes, half the places:
[WARNING] dataFlow: 2 endpoint(s), declared in 2 place(s), were not checked: ...
The runtime is shared per output directory, so the unit of regeneration is the project, not the screen. After a release that changes the runtime's shape, regenerating one screen swaps that shared file for everyone while the other screens' tests still expect the old one — they stop compiling. The command names the siblings it did not touch, so the situation is visible at the moment it is created; it still will not regenerate them for you, because rewriting generated files nobody asked about is the kind of help that costs more than it saves. You can ask instead of remembering: `generate branch-tests --check` writes nothing, reports drift against the @generated files on disk, and exits non-zero. Naming no screen covers every spec that declares branchContracts, for the same reason the unit of regeneration is the project. The drift it catches is one no other gate does — the generated test embeds copies of the mock scenario bodies, so editing a mock alone leaves the test asserting the old payload. Measured: after generating, changing only a mock body and regenerating nothing takes the run from `1 up to date, 0 stale` and exit 0 to a `[DRIFT]` line naming the test file, `0 up to date, 1 stale`, and exit 1.
the command names the siblings it did not touch
tests/unit/generated/jsonui-branch-runtime.ts (shared runtime)
note: 1 other generated test file(s) share this runtime — regenerate them too
if it changed shape (checkout_screen.branches.test.ts)
A screen that leaves the scan takes its generated test with it. When a spec is removed, or stops declaring branchContracts, a run over the whole project removes the test it had generated — `removed tests/unit/generated/settings_screen.branches.test.ts ('settings_screen' no longer declares branchContracts — its spec or its contracts are gone)` — and `--check` names it in a `[RETIRED]` line, counts it under retired and exits 1. The harness beside it is yours, so it is never removed: both modes name it in a `[WARN]` line, for you to delete with the screen. A run that names one screen removes nothing else; it prints a `note:` naming the other screen's test and saying to run without a screen name. A test is recognised by the screen its @generated banner names, so a file you wrote is never taken for one. Measured on this page's example with a second screen whose spec was then deleted, for web: `--check` exits 1, and regenerating leaves only the live screen's test.The shared runtime refuses on the READ side too: `countFor` and `lastBodyFor` reject an op no route declares, and name the ones that are declared. Answering 0 and nothing would be the defect: both are plausible values, so an assert written against a misspelled op would check nothing and stay green for as long as it existed. Generated asserts cannot reach the refusal, because every op they name comes from the same route table; it is there for the hand-written tests this runtime is exported for. Four edges are worth knowing before reading it as a guarantee — three shared, one that differs by platform. It does not reach a test that filters the public `calls` list by op directly, comparing the op field instead of calling either accessor: no name is passed to anything that could refuse it. That list is outside the act window as well: it keeps every call for diagnosis, including the ones made before `rec.mark()`. It only hides a defect where the assert expects zero or nothing — one expecting a value, a length, or a non-empty result goes red on its own. And ‘expects zero’ has a second form that never spells a zero: a count taken before the act and compared with the count after, which under a misspelled op is zero on both sides and agrees. The fourth is the per-platform one, and it was measured on the generated runtimes rather than taken from a note. On Android and iOS the route table is optional — `Recorder(routeOps: Set<String>? = null)` and `init(routeOps: Set<String>? = nil)` — and a recorder built without one refuses nothing, so a hand-written harness opts in by passing `routeOps`. On web there is no such recorder: `installFetchMock(routes, …)` takes the routes as a required argument and derives the declared set from them, so that face is always armed. Requiring the argument everywhere would have been a compile error in every hand-written harness that builds its own recorder, correctly spelled ones included, which is why it was not done.Two things frame every generated test, on all three platforms. The act has a window: the test installs the mock, builds the harness, lets the construction settle, writes the arranged state, and only then calls `rec.mark()` — `countFor`, `matchedCalls` and `lastBodyFor` read the calls made after the mark, so what the constructor fetched is not read as the method's doing, and `api: "none"` means no declared call during the act. A hand-written test that never calls `mark()` reads every call. And the calls have an upper bound: after the act, every declared route the method called must be one its rows reach — the test asserts that `rec.unexpectedOps([...])` comes back empty. The allowance is per method, not per row: a row that says `api.<op>: "called"` allows `<op>` in every row of the method that does not mention it, so a row that must not make the call says `api.<op>: "not-called"`; a call the app's network layer makes on its own is admitted with `apiOutcomeRules`. Calls to routes the screen does not declare are still recorded as `(unmatched)` and bounded by nothing. The generator's summary names what it read — `apiOutcomeRules: none (no app contracts spec declares them)` in the transcripts above, `apiOutcomeRules: 1 rule(s) from app_contracts.spec.json` when a file declares one. The generated rows end the act in a defined place. A generated row waits until no request is in flight, 400 ms have passed since a request last arrived or was answered, and each op the row expects has been called since `mark()`; it never returns quietly — an expected op still missing once nothing is in flight fails 10000 ms after the act, and work still in flight fails at the 31000 ms budget, each naming what it waited for. A fixed-time drain would read a view model that paused between requests half done, and a call it made at the end would not yet be recorded when the bound was checked — a green that checked nothing. On web that wait is `settleQuiet()`, and the exported `settle()` / `settle(n)` a hand-written test calls drains turns and waits for delayed responses, with no quiet window; `settle({ rec, expect })` is `settleQuiet`. The wait after the harness is built is `settleHarness()`: it drains one turn and returns if construction made no request and scheduled no timer, and is `settleQuiet()` otherwise — upstream records a row with nothing to wait for closing in about 17 ms instead of about 800. An `installFetchMock(routes)` with no row name is a single global mock, and only a generated row's named install keeps its row. On iOS and Android the generated rows wait through `settleUntilAnswered`, and the plain `settle()` drains a fixed time (iOS 80 × 5 ms, Android 60 × 5 ms). The bound's message states the window — `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` — and a call an earlier row's view model makes after its row ended does not count in a later row on web; it is named (`earlier_row_call`) on web, Android and iOS 26+. Web rows run under `ROW_TIMEOUT_MS` (twice the budget plus 5000 ms) instead of vitest's default 5000 ms. That is upstream's record. Measured here: the generated web rows call `await settleHarness()` after building the harness and `await settleQuiet({ rec, expect: ["updateProfile"] })` after the act. Regenerate every screen after taking a release. The bound is one half of the contract-gap check; the other half, and the declarations both read, have their own guide:A generated test does three things with requests, measured in the generated code on the page's example or read from the runtime it emits. A request during act that matches no declared route is answered 599 — a status no server returns — and the test reports it; the report names no release that will fail the test. Only the app's own API counts: a request to another host is reported as info, never a failure. On web the runtime cannot tell hosts apart by itself, so the screen's harness module exports `apiOrigins` (a relative URL is always the app's); iOS takes `apiOrigin` on the harness; Android needs nothing, because MockWebServer only ever sees the app's own requests. Second, a scenario's `delayMs` delays its response on all three platforms, so a row can make one of two parallel requests arrive last; `settle()` waits for every delayed response before it returns, and past 31000 ms it fails the test by name. Third, side calls an `apiOutcomeRules` rule names are served as side routes even when the screen does not declare them (Contract gaps guide, section 5). Each report is one line that names its row — `jsonui-test branch test [<screen>.<method> <row title>] <kind>: …` — written to stderr on web and Android and to xcodebuild's stdout on iOS. Called through the shipped web runtime with an unmatched request and a request to another host, it writes nothing to stdout and these two lines to stderr: jsonui-test branch test [profile_screen.onTapSave branch 2: cond="formValid" & api.updateProfile="success"] unmatched: POST /api/items/42/like reached no declared route and was answered 599, which no server returns — declare the route and its scenarios (dataFlow + mock); if a host named here is not the app's API, export apiOrigins from the harness jsonui-test branch test [profile_screen.onTapSave branch 2: cond="formValid" & api.updateProfile="success"] unmatched_foreign: 1 — POST https://analytics.example.com/v1/events Count them in the whole output, stderr included (`2>&1 | grep 'jsonui-test branch test \['`); `xcodebuild -quiet`, a pipe that keeps only stdout, or Android's test-results XML (the line goes to Gradle's console instead) will not show them.Contract gaps — which API outcomes the contracts answer →
2. Mock only the HTTP boundaryThe real ViewModel, UseCase, and Repository run in every test, and so does response decoding — the web runtime stubs fetch, Android points real Retrofit (and kotlinx-serialization decoding) at MockWebServer, iOS intercepts at URLProtocol under real Codable decoding. That is what lets "the call returned 2xx but the payload was wrong" failures land in the net instead of being mocked away. Every declared endpoint that has a mock answers with its default scenario, so a call the branch does not name still gets an answer rather than stopping the run. Such a call is not free, though: a declared route the method calls must be one its rows reach, or the generated bound fails the test (section 1).`api: "none"` asserts zero calls on the declared surface (the matched routes) — zero during the act: calls made while the harness was being built fall before `rec.mark()` and are not counted. Traffic outside that surface does not fail the contract either way. The runtime tells the two kinds apart: a request to the app's own API that matches no route is answered 599 and named in a warning, and one to another host — an analytics SDK posting telemetry, say — is an info line (section 1). This matters most on iOS, where interception is process-wide.Declare every operation the method reaches, not just the one the branch is about. A method that also calls another screen's API still makes that call under test; without a declaration it has no route, the request goes unmatched, and the run stops partway with a failure that reads like the branch itself is broken.File-backed scenarios — a CSV export, say, declared with `contentType` and `bodyFile` instead of an inline `body` — come back with their status, their declared content type and the file's text as the body. The generated test embeds that text, read relative to the mock file that declares the scenario, so `generate branch-tests --check` reports the tests stale when the file changes. The body is text, not an object, so reaching into it with `@response.<path>` is a generation error — the same mock boundary that section 5 of the contracts guide draws around server-chosen values. A file that is not UTF-8 text, such as a PDF, is refused by `generate branch-tests` by name, because the body is embedded in source; `mock serve` still sends it as it is.
3. Web (vitest)Web is the default platform — no flags needed. Outputs land under tests/unit/; the project needs vitest (scope its config to the unit directory so an existing Playwright `npm test` stays untouched). Two conventions hold for every transcript on this page: the tool prints paths absolute and they are shown here relative to the project root, and `<version>` on the closing line stands in for the number the tool prints there — that line names the toolchain that generated the files, and it is whichever one you ran rather than one this page can name for your install.
web (default) — output
$ jsonui-test generate branch-tests profile_screen
Generated branch tests for 'profile_screen':
tests/unit/generated/profile_screen.branches.test.ts (3 declared branch(es), 1 note-only listed as comments)
tests/unit/generated/jsonui-branch-runtime.ts (shared runtime)
tests/unit/branch-harness/profile_screen.ts (NEW harness skeleton — implement createHarness())
routes: updateProfile (from dataFlow.repositories[].methods[].endpoint,
not from the contract's api references)
apiOutcomeRules: none (no app contracts spec declares them)
 
1 screen(s) generated by jsonui-test <version>.
profile_screen.branches.test.ts — branch 2 (@generated)
it("branch 2: cond=\"formValid\" & api.updateProfile=\"success\"", async () => {
const h = createHarness();
h.setState({"isSaving": false, "form": {"nickname": "a"}});
const rec = installFetchMock(ROUTES, {"updateProfile": "success"});
const ref_form = h.readField("form");
try {
await (h.vm as any).onTapSave();
await settle();
h.expectTransition("HomeScreen");
expect(rec.countFor("updateProfile")).toBeGreaterThan(0);
expect(partialMismatches(rec.lastBodyFor("updateProfile"), { "nickname": ref_form })).toEqual([]);
} finally {
rec.restore();
}
});
If `jsonui-test` rejects branch-tests as an invalid choice, an older console script on your PATH is shadowing the toolchain — use the launcher at `~/.jsonui-cli/test_tools/jsonui-test`.
4. Android (Robolectric)Add `--platform android --package <pkg>`. Here --out-dir and --harness-dir point at the Kotlin test source root and the package path is appended automatically. The runtime brings MockWebServer plus a reflection-based BaseBranchHarness that reads and sets fields, StateFlows, and data-class state generically; scenario bodies are embedded, so the generated file is self-contained.
android — output
$ jsonui-test generate branch-tests profile_screen \
--platform android --package com.example.profile \
--out-dir app/src/test/java --harness-dir app/src/test/java
Generated branch tests for 'profile_screen':
app/src/test/java/com/example/profile/ProfileScreenBranchesTest.kt (3 declared branch(es), 1 note-only listed as comments)
app/src/test/java/com/example/profile/JsonuiBranchRuntime.kt (shared runtime)
app/src/test/java/com/example/profile/ProfileScreenBranchHarness.kt (NEW harness skeleton — implement createHarness())
routes: updateProfile (from dataFlow.repositories[].methods[].endpoint,
not from the contract's api references)
apiOutcomeRules: none (no app contracts spec declares them)
 
1 screen(s) generated by jsonui-test <version>.
Prerequisites: test dependencies (Robolectric, MockWebServer, kotlinx-coroutines-test, kotlin-reflect), `testOptions.unitTests.isIncludeAndroidResources = true` in the module's Gradle file, and a robolectric.properties that pins the sdk and names a plain Application class — a real DI-heavy Application will try to boot on the JVM and fail.
ProfileScreenBranchesTest.kt — branch 2 (@generated)
// branch 2: cond="formValid" & api.updateProfile="success"
@Test fun `onTapSave branch 2`() {
runBranchTest(routes, mapOf<String, Any?>("updateProfile" to "success"), ::createProfileScreenBranchHarness) { h, rec ->
h.setState(mapOf<String, Any?>("isSaving" to false, "form" to mapOf<String, Any?>("nickname" to "a")))
val ref_form = h.readField("form")
h.invoke("onTapSave")
h.settle()
h.expectTransition("HomeScreen")
assertTrue(rec.countFor("updateProfile") > 0)
assertEquals(emptyList<String>(), partialMismatches(rec.lastBodyFor("updateProfile"), mapOf<String, Any?>("nickname" to Ref(ref_form))))
}
}
5. iOS (XCTest)Add `--platform ios --module <app module>` — --module names the module the tests `@testable import`. Point --out-dir and --harness-dir at the test target's folder; with Xcode 16's synchronized folders, having the files on disk is enough — no project-file editing.
ios — output
$ jsonui-test generate branch-tests profile_screen \
--platform ios --module ProfileApp \
--out-dir AppTests --harness-dir AppTests
Generated branch tests for 'profile_screen':
AppTests/ProfileScreenBranchesTest.swift (3 declared branch(es), 1 note-only listed as comments)
AppTests/JsonuiBranchRuntime.swift (shared runtime)
AppTests/ProfileScreenBranchHarness.swift (NEW harness skeleton — implement createHarness())
routes: updateProfile (from dataFlow.repositories[].methods[].endpoint,
not from the contract's api references)
apiOutcomeRules: none (no app contracts spec declares them)
 
1 screen(s) generated by jsonui-test <version>.
ProfileScreenBranchesTest.swift — branch 2 (@generated)
// branch 2: cond="formValid" & api.updateProfile="success"
func test_onTapSave_branch_2() {
runBranchTest(routes: routes, overrides: ["updateProfile": "success"],
harnessFactory: createProfileScreenBranchHarness) { h, rec in
h.setState(["isSaving": false, "form": ["nickname": "a"]])
let ref_form = h.readField("form")
h.invoke("onTapSave", args: [])
h.settle()
h.expectTransition("HomeScreen")
XCTAssertGreaterThan(rec.countFor("updateProfile"), 0)
XCTAssertEqual(partialMismatches(rec.lastBodyFor("updateProfile"), ["nickname": Ref(value: ref_form)]), [])
}
}
Interception is process-wide: the runtime registers a URLProtocol and also swizzles the URLSessionConfiguration.default / .ephemeral getters, so network layers that build their own sessions from those configurations are captured too — nothing reaches the real network.Reads are generic, writes are typed: the runtime reads any field via Mirror traversal (unwrapping @Published); Swift has no reflective writes, so setState goes through the generated Data.update(dictionary:) and declared event handlers — that typed side lives in your harness.A `null` expectation compares equal to both Swift nil and NSNull(): assertFieldEquals normalizes both sides on entry, so a harness readField can return an Optional property as-is — nothing to remember.Harnesses are deliberately retained for the process lifetime: deallocating @MainActor types on teardown goes through the isolated-deinit back-deploy shim on current simulators and crashes with an invalid free, so the runtime keeps the few test VMs alive instead — the full reason is a comment in the generated runtime.With Xcode 16's synchronized folders (FileSystemSynchronizedRootGroup), the generated files are picked up by the test target as soon as they exist on disk.
6. The harness — your side of the contractOne hand-written file per screen: it constructs the real ViewModel against the mock boundary and implements setState, invoke, expectTransition, and resolveString. The shared rule across all three platforms: unknown names must fail loudly — a harness that silently ignores a name it does not know would quietly weaken every branch that uses it. The shared runtime checks the other half of that contract, which is what the harness gives back. `resolveString` is called through a wrapper that rejects a result equal to the key it was handed, or a full key ending in `_<key>`, with a message naming both the key and what came back. The reason is the render path rather than the field: `@{...}` bindings are not resolved when a component renders, so a data field holds resolved text, and an expectation compared against it has to be resolved text too. That reason is worth reading past the easier one — a field also carrying a server message has no front-end key for that value, which is true and sufficient on its own, but taken as the reason it invites the conclusion that a field servers never touch may return a key, and that is wrong for every field. The check fires on the call rather than at setup, because a harness whose string table is empty never calls `resolveString` at all: it is broken and green until the screen's first `@key` contract arrives. Measured at its edges. Text that happens to be a single identifier-shaped word ending in the key is rejected too — `Some_title` for `title` — which is a false positive kept on purpose, because it errs toward refusing and names what it refused. Returning nothing fails like returning a key, and the message says both — a key, or nothing, means the table did not resolve. That sentence comes from one source rather than three copies, so a Swift or Kotlin harness fails with the same words a web one does — which is what makes it a shared rule rather than three rules that happen to agree today. The words are the shared part, and only the words: the prose is single-sourced while the key and the returned value are quoted per language, so the renderings differ where they should and agree where the claim is. One edge is still open: the test is emptiness, not blankness, so a harness returning a single space passes. The three flavors:web — plain closed maps: screenRoutes from transition destinations to URLs, and a closed string-key map (keep it closed so string-usage lint gates stay computable).On web, write the ViewModel through the runtime's `applyDeclaredKeys(vm, state)` rather than assigning every key in a loop, then hand the same object to the data store. A plain loop invents ViewModel properties for data-only fields — values the screen updates through the store and the ViewModel never declares — and because readField consults the ViewModel first, those invented properties shadow the store for the rest of the test: the branch then fails against a correct implementation. Android skips writes to undeclared fields in its base harness and iOS goes through a typed switch, so this one is web-only. For a scenario with no inline body, all three runtimes return an empty response, as the mock server does. The generated types also carry an index signature on purpose: output the project cannot hand-edit must not break its type-check when a mock later grows a key nobody anticipated.android — extend the generated reflection-based BaseBranchHarness (fields, StateFlows, and `_data` data-class copies are handled generically) and add closed maps for strings and transition predicates.ios — everything typed: setState through Data.update(dictionary:) plus event-handler routing for VM-internal state; invoke / expectTransition / resolveString as closed switches. The skeleton's own comment states the contract:
ProfileScreenBranchHarness.swift — skeleton contract comment
// Swift has no reflective writes, so this harness is the typed side of the
// contract: setState routes through the generated Data.update(dictionary:)
// (plus event-handler calls for VM-internal state), while invoke /
// expectTransition / resolveString are closed switches — an unknown name
// must fail loudly, never soften.
The harness has a second, app-wide half for preconditions no mock can arrange — a signed-in session, say, which the view model reads at construction. Declare each once in the app contracts spec as `harnessConditions: { "<name>": { values, default, reason } }` and name it in a row's `when` as `"harness.<name>": "<value>"` (not `cond`, which names a witness). Every generated test then calls `arrangeCondition(name, value)` (awaited on web) for every declared condition — the row's value, or the default — after the mock is installed and before the screen's harness is built. The hook is one consumer-owned file per app in the harness directory: `branch-conditions.ts` on web, `BranchConditions.kt` on Android, `BranchConditions.swift` on iOS, each written once as a skeleton that throws for every pair until you implement it, so no row passes on the harness's bare state. Make each pair produce what production would give the view model to observe; the tool cannot see whether it does. Measured on the page's example with a `session` condition and one row naming it: `jsonui-doc validate spec` passes the row, and it also passes a row naming an undeclared condition or a value outside `values` — those are refused by `generate branch-tests` and `contracts coverage` instead (exit 1, naming the condition and the allowed values). With the hook file deleted, `generate branch-tests --check` warns that it is missing and still exits 0. A project that declares no `harnessConditions` gets none of this. Two more. An app contracts spec that declares only `harnessConditions` is valid on its own — `unitContracts` is required only beside `apiOutcomeRules`. And whether a condition changes anything is a question the rows do not answer — a row naming `harness.session: "present"` stays green if the session decides nothing it asserts — so `generate branch-tests --condition-controls` adds, after each row that names a condition away from its default, a control that runs the same act and assertions with every condition at its default and never fails; when they still hold it reports `condition_without_effect` — on the same row-named line as the request reports above. Measured on the example: the summary gains `condition controls: 1`, and the file gains `branch 2: … [control: session=absent instead of present]`. It is off by default, because it doubles those rows.
a harness condition — declaration, row, generated call
// app_contracts.spec.json
"harnessConditions": {
"session": { "values": ["absent", "present"], "default": "absent",
"reason": "whether a user is signed in; the view model reads it at construction" }
}
 
// a row in the screen spec
{ "when": { "cond": "formValid", "harness.session": "present", "api.updateProfile": "success" },
"then": { "transition": "HomeScreen", "api.updateProfile": "called" } }
 
// generated (web): the condition is arranged before the harness is built
const rec = installFetchMock(ROUTES, {"updateProfile": "success"});
try {
await arrangeCondition("session", "present");
const h = createHarness();
await settle();
…
 
// and the two lines generate branch-tests adds to its summary
tests/unit/branch-harness/branch-conditions.ts (NEW harness-conditions hook skeleton, one per app — implement arrangeCondition(); until then every branch test throws in it)
harnessConditions: session from app_contracts.spec.json — every branch test calls arrangeCondition for each
7. Formatted strings: pseudo-key + harness formatting`@key` resolves one whole entry of the string table — there is no vocabulary for format arguments, and hard-coding the formatted result ("Resuming from step 0/10") as a literal breaks on every locale but one. The locale-independent pattern: the spec declares a pseudo-key that names the expectation — `@resume_info_step_0_of_10` — and the harness's closed map resolves it by formatting the app's own string table with the arguments the name spells out. The expectation then flows through exactly the string the user sees, and the closed-map contract (unknown names fail loudly) already covers it. `jui lint-strings --usage` also checks every `@key` a branchContracts section references for existence — the division of labor: validate checks only the reference's shape, because it does not know where the strings table lives; lint-strings does, so it resolves each reference against the table and against your harness's declarations. A pseudo-key is correct precisely because it is NOT in the table — what makes it legal is the harness declaration: `*_STRING_KEYS` maps count, and so does any key-shaped literal in a `*BranchHarness*` file (the Swift and Kotlin skeletons spell the closure as a closed switch rather than a map, and that counts the same). A `@key` found in neither place is reported missing — declared nowhere, in other words a typo:
one pseudo-key, three harness flavors (consumer-owned)
// spec — the expectation names a pseudo-key:
"then": { "data.statusMessage": "@resume_info_step_0_of_10" }
 
// web harness — closed map entry:
"resume_info_step_0_of_10": tpl("resume_info_step", { current: 0, total: 10 }),
 
// android harness — closed when-branch:
"resume_info_step_0_of_10" ->
context.getString(R.string.resume_info_step, 0, 10)
 
// ios harness — closed switch case:
case "resume_info_step_0_of_10":
return String(format: StringManager.resumeInfoStep, 0, 10)
8. What stops generationThe binding chain is the same on every platform: api.<op> resolves through the dataFlow method's endpoint declaration to a mock file matched on source.method + path, then to the named scenario — a reference that cannot be bound is a hard error, because a test that cannot bind its vocabulary must not silently weaken. The platform flags have their own requirements. All six messages below are real output, one seeded mistake each:
hard generation errors — one seeded mistake each
Error: branches[1].when.api.updateProfile: api operation 'updateProfile' has no `endpoint`
declaration in dataFlow.repositories/useCases — declare the method with its
endpoint (e.g. "endpoint": "POST /api/...")
Error: branches[1].when.api.updateProfile: no mock file found for PUT /api/items
(op 'updateProfile') under the mocks directory
Error: branches[1].when.api.updateProfile: scenario 'timeout' not found in
['failure', 'success'] (mock for PUT /api/items)
Error: condition 'formValid' has no witness_false — test generation needs a witness
to arrange the state
Error: --package is required for --platform android (Kotlin package of the generated
test sources)
Error: --module is required for --platform ios (the app module name for @testable import)
9. Platform-scoped branchesWhen implementations genuinely diverge — one platform surfaces an alert field of its own where the others share one — a branch can carry `platforms` (a non-empty subset of ios / android / web; anything else fails validate). Each generator skips out-of-scope branches with an explicit comment and excludes them from its declared count — never silently:
generator output — scoped branches are skipped loudly
// in ProfileScreenBranchesTest.swift (--platform ios):
// branch 3 is platform-scoped (['web', 'android']) — not generated for ios
 
// in profile_screen.branches.test.ts (web):
// branch 4 is platform-scoped (['ios']) — not generated for web
A screen can be left with nothing to generate on a platform: every branch it declares is scoped to another platform, or the platform is outside the screen's own `platforms`. The command prints `Skipped '<screen>': …` for it. The closing line counts what it generated and the skips apart — `0 screen(s) generated by jsonui-test …, 1 skipped (not for this platform).` — and naming such a screen exits 1, when generating and with `--check`, with `Error: 'profile_screen' was skipped on web — every branch it declares belongs to another platform — so nothing was generated. Pass --platform for a platform the screen targets.` A run over the whole project that skips screens still exits 0. The MCP tool `test_generate_branch_tests` follows the exit code, so it says success: false. Measured on a two-screen fixture with one screen's branches all scoped to iOS, run for web; the other kind of skip and the MCP tool are jsonui-cli's measurement.
10. Time-dependent state: a note, not a platform splitState that changes by itself after a delay — a banner that auto-dismisses after five seconds — can observe differently per platform even when the implementation is identical, because the test time models differ: the Android runtime drives a StandardTestDispatcher whose virtual clock advances inside settle(), so the dismissal has already fired; the iOS runtime drains the real-time main run loop in short slices, so it has not. That split is a property of the harnesses, not of the implementations — scoping such a branch with `platforms` would leak the test's time model into the spec. The same family includes state that is released only when an external SDK answers — billing, say — where settle() cannot know when that latency ends: the split is timing, not implementation, so it too belongs in a note. Declare the delayed outcome as a note with the reason, and keep the machine-checked branch to the immediately observable part. Auto-dismissing UI is common — check for this before puzzling over a one-platform red:
declare the delayed outcome as a note, with the reason
{ "note": "banner auto-dismisses after 5 s — time-model dependent: virtual time
(Android tests) has already fired the dismissal inside settle(), the
real-time run loop (iOS tests) has not. Harness property, not an
implementation difference — do not platforms-split this." }
11. Scope: claims that pin an unrelated axisThe three classes above are things the machine cannot judge. There is a fourth reason to keep something out of the contract, and it is different in kind: the claim is perfectly writable — but writing it pins an axis the contract has no business fixing. The canonical shape: a section's display variants (empty / populated / an upgrade prompt) depend on the user's plan tier. Declare all three and the contract silently fixes the tier axis too — the day a tier is added, branches go red for a reason that has nothing to do with the screen being broken. What belongs in the contract instead is the one fact that holds on every tier: the section is visible. Weakening the claim is not a compromise — one axis-independent fact outlives three axis-dependent variants.The test: does this claim survive a change on an axis it is not about? If not, weaken it to the part that does. And the inverse reading is the useful alarm — if you can imagine a branch going red for any reason other than "the implementation broke", the contract's scope is too wide.
12. Trust it: red-check, then regenerateA green suite proves the tests can pass; a red-check proves they can fail. After the first green run, break one implementation line and confirm that exactly one branch goes red — then restore it. Vary the depth of the mutation rather than hunting for the one perfect line: a mutation at the decode/mapping stage — where the response becomes your domain value — behaves like a real failure, because a real payload drop empties every reader downstream of it; a shallow mutation of one stored field can stay green when the method reads the response directly. Shoot coarse to fine, and treat a probe that stays green as information, not failure — it is telling you which surface the contract actually watches.The regeneration loop afterwards: edit the spec → `jsonui-doc validate spec` → generate again (the @generated pair is rewritten, the harness is kept) → run. The decision table and the tests stay two views of the same declaration.Before blaming the probe, check the arrange. A contract of the form "…is cleared / collapses / becomes empty" asserts a transition away from some state — and if `baseline` leaves that field at its default, and the default already equals the post-clear value, the assertion was vacuous from the moment it was written: nothing changes across the act, so removing the implementation changes nothing either. That failure is decided at authoring time, not at probe time, which is what makes it different from picking the wrong line to mutate. Whenever a branch asserts that something goes away, make the baseline put it there first — visible, selected, populated — and the same red-check that stayed green will turn red.Make landing the mutation a procedure, not a good intention — the same two lines of error handling often appear verbatim in several methods of one file, so a string-targeted edit lands in a neighbour and the contracted method stays intact. Two steps are enough: locate the function first and mutate relative to it ("the first match below `func confirmDelete()`"), never by string alone; and when the run comes back green, suspect a missed probe before you conclude the implementation is right — grep for the marker and check its line number before reading anything into the result. A green run only means something if the thing you meant to break is really broken.The mirror image is worth knowing because the symptom points the wrong way: a branch that goes red against an implementation you just verified by hand. A vacuous arrange stays green and looks like a bad probe; a harness that lies about the subject goes red and looks like a bug in the code — on web, the classic cause is a setState that invents ViewModel properties for data-only fields (see section 6). Both failures wait for the same trigger: they appear only once a baseline actually arranges the pre-state, which is to say they wait for exactly the contracts most worth writing. So when a red arrives, ask whether the test is reading the same field the implementation writes before you start editing the implementation.There is a third variant, and it is the quietest: the branch passes, but through a path you did not mean. A baseline has to agree with the data the scenario actually returns — above all the values the implementation matches on, ids, timestamps, versions. Put an id in the baseline that no record in the mock's list carries, and a branch meant to pin "the conflict is detected and the item is refetched" can instead exercise "the refetch found nothing": the assertion still holds, so the run is green, and what is pinned is not what you wrote it for. So the question a red-check answers is not only "can this fail?" but "did it travel the route I described?" — turning a branch red proves it can move; reading which assertion moved proves it moved along your path.A fourth way a green run lies: the expectation itself does not identify the branch. If the value you assert can arrive by more than one route — a `@key` whose text happens to read exactly like the message the server sends — then breaking the mapping changes nothing observable and the branch stays green. The fix is in the fixture, not the contract: give the mock wording that differs from the string table's, and the assertion can finally tell the two routes apart. The same reasoning explains another stubborn green: when the implementation guards the same outcome in more than one place, breaking one guard leaves the result intact, so a probe that lands correctly still produces no red. So when nothing turns red, work through two suspects in order: first, the probe missed — grep the marker's line number and confirm it landed where you meant; only then, something else already ensures this — look for a second guard covering the same outcome. Same symptom, different place to look. The opposite result has its own first suspect: when more goes red than the branch you broke, check that the working tree is in the state you think it is before concluding the branches are entangled. Restoring a mutation with a wholesale VCS checkout takes uncommitted work with it, and the next probe then runs against a tree missing changes you never meant to drop. Keep a copy of the file before mutating and restore from that, so undoing a probe touches exactly what the probe touched.One line holds the first three together: the baseline is an arrange, not decoration. It is not a restatement of the declaration — it is the operation that puts the subject into the state where the observation can happen at all. Read the three failures that way and they stop being separate problems: vacuous means no pre-state was built, a lying harness means it was built in the wrong place, and the wrong path means it was built with the wrong contents. When a new shape of arrange appears in a contract, suspect the harness before the implementation — a harness only has to handle the states someone has asked it for, so a new kind of arrange is exactly when its shortcuts surface. The fourth variant extends the same idea to the other end of the test: an arrange has to build the state that makes the observation possible, and an expectation has to be one only this branch can satisfy. Both halves have to distinguish — a green run is worth something only when nothing else could have produced it.
Keep going
Branch contractsThe declaration side: vocabulary, validate, and the rendered decision tables./guides/branch-contracts
Writing screen testsScreen and flow tests — the executable side of behavior documentation./guides/testing
Verifying implementation against docsThe wider check suite that keeps spec and implementation from drifting./guides/verifying-implementation-against-docs