# makepad_test on Android

How `makepad_test` runs Makepad UI tests on real Android devices, and the
steps that were taken to get it working end-to-end. This is the Android
companion to [GUIDE.md](./GUIDE.md), which covers the desktop headless and
visible-Studio modes.

## What "Android mode" does

When `MAKEPAD_TEST_ANDROID=1` is set, the test runtime:

1. starts an in-process `StudioHub` that listens on `127.0.0.1:<port>` on the host
2. forwards that port to the device with `adb reverse tcp:<port> tcp:<port>`
3. builds the APK through `cargo-makepad` (`android build -p <package>`)
4. installs the APK with `adb install -r`
5. force-stops any previous instance of the app
6. launches the app with `am start`, passing the hub address, build id, and crate name as intent extras
7. waits for the app to connect to the hub (`AppStarted`)
8. settles until the app actually answers a request (see "Startup race fix")
9. drives the test through the normal `TestApp` / `Locator` / `Selector` APIs

The app dials `127.0.0.1:<port>` on the device; `adb reverse` maps that back
to the host listener, so no separate device-side network setup is needed.

## Two runtime modes

| Mode | Activity launched | Platform build | When |
|------|------------------|----------------|------|
| Legacy Java | `dev.makepad.<pkg>/.MakepadApp` | no `--cfg native_activity` | default |
| NativeActivity | `<pkg>/android.app.NativeActivity` | `--cfg native_activity` + `--native-activity` build flag | `MAKEPAD_TEST_NATIVE_ACTIVITY=1` |

- **Legacy Java** is the default. `cargo-makepad` generates a `MakepadApp`
  Java `Activity` that bridges into `MakepadNative.activityOnCreate`.
- **NativeActivity** requires the flag on both sides: the platform crate must
  be compiled with `--cfg native_activity` (so the `native_activity.rs`
  module and the `ANativeActivity_onCreate` entry point are used instead of
  the Java activity), and the APK must be built with
  `cargo makepad android --native-activity build -p <pkg>`.
  `build_android_apk` in `runtime.rs` adds the flag automatically when
  `config.android_native_activity` is set.

The launch is wired up in `adb_launch` in `libs/makepad_test/src/runtime.rs`:

```text
am start -n <activity>
  -e makepad.STUDIO_HOST 127.0.0.1:<port>
  -e makepad.STUDIO_BUILD <build_id>
  -e makepad.STUDIO_CRATE <package>
```

## Environment variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `MAKEPAD_TEST_ANDROID` | enable Android mode (any truthy value) | unset (off) |
| `MAKEPAD_TEST_DEVICE` | adb device serial (`-s <serial>`) | unset (default adb device) |
| `MAKEPAD_TEST_ADB` | path to the adb binary | `adb` on `PATH` |
| `MAKEPAD_TEST_ANDROID_PORT` | host hub port / adb reverse port | `8001` |
| `MAKEPAD_TEST_NATIVE_ACTIVITY` | use NativeActivity instead of legacy Java | unset (legacy) |
| `MAKEPAD_WORKSPACE_ROOT` | workspace root holding `tools/cargo_makepad` | auto-detected by walking up from the manifest dir |
| `MAKEPAD_STUDIO_HUB_DEBUG` | print every hub child line (build + app output) | unset |

The hub binds `127.0.0.1:<port>` and may fall back to a different port if
`8001` is already taken (for example by a real Studio). `start_android_app`
reads the port the hub actually bound (`connection.studio_addr()`) and routes
`adb reverse` and the intent extras at that port, never a hardcoded one.

## Build system requirements

- Android builds use the **nightly** toolchain: the platform crate needs
  `cargo +nightly` and the NDK target installed for `aarch64-linux-android`.
- The `cargo-makepad` binary must exist at `<workspace>/target/release/cargo-makepad`:
  `cargo build --release -p cargo-makepad`.
- The APK lands at
  `target/android/makepad-android-apk/<pkg_underscored>/apk/<pkg_underscored>.apk`.
- `tools/cargo_makepad/src/android/compile.rs` gained a `native_activity`
  argument that flows into `rust_build` (alongside the profile-based
  `prefer_dynamic` choice) and is plumbed through both APK build call sites.

Sanity-compile checks that must stay green:

```bash
# legacy Java cfg
cargo +nightly check -p makepad-platform --target aarch64-linux-android

# native-activity cfg
RUSTFLAGS="--cfg native_activity" cargo +nightly check -p makepad-platform --target aarch64-linux-android
```

## Device setup

