env-android

name	env-android
description	Recipe for filling state/reference/ENV.md when the project is an Android app. Use when the project has a build.gradle / settings.gradle and targets Android. Covers emulator boot, gradle test/connectedAndroidTest, adb logcat capture.
tools	["Read","Write","Bash"]

env-android — recipe for state/reference/ENV.md

Android needs more setup than web because tests differ (unit vs instrumentation) and logs come from adb logcat. Fill these in.

Profile

Profile: android

Bring up

• Ensure SDK + emulator on PATH (the init.ps1 script should sanity-check adb, emulator, gradle)
• adb start-server
• Boot emulator (background, no UI for CI-friendliness):

  emulator -avd Pixel_API_34 -no-snapshot-load -no-window -no-audio -no-boot-anim &
  

• Wait for boot:

  adb wait-for-device
  adb shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 1; done'
  

• Install app: ./gradlew installDebug

Smoke (< 30s)

• adb devices (must list one online)
• ./gradlew :app:assembleDebug --offline

Verify (canonical green-light)

• ./gradlew test # JVM unit tests; fast; no emulator needed
• For richer green-light: ./gradlew test lint

E2E / instrumentation

• ./gradlew connectedAndroidTest # requires running emulator/device
• For a single test class: ./gradlew connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.example.FooTest

Capture logs

• App logs (logcat):

  adb logcat -c                                        # clear before run
  adb logcat -d -v threadtime > logs/logcat-<ts>.txt   # dump after
  # filter to your package:
  adb logcat -d --pid=$(adb shell pidof com.example.app) > logs/app-<ts>.txt
  

• Test reports: app/build/reports/tests/, app/build/reports/androidTests/connected/
• Crash dumps: adb shell bugreportz → pull the zip, or adb pull /data/anr/
• Where logs land: logs/, app/build/reports/

Tear down

• adb -s emulator-5554 emu kill # or whatever serial adb devices shows
• ./gradlew clean if disk pressure

Devices / emulators

• Required: AVD Pixel_API_34 (x86_64, system image with Google APIs)
• How to create: avdmanager create avd -n Pixel_API_34 -k "system-images;android-34;google_apis;x86_64"
• How to check alive: adb shell getprop sys.boot_completed returns 1

Known fragility

• Emulator boot sometimes hangs on first run after host reboot — give it 60s before failing
• adb logcat buffer wraps; always -c before the run you care about
• Instrumentation tests timeout default is short — bump in build.gradle testOptions { unitTests.all { timeout = ... } }
• KVM/HAXM acceleration must be enabled or emulator runs at glacial speed