From a3afefeda9a8365baacc8cfb5768ca5ee9fe3db5 Mon Sep 17 00:00:00 2001 From: Jose Olarte III Date: Thu, 5 Feb 2026 17:48:46 +0800 Subject: [PATCH] docs(testing): EMULATOR_GUIDE prerequisites and API 35 - Add "Checking and Installing Prerequisites" section: - How to check Node, npm, Java, ANDROID_HOME, adb, emulator, AVDs - Reference scripts/check-environment.js for partial check - Install steps for Node, Java, Android SDK (cmdline-tools only), sdkmanager packages, and avdmanager AVD creation - Align SDK and AVD with project: use API 35 (android-35, build-tools 35.0.0, Pixel8_API35) to match compileSdk/targetSdk in variables.gradle - Bump guide version to 1.1.0 and last-updated date --- docs/testing/EMULATOR_GUIDE.md | 90 +++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 12 deletions(-) diff --git a/docs/testing/EMULATOR_GUIDE.md b/docs/testing/EMULATOR_GUIDE.md index 9f03a5b..8db5c4c 100644 --- a/docs/testing/EMULATOR_GUIDE.md +++ b/docs/testing/EMULATOR_GUIDE.md @@ -1,8 +1,8 @@ # Running Android App in Standalone Emulator (Without Android Studio) **Author**: Matthew Raymer -**Last Updated**: 2025-10-12 06:50:00 UTC -**Version**: 1.0.0 +**Last Updated**: 2026-02-05 +**Version**: 1.1.0 ## Overview @@ -22,6 +22,72 @@ This guide demonstrates how to run the DailyNotification plugin test app in a st - **Storage**: 2GB free space for emulator - **OS**: Linux, macOS, or Windows with WSL +## Checking and Installing Prerequisites + +### How to check + +Run these in a terminal. If a command is missing or a check fails, use the install steps below. + +| Requirement | How to check | +|------------------|--------------| +| **Node.js** | `node --version` (v14+ recommended; test app may require 20+) | +| **npm** | `npm --version` | +| **Java** | `java -version` (Java 11+; build scripts expect 11+) | +| **ANDROID_HOME** | `echo $ANDROID_HOME` (must be set to your Android SDK root) | +| **adb** | `adb version` (must be on PATH; usually `$ANDROID_HOME/platform-tools/adb`) | +| **emulator** | `emulator -version` (must be on PATH; usually `$ANDROID_HOME/emulator/emulator`) | +| **At least one AVD** | `emulator -list-avds` (must list at least one device name) | + +**Project script:** From the repo root you can run: + +```bash +node scripts/check-environment.js +``` + +This checks Node, npm, Java, and `ANDROID_HOME`. It does **not** check `adb`, `emulator`, or AVDs—verify those manually as above. + +### How to install + +- **Node.js and npm** + - Install from [nodejs.org](https://nodejs.org/) (LTS), or on macOS: `brew install node`. + +- **Java (JDK 11+)** + - macOS: `brew install openjdk@17` and follow the caveats to link (e.g. `sudo ln -sfn $(brew --prefix)/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk`). + - Or install [Eclipse Temurin](https://adoptium.net/) / [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) and ensure `java` and `javac` are on your PATH. + +- **Android SDK (without Android Studio)** + 1. Download the [Command-line tools only](https://developer.android.com/studio#command-tools) package for your OS. + 2. Create an SDK directory, e.g. `mkdir -p ~/android-sdk` and extract the zip so that you have `~/android-sdk/cmdline-tools/latest/` (the `bin` folder with `sdkmanager` and `avdmanager` must be inside `cmdline-tools/latest/`). + 3. Set environment variables (add to `~/.zshrc` or `~/.bashrc`): + + ```bash + export ANDROID_HOME=$HOME/android-sdk + export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator + ``` + + 4. Install required SDK packages (accept licenses when prompted): + + ```bash + sdkmanager "platform-tools" + sdkmanager "emulator" + sdkmanager "platforms;android-35" + sdkmanager "system-images;android-35;google_apis;x86_64" + sdkmanager "build-tools;35.0.0" + ``` + + 5. Create at least one AVD: + + ```bash + avdmanager create avd -n Pixel8_API35 -k "system-images;android-35;google_apis;x86_64" -d "pixel_8" + ``` + + Then start the emulator with: `emulator -avd Pixel8_API35 -no-snapshot-load &` and use `adb wait-for-device` before building/installing the app. + +- **Gradle** + The project uses the Gradle Wrapper (`gradlew`) inside the app’s `android` directory. No separate Gradle install is needed. + +After installing, run the checks again to confirm `adb`, `emulator`, and `emulator -list-avds` work. + ## Step-by-Step Process ### 1. Check Available Emulators @@ -31,21 +97,21 @@ This guide demonstrates how to run the DailyNotification plugin test app in a st emulator -list-avds # Example output: -# Pixel8_API34 +# Pixel8_API35 ``` ### 2. Start the Emulator ```bash # Start emulator in background (recommended) -emulator -avd Pixel8_API34 -no-snapshot-load & +emulator -avd Pixel8_API35 -no-snapshot-load & # Alternative: Start in foreground -emulator -avd Pixel8_API34 +emulator -avd Pixel8_API35 ``` **Flags Explained:** -- `-avd Pixel8_API34` - Specifies the AVD to use +- `-avd Pixel8_API35` - Specifies the AVD to use - `-no-snapshot-load` - Forces fresh boot (recommended for testing) - `&` - Runs in background (optional) @@ -141,7 +207,7 @@ adb logcat -c && adb logcat ```bash # 1. Start emulator -emulator -avd Pixel8_API34 -no-snapshot-load & +emulator -avd Pixel8_API35 -no-snapshot-load & # 2. Wait for emulator adb wait-for-device @@ -211,7 +277,7 @@ ps aux | grep emulator pkill -f emulator # Start with verbose logging -emulator -avd Pixel8_API34 -verbose +emulator -avd Pixel8_API35 -verbose ``` #### ADB Connection Issues @@ -256,13 +322,13 @@ cd android && ./gradlew clean #### Emulator Performance ```bash # Start with hardware acceleration -emulator -avd Pixel8_API34 -accel on +emulator -avd Pixel8_API35 -accel on # Start with specific RAM allocation -emulator -avd Pixel8_API34 -memory 2048 +emulator -avd Pixel8_API35 -memory 2048 # Start with GPU acceleration -emulator -avd Pixel8_API34 -gpu host +emulator -avd Pixel8_API35 -gpu host ``` #### Build Performance @@ -336,7 +402,7 @@ adb shell am start -n com.timesafari.dailynotification/.MainActivity ### Automated Testing ```bash # CI/CD pipeline -emulator -avd Pixel8_API34 -no-snapshot-load & +emulator -avd Pixel8_API35 -no-snapshot-load & adb wait-for-device ./scripts/build-native.sh --platform android cd android && ./gradlew :app:assembleDebug