GuidesInitial state and the state bridgeA test can start a screen with the data it needs. The values in `initialState` go into the screen's Data when the app launches. The app reports which ones it accepted, and the driver fails the test if it did not. The `state` assertion reads the same channel back, so a harness no longer needs a state provider.11 min read
What it doesA screen test writes `initialState.viewModel`. A flow writes `initialState.viewModels`, keyed by screen id. At launch the driver hands the values to the app. The generated code checks each one against the Data the layout declares and applies the ones that fit. The screen then publishes what it applied and what it rejected, and the driver waits for that receipt before the first case runs. A value the app rejects fails the test at setup; it is not dropped without a word.It needs the drivers, SwiftJsonUI, KotlinJsonUI and screens generated with jsonui-cli. There is no transition period. A driver fails a file whose initialState the app did not confirm, so the case fails instead of running on the defaults.
Writing itPut the values at the top of the file. They are delivered once, before the first case, and every case starts from them.A case may carry its own `initialState`, but only in a file that declares `caseIsolation: "reopen"`. The screen is then opened again before each case, and the case's values are merged into the file's, key by key. The merge is shallow: a case's value replaces the file's value for that key whole, objects included, and a case's `null` is a value that replaces it too. In a shared file (the default) the screen opens only once, so a case-level initialState cannot be delivered. Validate reports an error, and the driver fails that case at setup.
order_status.test.json
{ "type": "screen", "source": { "layout": "layouts/order_status.json" }, "caseIsolation": "reopen", "initialState": { "viewModel": { "orderNumber": "A-1001", "status": "processing", "trackingNumber": null } }, "cases": [ { "name": "processing", "steps": [ { "assert": "text", "id": "order_number_label", "equals": "A-1001" }, { "assert": "hidden", "id": "tracking_link" }, { "assert": "state", "path": "trackingNumber", "equals": null } ] }, { "name": "shipped", "initialState": { "viewModel": { "status": "shipped", "trackingNumber": "1Z999" } }, "steps": [ { "assert": "visible", "id": "tracking_link" } ] } ]}Keys and typesKeys are the Data names in the layout's `data` section, top level only and case-sensitive. There is no dot notation: `user.name` is one key, and it is not a Data name. A ViewModel property that the layout does not declare cannot be set. Each key is judged on its own, in this order: not a data field, unsupported type, null, type. The keys that pass are applied even when others are rejected.The class is read as the layout writes it, with the generators' vocabulary: `Integer` is `Int`, `Number` is `Double`, `Boolean` is `Bool`. A trailing `?` makes it optional, and only then is `null` accepted. `Int` is 32-bit, and `2.0` is accepted, because JavaScript cannot tell it from `2`. A `Visibility` takes the three words the `visibility` attribute reads, `visible`, `invisible` and `gone`, lowercase; any other value, `Gone` or `false` included, is a type mismatch, and `null` is accepted only for `Visibility?`. An array of Visibility is an unsupported type. Web accepts it through the generated screens, iOS through SwiftJsonUI and Android through KotlinJsonUI (the library half is jsonui-cli's word; the validate half was measured).
Data classes initialState accepts (jsonui-test-runner spec §10.3)
data class acceptsString a stringInt a number with no fraction, -2147483648 to 2147483647 (2.0 accepted; 1.5, true, "1" and 2147483648 rejected)Double / Float / any numberCGFloat / NumberBool true or false (0, 1 and "true" rejected)Color a colour token or hex stringArray(X) / [X] / an array whose every element is X (no null elements)List<X>Array an array of strings, numbers or booleansObject / Hash an object whose values are strings, numbers or booleansX? the same as X, plus nullanything else nothing: closures, CollectionDataSource, Visibility, Image, EdgeInsets, an array of a custom type, ... rejection reasons not a data field type mismatch: expected <class> null for non-optional <class> unsupported type <class> viewModel has no updateData (Android only)When the values arriveThe app applies them the first time the screen appears after the launch, once per launch and screen. Navigating away and back in the same launch does not apply them again. By then the ViewModel's init or onAppear may already have run with the default values, so a value that onAppear overwrites will not stay. Values that come from an API are made with `mocks`, not with initialState.The app receives values only while the same gate as the screen marker is open: DEBUG or the Info.plist key `com.swiftjsonui.SCREEN_MARKER` on iOS, a debuggable build or the meta-data `com.kotlinjsonui.SCREEN_MARKER` on Android, and a non-production build on web. A release build neither receives values nor publishes state. On web the code is not in the production bundle at all: this site's own production export contains none of it.
The receiptAfter a launch that carried values, the driver waits up to `screenReadyTimeout` (15000 ms by default) for the screen to report a receipt with the same launch id. If none arrives, or any key was rejected, the cases fail with `failureReason: "setup"`: every case of a shared file, or only that case on a reopen. The message lists each rejected key with its reason. When nothing arrived, it lists the likely causes: a library older than this release, a build with the gate closed, a web page that does not go through the generated hook, or a screen id that does not match.Where the bridge lives: on iOS, the accessibility value of a transparent leaf with the identifier `__state_<screenId>` (over 32 KB it holds only `{"truncated": <bytes>}`); on Android, the semantics key `JsonUIState` on the screen marker node; on web, `window.__JSONUI_STATE__[screenId]`. It is published again every time the Data changes.
What a screen publishes (the state bridge)
{ "launchId": "6F1C2A9E-3B7D-4C1E-9A55-0D2F8E7B4C11", "initialState": { "applied": ["email"], "rejected": [{ "key": "nickname", "reason": "not a data field" }] }, "data": { "email": "test@example.com", "password": "" }}Reading state backThe `state` assertion and `when: { state }` resolve their `path` in the same bridge's `data`, so with libraries of this release the harness passes no state provider. `equals: null` asserts a null value. In a screen test the screen is the screen under test. In a flow it is the step's `screen`, or else the last screen an earlier step named. A provider the harness still passes wins. While the bridge is absent or the path does not resolve, the assertion keeps waiting; a truncated iOS bridge fails at once.
FlowsA flow writes `initialState.viewModels`, keyed by screen id, the same values its steps write in `screen`. Each screen is checked the first time the flow reaches it. A screen in `viewModels` that the flow never reaches is a warning. `initialState.screen` is no longer part of the flow schema, and validate rejects it: the flow starts on whatever screen the app opens. A file or case the flow references runs without its own initialState, because the flow's launch has already happened; validate and the driver both warn about it.
login_to_profile.test.json — initialState
{ "type": "flow", "initialState": { "viewModels": { "login": { "email": "test@example.com" }, "profile": { "nickname": "Ann" } } }}The launch sequenceWhen a file has `launch`, `mocks` or a non-empty initialState, every driver launches the app in the same order. An empty initialState is the same as none and is not a reason to launch. With `caseIsolation: "reopen"`, the whole sequence runs again before each case.On web the runner applies `launch` itself. `clearState` clears cookies and the origin's local and session storage (not IndexedDB), permissions are cleared and granted again, and `arguments` go to sessionStorage. To put back something `clearState` removed, such as an auth cookie, give the runner an `afterLaunch(page)` hook. It runs after the arguments and before the initialState is written, on every launch, so per case on a reopen.
The same order on iOS, Android and web (spec §10.2)
1. clearState2. permissions3. arguments web: then the harness's afterLaunch(page)4. initialState5. mocks6. launch iOS app.launch(), Android relaunch, web reload (goto on a reopen)7. receipt8. setupweb harness — seeding a cookie that clearState removed
const runner = new JsonUITestRunner(page, { afterLaunch: async (page) => { await page.context().addCookies([ { name: 'session', value: process.env.TEST_SESSION ?? '', url: 'http://localhost:3000' }, ]); },});What validate checks`jsonui-test validate` applies the same rules before the run. It reads the Data each layout declares and reports every value the app would reject, a case-level initialState in a shared file, a `viewModels` key that is not a screen id, `initialState.screen` in a flow, and an initialState that a flow reference would ignore. It also warns when the installed driver is older than the one that reads the key, or when it cannot read the driver's version. Measured with a layout declaring `orderNumber: String`, `status: String`, `trackingNumber: String?` and `itemCount: Int`:The same file with `caseIsolation: "reopen"` and values that fit passes with no errors, including `trackingNumber: null`, because that class ends in `?`.
jsonui-test validate (the repeated hint abridged)
tests/screens/order_status.test.json [ERROR] ...cases[0].initialState: case 'shipped' has its own initialState, but the file's caseIsolation is shared (the default) — the screen opens once, before the first case, so it cannot be delivered and the driver fails this case (setup). Set "caseIsolation": "reopen", or move the values to the file's initialState (case-initial-state-needs-reopen) [ERROR] ...initialState.viewModel.itemCount: initialState 'itemCount' for screen 'order_status': type mismatch: expected Int. The app rejects it and the driver fails the file's cases (setup). ... [ERROR] ...initialState.viewModel.status: initialState 'status' for screen 'order_status': null for non-optional String. ... [ERROR] ...initialState.viewModel.customer: initialState 'customer' for screen 'order_status': not a data field. ... Result: FAILEDFiles: 1, Errors: 4, Warnings: 0What it does not coverinitialState sets the screen's Data at launch and nothing else. It does not set state in the middle of a run, state outside the ViewModel's `data`, or a flow's starting screen. Closures, collections and custom types cannot be set. The drivers deliver `launch.arguments` and `clearState` to the app, but reading them is the app's job; the libraries read only initialState.
Keep going
Writing screen testsThe test file, the step DSL, caseIsolation and the assertions./guides/testing
Screen identityScreen ids, the screen marker and the gate this bridge shares with it./concepts/screen-identity
Test tooling referenceWhere the three drivers differ, row by row./reference/test-tooling