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 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.

ota.base and sync.base go into the bundle’s identity, not just your dev setup:

  • codegen compiles both into config.g.dart, so they end up in the binary;
  • valence bundle puts the sync.base origin into the signed manifest’s CSP connect-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.

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:

Terminal window
adb reverse tcp:8121 tcp:8121 # OTA host
adb reverse tcp:8122 tcp:8122 # sync API

Now 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.

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.

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.

Terminal window
npx --yes http-server .valence/dist-ota -p 8121 -c-1

Then the normal release commands, with the channel pointed at your build:

Terminal window
node valence/valence.mjs bundle
node valence/valence.mjs pointer --rollout 100

Use --rollout 100 while testing so the cohort gate never decides for you.

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.

Everything that decides what a launch does lives in state.json inside the app’s private directory. On a debug build of Android:

Terminal window
adb shell run-as com.example.app cat files/valence/state.json
adb shell run-as com.example.app rm files/valence/state.json # forget updates, keep the user's data

Deleting 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.

  1. Release a good bundle and let it commit. Note current.
  2. Release a bundle whose entry page never calls ready() — commenting out the call is enough. Point the channel at it.
  3. 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 it bad.
  4. Launch again. You should be back on the bundle from step 1, with your data intact, and the bad seq must 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.