Testing OTA and sync locally
The releasing guide uploads to a real CDN, and the beta page asks you to start every release at a small rollout. Both assume you already trust the update path. This page is how you earn that trust first, with nothing leaving your machine.
You want to be able to force each of these before you ship anything to a user: a bundle becomes pending, a trial commits, a trial fails twice and the phone goes back to the last good bundle, and a roll-forward recovers. All of it runs against two static-ish servers on 127.0.0.1.
Pick the ports first
Section titled “Pick the ports first”ota.base and sync.base go into the bundle’s identity, not just your dev setup:
codegencompiles both intoconfig.g.dart, so they end up in the binary;valence bundleputs thesync.baseorigin into the signed manifest’s CSPconnect-src.
So changing a port later means codegen, a host rebuild and a rebuild of every bundle you have already signed. Check the ports are free, pick ones you will not fight another process for, and write them down. Before you start a server, check nothing else is already listening on its port (netstat -ano | findstr :8121 on Windows, lsof -i :8121 elsewhere): a leftover server from an earlier run answers instead, and hides a mismatch between what you configured and what you think you are serving.
{ "ota": { "base": "http://127.0.0.1:8121" }, "sync": { "base": "http://127.0.0.1:8122" }}Use 127.0.0.1, not localhost and not your LAN address. The reason is the next section.
Android: use adb reverse
Section titled “Android: use adb reverse”Keep the host’s Android platform setup
restricted to 127.0.0.1. That XML policy is not a guarantee for native Dart
HTTP: a release-device check successfully sent a synthetic bearer token to an
explicitly allowlisted http://10.0.2.2 origin despite the restriction. Use
loopback forwarding for local OTA, sync and native RPC tests, and HTTPS for
remote services. Do not rely on an opaque cleartext failure to protect a token.
The debug-only development proxy is separate from
these signed-bundle tests.
Map the ports onto the device’s own loopback instead:
adb reverse tcp:8121 tcp:8121 # OTA hostadb reverse tcp:8122 tcp:8122 # sync APINow the device genuinely talks to 127.0.0.1, the network security config is satisfied unchanged, and the signed CSP matches. Re-run the commands after every adb reconnect, because reverse forwards do not survive one.
The forwards ride the adb connection, not the phone’s network, so airplane mode alone is not an offline test: the device still reaches both servers over USB or wireless debugging. Run adb reverse --remove-all first, then go offline.
iOS simulator
Section titled “iOS simulator”The simulator shares the host’s network stack, so http://127.0.0.1:<port> reaches your machine with no forwarding. A real device needs a tunnel that terminates on the device’s own loopback; the same 127.0.0.1-only rule applies, and the App Transport Security loopback exception is what allows it.
The OTA host
Section titled “The OTA host”Any static file server over .valence/dist-ota will do, as long as it serves the bundle layout under /<appId>/. The only behaviour that matters is that the pointer is re-read (short or no caching) and the manifests and files are returned as they are.
npx --yes http-server .valence/dist-ota -p 8121 -c-1Then the normal release commands, with the channel pointed at your build:
node valence/valence.mjs bundlenode valence/valence.mjs pointer --rollout 100Use --rollout 100 while testing so the cohort gate never decides for you.
A minimal sync API
Section titled “A minimal sync API”Two endpoints, both described in full in the data and sync guide. The smallest thing that satisfies the host:
GET /{bucket}?since={usn}&schema={n}&limit=500 -> {"bucket":"schedule","schema":2,"rows":[{"k":"day-1","v":{},"u":1241,"d":0}],"max":1241,"more":false}
POST /{bucket}/push {"ops":[{"id":"<uuid>","k":"n1","v":{},"d":0}]} -> {"acked":["<uuid>"],"rows":[{"k":"n1","v":{},"u":1301,"d":0}]}Rows must come back in ascending usn order, max must be the last row’s u, and push must be idempotent by op id — replay the same id and acknowledge it again without assigning a second usn. Those three are what the host’s retry and outbox logic relies on; everything else is yours.
For read-only buckets you can skip the server entirely and publish static chunks next to the bundles on the same static host.
Watching and resetting the update state
Section titled “Watching and resetting the update state”Everything that decides what a launch does lives in state.json inside the app’s private directory. On a debug build of Android:
adb shell run-as com.example.app cat files/valence/state.jsonadb shell run-as com.example.app rm files/valence/state.json # forget updates, keep the user's dataDeleting just that file sends the next launch back to the built-in bundle with a fresh install id, while leaving the SQLite database alone. That matters, because the most important rollback property to test is “a bad bundle reverts and the user’s own writes are still there”, and adb shell pm clear is too blunt to test it: it wipes the database too.
On a release build the directory is unreachable, which is the point. Test the state machine on a debug build.
flutter test integration_test/... writes its own test APK to build/app/outputs/flutter-apk/app-debug.apk and uninstalls the app at teardown, which wipes its database. Run flutter build apk --debug again before you reinstall from that path, and do not run integration tests in the middle of a rollback test.
A rollback drill worth running once
Section titled “A rollback drill worth running once”- Release a good bundle and let it commit. Note
current. - Release a bundle whose entry page never calls
ready()— commenting out the call is enough. Point the channel at it. - Launch: the check makes it
pending. Launch again: it runs as a trial and times out after 15 seconds of foreground time, which is one failure. Launch again: the second failure marks itbad. - Launch again. You should be back on the bundle from step 1, with your data intact, and the bad
seqmust not come back on any later launch.
Step 4 is the one to watch. If the bad bundle returns, the host is missing one of the guards in the update protocol: the update check has to stop on trial as well as on current, pending and bad, and a pending holding a bad seq must be dropped rather than promoted.
Publish your own fixture before a picker test
Section titled “Publish your own fixture before a picker test”A gallery or document picker hands your plugin a content:// URI chosen from whatever
the device happens to hold, and the device is free to stop being able to read it: a
media row can be removed, rewritten or scoped away between the pick and the read, and
the provider then answers FileNotFoundException for a URI the picker had just
offered. Through the bridge that surfaces as E_INTERNAL with the provider’s message,
which is the honest answer — the host did not fail, the item is gone.
So an automated device run must publish its own image and select that, rather than pick whatever is first in the gallery. A fixture your test wrote is the only one whose lifetime your test controls; it is also the only way a failure tells you about your code instead of about the emulator’s media catalog. Delete it in the same run, the way you would revoke a host file.
Keep the error boundary rather than retrying around it: a picked URI that cannot be read is a real outcome your app has to show a user, and a test that silently re-picks is a test that cannot see it.
- Releasing for the real thing
- Troubleshooting when a phone does not take an update