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
2026-02-05 17:48:46 +08:00
parent d0155f0b22
commit a3afefeda9
1 changed files with 78 additions and 12 deletions
--- 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