Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

Testing the host widget

The runtime package owns the host’s lifecycle, navigation lock and trial-ready timer. Its test/app_widget_test.dart pumps the real ValenceApp; apps test their own handlers and generated wiring instead of copying these tests. This is the host-widget row of contracts §8.

From packages/valence in the Valence source repository:

Terminal window
flutter test test/app_widget_test.dart

The command is also included in flutter test. Run the full suite and dart analyze --fatal-infos . before handing off a runtime change.

The fixture verifies signed bundles, opens a temporary SQLite database and binds a loopback socket. test/webview_stub.dart replaces only the native WebView platform: it captures navigation callbacks, page loads, JavaScript channels and scripts. Unsupported operations throw. OTA/sync requests use an in-memory HTTP client; connectivity and external URL launches use platform-channel stubs. The fixture generates its signing key and restores platform handlers after each case.

These are the decisions the tests exercise:

  • Resume during held-open startup updates lifecycle state without running an update check, sync or resumed event. Completing startup starts its normal triggers (I-61).
  • Same-origin routes navigate. Reserved host documents and off-origin subframes are refused; external main-frame URLs pass through the native scheme allowlist.
  • Bridge dispatch receives the bound server’s nonce and its reply reaches the JavaScript channel. The back callback consumes WebView history before asking the OS to close the app. Strict decoders and invalid nonce rejection remain covered by their own lower-layer tests.
  • One-shot events flush once and buffer again on reload; lifecycle state is re-derived.
  • A ready trial commits. A foreground timeout counts one failure and reloads current without spending the next UI start’s retry. Time in the background counts nothing; late/current ready calls cannot commit a trial.
  • A timeout refuses the given-up page’s data.cache with E_DENIED until the document that swap asked for starts, and accepts it again after, with the trial’s overlays gone. A swap with nothing left to serve throws, loads no page and logs it, and neither that failure nor a self-navigation by the given-up page releases the refusal.
  • A launch destination waiting in a mailbox pre-empts the restored route: the host ends up at / with the saved draft intact, the mailbox unconsumed and the source named in the log, and a reload after that goes to / too. A start with no launch tap restores its route unchanged. The decision is driven through the host’s own prepareRestoration call rather than by restarting the widget tree — a restart in one process is not the launch under test, because ValenceApp.dispose closes the link mailbox that a real cold start refills before its first frame.
  • A dead WebView content process reloads the same bundle at the same route and spends no trial strike; one that keeps dying stops after three recoveries, releases the WebView and clears the trial marker on disk so the next launch spends none either. A resume that reclaims the same port reloads the page when none is loaded. Android’s half of this has no behaviour test — the process is killed with no Dart frame in between — only a tripwire that fails if the plugin ever exposes the callback.
  • Disposal cancels timers, connectivity and lifecycle triggers, closes the socket and keeps SQLite usable.

Cold startup behind the native update blocker still arms sync. Mount that case through tester.runAsync, as the shared mounting helper does, and drain real I/O after disposal before closing the test-owned database. A painted blocker alone does not mean the startup sync has finished; its diagnostic timer can still be active.

Production measures foreground time with a Dart Stopwatch, which Flutter’s fake clock cannot advance. Page-start callbacks run through tester.runAsync with short configured deadlines and real ticker waits. Disposal waits beyond the configured update interval. Do not replace those waits with pump(Duration(...)): the fake clock could let a broken cancellation pass. File/socket/SQLite work drains between frames with bounded polling. The fixture temporarily removes Flutter’s default HTTP stub so the resume liveness probe reaches the real socket, then restores it.

The stub does not render HTML, execute JavaScript or prove the native WebView’s isolation. Keep the Android offline and rollback checks as separate evidence. Android is tested; iOS remains experimental and untested. A passing widget suite does not change that status.

Last updated: