amethyst/tools/tor-network-tests/README.md

Tor networking scenario suite

A repeatable, device-driven test harness for Amethyst's embedded Tor (Arti) across the network transitions that have historically broken it. These checks live outside the JVM/instrumented test tree on purpose: they manipulate the device's network (airplane mode, WiFi/cellular, app lifecycle) and assert on the real ArtiNative bootstrap — things a unit test can't reach.

When to run this

Run the suite whenever you touch anything in the Tor management path, and treat a green run as a release gate for those changes:

• Bumping Arti (tools/arti-build, the rebuilt libarti_android.so) — a new Arti version can change bootstrap timing, the SOCKS error mapping, or guard handling. This is the most important trigger.
• TorService.kt — lifecycle (start/stop/reset/resetWithCleanState), the bootstrap-timeout handling (ARTI_ERROR_BOOTSTRAP_TIMEOUT), or cache/state wiping.
• TorManager.kt — the self-heal watchdog, onNetworkChange, cooldowns, or status routing.
• The dial gate — WebsocketBuilder.canConnect / the canDial wiring in AppModules.kt that holds Tor-routed relays until the SOCKS port is ready.
• The connectivity layer — ConnectivityManager / RelayProxyClientConnector (pause/resume, reconnect-on-change).

How it relates to the other tests

Layer	Where	Covers
Pure logic (fast, deterministic)	amethyst/src/test/.../tor/TorManagerTest.kt	watchdog, cooldown, onNetworkChange, status routing — virtual time, in-memory fakes, no Arti
Pure logic (fast)	amethyst/src/test/.../service/relayClient/TorCircuitHealthTrackerTest.kt	the Active-but-failing discriminator (companion circuit-health PR)
Real Arti, single process	amethyst/src/androidTest/.../tor/TorBootstrapInstrumentedTest.kt (@Ignore'd)	real initialize → create_bootstrapped → SOCKS round-trip + destroy
Real Arti + real network transitions	this suite	bootstrap bounding, network change, airplane, pause/resume — end to end

The unit tests are the first line of defense (run in CI). This suite is the end-to-end backstop you run by hand (or in a device lab) before shipping a Tor change, because the failures it catches only appear with a real radio.

Device setup (once)

1. Connect one device or emulator with internet egress to the Tor network. An emulator that exposes both WiFi and Cellular (e.g. a stock Pixel AVD) is ideal — the wifi_cellular scenario needs a second transport to fail over to.
2. Install the debug build: ./gradlew :amethyst:installPlayDebug.
3. In the app, set Tor = INTERNAL and enable routing relays over Tor (Settings → Network/Tor). The suite does not change Tor settings; it only manipulates the network and the app lifecycle, so it tests the config the user actually runs.

Running

# full suite
tools/tor-network-tests/run.sh

# a single scenario
tools/tor-network-tests/run.sh offline_bootstrap

# override the package (e.g. a different flavor)
AMETHYST_PKG=com.vitorpamplona.amethyst.debug tools/tor-network-tests/run.sh

Exit code is 0 only if every selected scenario passes. The suite restores a clean network state (airplane off, WiFi+data on) when it finishes.

Scenarios

Each scenario clears logcat, drives a transition, then asserts on Tor's lifecycle log markers (SOCKS proxy active, bootstrap timed out, onNetworkChange, Pausing/Resuming Relay Services, OnOpen).

cold_start

Force-restart on a healthy network. Asserts: Tor reaches Active, and the number of Tor-routed dials issued before the SOCKS port was ready stays ~0 (the #3223 gate). A spike here means the gate regressed and the pool is hammering a dead proxy during bootstrap.

offline_bootstrap — the headline regression test for this PR

Wipe Arti state (empty cache), enable airplane mode, then cold-start so create_bootstrapped runs with no network and nothing cached. Asserts: the native bootstrap is bounded — a bootstrap timed out line appears (the 60s tokio::time::timeout releasing lifecycleMutex so the self-heal watchdog can run), instead of blocking for many minutes. Then restore the network and assert recovery to Active.

Without the timeout (fix: bound Arti bootstrap with a 60s timeout, this PR), create_bootstrapped blocks indefinitely holding the lifecycle lock — observed wedging at 95s+ on an emulator — and this scenario fails with "no 'bootstrap timed out'". That regression is invisible to every JVM test, which is why this suite exists.

wifi_cellular

With Tor Active, disable WiFi (the default route fails over to cellular), wait, re-enable. Asserts: the transport change drives onNetworkChange and Tor returns to Active. Catches the "stale guards/circuits from the old network" class of wedge.

airplane

Toggle airplane mode on (full offline) then off. Asserts: relays pause cleanly on connectivity loss (no Tor thrash while offline) and Tor + relays recover on restore.

pause_resume

Background the app (HOME), wait for the WhileSubscribed(30s) wind-down, then foreground it. Asserts: relays pause (Pausing Relay Services) while backgrounded and reconnect (OnOpen increases) on resume. The reconnection burst on resume is the same shape as the post-Active warmup burst, so this also guards against the circuit-health self-heal firing a false positive on resume.

Interpreting failures

The summary prints PASS/FAIL per check with a one-line reason. Common ones:

• offline_bootstrap FAIL "no 'bootstrap timed out'" → the native timeout isn't in the installed .so (rebuild libarti_android.so from tools/arti-build, or you're on a branch without the fix).
• cold_start FAIL "pre-ready doomed dials >5" → the canDial/canConnect gate regressed.
• wifi_cellular / airplane FAIL "did not reach Active" → bootstrap is slow or wedged on the new network; pull the full log and look for repeated ExitTimeout / AllGuardsDown.

For a deeper look at any run, dump the lifecycle directly:

adb logcat -d | grep -E "TorService|TorManager|ManageRelayServices" \
  | grep -iE "Initializing|bootstrap|proxy active|timed out|self-heal|reset|onNetworkChange|Pausing|Resuming"