android-instrumented-tests

name

android-instrumented-tests

description

Run this repo's Android test layers and capture device logs. Covers the `scripts/run-instrumented-tests.sh` runner (single-class filter, --skip-build, --unit-only), the underlying `:comapeo-core-react-native:connectedDebugAndroidTest` Gradle task on the integration app, where the JVM/instrumented/service-lifecycle tests live, the report paths, and how to read logcat for the Kotlin (`ComapeoCore`) and embedded-Node (`Comapeo:NodeJS`) tags including the `:ComapeoCore` foreground-service process. Use when running, filtering, or debugging Android unit/instrumented/androidTest runs, a single Android test class, `connectedDebugAndroidTest`, or `adb logcat` for this project.

Android instrumented tests + log capture

Test layers (see docs/TESTING.md for the full picture)

Layer	Where	Needs a device?
JVM unit (JUnit4)	android/src/test/java/com/comapeo/core/	no
Instrumented IPC/file-watch (AndroidJUnit4)	android/src/androidTest/java/com/comapeo/core/	yes
Service-lifecycle integration (AndroidJUnit4 on the integration app)	apps/integration/tests/android/ (e.g. ServiceLifecycleTest.kt, ShutdownPathTest.kt) — injected into the prebuilt apps/integration/android/ by the with-android-tests config plugin	yes

Instrumented/service tests run against the integration app (com.comapeo.core.integration); the backend runs in its com.comapeo.core.integration:ComapeoCore foreground-service process.

Running

Use Node 24 (pinned in .nvmrc) — select it with whatever version manager you use (nvm use, fnm use, asdf, …) or have it on PATH.

npm run test:android:unit          # JVM unit only, no device
npm run test:android               # full instrumented run (boots an AVD if none attached)

# direct, for the useful flags the npm scripts don't expose:
./scripts/run-instrumented-tests.sh --class NodeJSIPCTest    # single class (prefixed com.comapeo.core.)
./scripts/run-instrumented-tests.sh --skip-build             # reuse the last prebuild/build
./scripts/run-instrumented-tests.sh --unit-only              # == test:android:unit

The runner: ensures deps → expo prebuild --platform android --no-install (the with-android-tests plugin re-injects test sources) → boots an emulator if no device is attached → runs ./gradlew :comapeo-core-react-native:connectedDebugAndroidTest from apps/integration/android (with -Pandroid.testInstrumentationRunnerArguments.class=com.comapeo.core.<Class> when --class is given) → then the JVM unit tests.

Device note: when no device is attached the runner auto-boots emulator -list-avds | head -1 — the alphabetically-first AVD, which may not be the API level you want. Boot the AVD you intend to test against before running (emulator -avd <name> & adb wait-for-device) and the runner will use it.

To run a Gradle task directly (e.g. iterating without the prebuild step), cd apps/integration/android and invoke ./gradlew :comapeo-core-react-native:<task>.

Reports

• Instrumented: apps/integration/android/build/reports/androidTests/connected/
• JVM unit: android/build/reports/tests/

Reading logs

Two tags matter (android/src/main/java/com/comapeo/core/log.kt, android/src/main/cpp/log.cpp):

• ComapeoCore — Kotlin native layer (module, service, IPC, process guard).
• Comapeo:NodeJS — the embedded Node process's stdout/stderr, bridged to logcat by the JNI layer. This is where backend errors, dlopen failures, and JS stack traces surface.

adb logcat -c                                   # clear first
adb logcat -s ComapeoCore Comapeo:NodeJS        # both tags
# isolate the backend foreground-service process:
adb logcat --pid "$(adb shell pidof -s com.comapeo.core.integration:ComapeoCore)"

If pidof returns nothing, the FGS process hasn't started (or already exited) — check the ComapeoCore tag for the lifecycle transition (STOPPED → STARTING → STARTED) and whether startForeground was reached.

Gotchas

• The instrumented suite is slow; CI runs it only in the merge queue (or with the run-e2e label). docs/TESTING.md §5 has the decision table.
• apps/integration/android/ and ios/ are gitignored and regenerated by prebuild — never edit them directly; edit the source under apps/integration/tests/android/ and the with-android-tests plugin.
• For FGS cold-start latency/ANR work, benchmark a release build (e.g. assembleRelease) — a debug startForeground is ~10× slower (measured ~4.18 s debug vs ~434 ms release), so debug timings overstate the ANR risk.