Skip to content

README.md

Latest commit

 

History

History
150 lines (115 loc) · 4.33 KB

README.md

File metadata and controls

150 lines (115 loc) · 4.33 KB

Android Plugin Tests

Unit tests for the Android plugin functionality.

Running Tests

From the repository root:

# Run standard Android plugin tests (fast, no emulators)
devbox run test:plugin:android

# Run all tests including emulator tests
devbox run test:plugin:android:all

# Run specific test suites
devbox run test:plugin:android:lib                    # Utility function tests
devbox run test:plugin:android:devices                # Device management tests
devbox run test:plugin:android:emulator-detection     # Emulator detection logic
devbox run test:plugin:android:emulator-modes         # Pure vs normal mode behavior

Test Suites

test-lib.sh

Tests utility functions from scripts/lib/lib.sh:

  • JSON parsing
  • Path manipulation
  • String operations
  • Checksum validation

test-devices.sh

Tests device management from scripts/user/devices.sh:

  • Device CRUD operations
  • Lock file generation
  • Device validation
  • Configuration management

test-emulator-detection.sh

Tests emulator detection and matching logic from scripts/domain/emulator.sh:

  • Finding running emulators by AVD name
  • Listing all running emulators
  • Checking emulator responsiveness
  • Port availability detection
  • Cleanup of offline emulators

Key functions tested:

  • android_find_running_emulator() - Find emulator by AVD name
  • android_list_running_emulators() - List all running emulators
  • android_is_emulator_running() - Check if serial is running
  • android_cleanup_offline_emulators() - Clean up stale emulators
  • android_find_available_port() - Find free port for new emulator

test-emulator-modes.sh

Demonstrates and tests the behavioral differences between:

Normal Mode (default):

  • Reuses existing emulator if AVD matches
  • Fast iteration for development
  • Emulator persists between runs
  • May have state from previous runs

Pure Mode (TEST_PURE=1):

  • Always starts fresh emulator with clean state
  • Deterministic testing for CI/CD
  • Slower (full boot each time)
  • Emulator stopped after test completes

Emulator Detection

Why Serial (emulator-5554)?

The emulator serial is the standard identifier because:

  • Unique: Each emulator instance has a unique serial
  • Required: All adb commands require it: adb -s emulator-5554 shell ...
  • Stable: Remains constant for the emulator's lifetime
  • Standard: Used throughout Android tooling

Not PID because:

  • PIDs can be reused by the OS
  • Not portable across systems
  • Not recognized by adb

Detection Flow

# 1. List running emulators
adb devices
# Output: emulator-5554  device

# 2. Get AVD name from emulator
adb -s emulator-5554 shell getprop ro.boot.qemu.avd_name
# Output: pixel_api30

# 3. Match AVD to find running emulator
android_find_running_emulator "pixel_api30"
# Output: emulator-5554

# 4. Check emulator is responsive
adb -s emulator-5554 shell echo "ping"
# Output: ping

AVD Matching Logic

When starting an emulator in normal mode:

  1. Resolve target AVD: Determine which AVD to use (from config or default)
  2. Check running emulators: Query all emulator serials from adb devices
  3. Match by AVD name: For each serial, get its AVD name and compare
  4. Verify responsiveness: Ensure matched emulator responds to commands
  5. Reuse or start new: If match found, reuse it; otherwise start new

In pure mode, this matching is skipped and a fresh emulator always starts.

Test Output

All tests use colored output:

  • 🟢 Green ✓: Test passed
  • 🔴 Red ✗: Test failed
  • 🟡 Yellow ⚠: Warning or skipped test
  • 🔵 Blue: Informational output

Example:

========================================
TEST: Find running emulator
========================================
✓ android_find_running_emulator function exists
✓ Detects running emulator by serial
✓ Finds emulator by AVD name

Integration with E2E Tests

These unit tests complement the E2E tests in examples/android/tests/:

Unit tests (these files):

  • Test individual functions in isolation
  • Fast execution (< 1 minute)
  • No app building required
  • Can run with or without emulators

E2E tests (examples/android/tests/test-suite.yaml):

  • Test complete workflow
  • Includes build, emulator, deploy, verify
  • Slower (3-5 minutes)
  • Requires full Android environment

Run unit tests frequently during development. Run E2E tests before commits/PRs.