Skip to content

testing.md

Latest commit

 

History

History
147 lines (110 loc) · 4.42 KB

testing.md

File metadata and controls

147 lines (110 loc) · 4.42 KB
Raw

AndroidOutBox Testing

AndroidOutBox keeps the normal local feedback loop small. Regular Kotlin tests, Android lint, and release assembly are the default local checks. Lower-level native diagnostics use explicit tasks because they are more host-dependent; CI runs smoke, JNI integration, ASan, UBSan, and TSan, while stress and shutdown-race diagnostics remain opt-in.

Regular Checks

Run the Kotlin/JVM unit tests:

./gradlew :android-outbox:testDebugUnitTest --console=plain

Run Android lint:

./gradlew :android-outbox:lintRelease --console=plain

Build the release AAR:

./gradlew :android-outbox:assembleRelease --console=plain

Build the sample app:

./gradlew :app:assembleDebug --console=plain

Host-Native Smoke

The host-native smoke test compiles and executes the C core on the development machine. It validates queue pressure, bounded frame/config handling, provider cursor behavior, restart retry, ACK semantics, deterministic malformed parser input, and injected filesystem failures without requiring an Android device.

./gradlew :android-outbox:testNativeHost \
  -PandroidOutboxHostNative=true \
  --console=plain

For clean JSON output:

./gradlew -q :android-outbox:testNativeHost \
  -PandroidOutboxHostNative=true | sed -n '/^{/,$p'

Host Sanitizers

Run the native smoke suite in three separate instrumented binaries: AddressSanitizer (ASan), UndefinedBehaviorSanitizer (UBSan), and ThreadSanitizer (TSan).

./gradlew :android-outbox:testNativeHostAllSanitizers --console=plain

Run one sanitizer independently when diagnosing a failure:

./gradlew :android-outbox:testNativeHostAsan --console=plain
./gradlew :android-outbox:testNativeHostUbsan --console=plain
./gradlew :android-outbox:testNativeHostTsan --console=plain

ASan stops on memory-safety errors and enables leak detection on Linux. UBSan stops on the first detected undefined behavior. TSan detects data races and thread lifecycle mistakes under concurrent native tests. Every task first compiles and executes a small validation probe with an intentional fault, confirming that the requested sanitizer actually works. If the compiler, sanitizer support, or runtime is missing, the task fails with the detected reason and platform-specific install commands instead of being silently skipped. Set CC to select another host C compiler, for example:

CC=clang ./gradlew :android-outbox:testNativeHostAllSanitizers --console=plain

The shorter testNativeHostSanitizers aggregate remains available when only ASan and UBSan are wanted.

The host suite uses POSIX APIs. Windows users should run it inside WSL 2.

Host JNI Integration

The host JNI integration test builds a host-loadable shared library from the production C/JNI objects. It then validates pipe framing, file descriptor ownership, cursor/ACK behavior, provider isolation, and restart behavior from a plain JVM test.

./gradlew :android-outbox:testDebugUnitTest \
  --tests "io.github.phuongtran.androidoutbox.OutboxHostJniIntegrationTest" \
  -PandroidOutboxHostJni=true \
  --console=plain

Shutdown Race

Run this when changing lifecycle, pipe close, command serialization, or native shutdown behavior. It intentionally creates contention between write, flush, read, ACK, stats, and close paths.

./gradlew :android-outbox:testDebugUnitTest \
  --tests "io.github.phuongtran.androidoutbox.OutboxHostJniShutdownRaceTest" \
  -PandroidOutboxHostJniRace=true \
  --console=plain

Native Stress

Stress diagnostics are opt-in. They are useful when changing queue, writer, segment rotation, retention, or producer hot-path logic, but they should not run as part of the normal CI feedback loop.

./gradlew :android-outbox:testNativeHostStress \
  -PandroidOutboxStress=true \
  --console=plain

Useful knobs:

./gradlew :android-outbox:testNativeHostStress \
  -PandroidOutboxStress=true \
  -PandroidOutboxStressWorkers=8 \
  -PandroidOutboxStressRecordsPerWorker=20000 \
  -PandroidOutboxStressQueueCapacity=1024 \
  -PandroidOutboxStressMaxRecordBytes=256 \
  --console=plain

CI Policy

CI runs regular checks, the host-native smoke test, host JNI integration, and all three host sanitizers automatically. Stress and shutdown-race diagnostics remain manual because they are substantially heavier or more host-specific. Use the GitHub Actions manual workflow when you want those additional diagnostics.