```bash
export MAKEPAD_TEST_ADB="<repo>/tools/cargo_makepad/android_33_macos_x64/platform-tools/adb"
export MAKEPAD_TEST_DEVICE="RF8Y103NERA"          # your device serial
$MAKEPAD_TEST_ADB devices                          # must list the device
$MAKEPAD_TEST_ADB -s "$MAKEPAD_TEST_DEVICE" wait-for-device
```

- The device must be **authorized** (accept the USB debugging prompt).
- Keep the screen on during the run:
  `adb -s <serial> shell svc power stayon true`.
- On some devices a screen-off can still slow or starve the app; test with the
  screen awake.

## Running the tests

Legacy Java mode (default):

```bash
MAKEPAD_TEST_ANDROID=1 \
MAKEPAD_TEST_DEVICE="RF8Y103NERA" \
MAKEPAD_TEST_ADB="<repo>/tools/cargo_makepad/android_33_macos_x64/platform-tools/adb" \
cargo test --release -p makepad-example-counter --test ui -- --test-threads=1
```

NativeActivity mode:

```bash
MAKEPAD_TEST_ANDROID=1 \
MAKEPAD_TEST_NATIVE_ACTIVITY=1 \
MAKEPAD_TEST_DEVICE="RF8Y103NERA" \
MAKEPAD_TEST_ADB="<repo>/tools/cargo_makepad/android_33_macos_x64/platform-tools/adb" \
cargo test --release -p makepad-example-counter --test ui -- --test-threads=1
```

`--test-threads=1` is required: each test owns the shared hub port and the
serialized app session.

Progress is printed to stderr with `[makepad-test] Android: ...` lines as each
phase completes (forward, build, install, force-stop, launch, connect,
responsive).

## Expected results

Recorded runs on the reconciled tree:

| Mode | Device | Result | Time |
|------|--------|--------|------|
| Native | RF8Y103NERA (SM-A165F) | 2 passed | 515.71s |
| Native | R28M52LJP2Y (SM-A6060), screen off | 2 passed | 179.65s |
| Legacy | R28M52LJP2Y (SM-A6060) | 2 passed | 361.76s |
| Legacy | RF8Y103NERA (SM-A165F) | 2 passed | 957.16s |
| Native | RF8Y103NERA (SM-A165F) | 2 passed | 520.70s |

The APK build dominates the wall time; app install and test execution are the
small remainder.

## The startup race fix (settle step)

**Symptom:** the app connected (`AppStarted`) but the first widget query or
click was lost, failing the test with a timeout on the first interaction.

**Root cause:** the websocket connects on a background thread before the app's
event loop is up. A cold start can answer the handshake well before it can
service hub requests. Legacy Java starts are the slowest: the first frame (and
with it the main loop that drains requests) only comes after the
`SurfaceView` surface materializes, which on a first launch after install can
exceed the per-request `ACTION_TIMEOUT` (10s).

**Fix:** after `wait_for_android_app_started`, call
`wait_for_android_app_responsive` (`runtime.rs:1754`). It repeatedly sends
`ClientToHub::WidgetTreeDump` and waits for a matching `WidgetTreeDump`
reply, with a per-attempt `ACTION_TIMEOUT` and an overall
`ANDROID_STARTUP_TIMEOUT` (120s) deadline. The test body's first query only
starts once the app has actually answered a request, closing the boot race.

## Debugging

Enable hub transport diagnostics, which echo every child stdout/stderr line
(APK build output, app logs, protocol messages):

```bash
MAKEPAD_STUDIO_HUB_DEBUG=1 ... cargo test --release -p makepad-example-counter --test ui -- --test-threads=1 --nocapture
```

Failure artifacts are written to `target/makepad_test/<package>/<test>/`
(`failure.txt`, `failure-screenshot.png`, logs), exactly like desktop mode.

## Troubleshooting

| Symptom | Likely cause / fix |
|---------|--------------------|
| `adb: error: device '<serial>' not found` | device disconnected; reconnect USB and `adb devices` |
| `device unauthorized` | accept the USB debugging prompt on the device |
| `timed out waiting for Android app to connect to hub` | wrong port / stale `adb reverse`; the hub binds a fallback port, so make sure adb and the app use the actually-bound port (already handled in code) |
| `timed out waiting for Android app to become responsive` | very slow cold start; raise `ANDROID_STARTUP_TIMEOUT`, keep the screen on, or rerun once warm |
| `cargo-makepad not found at ...` | `cargo build --release -p cargo-makepad` first |
| test fails only on the very first launch after install | known cold-start surface race; rerun warm, or run the legacy case twice |

## Current limitations

- one device at a time (`-s <serial>` targets a single device)
- one app session per test (serial suite with `--test-threads=1`)
- the APK build happens inside the test process, so the first test of a suite
  is the slow one; subsequent tests reuse the built APK