Skip to content

APPIUM_ANDROID_TESTING_WINDOWS.md

Latest commit

 

History

History
649 lines (458 loc) · 16.9 KB

APPIUM_ANDROID_TESTING_WINDOWS.md

File metadata and controls

649 lines (458 loc) · 16.9 KB

Appium Android Testing Guide (Windows)

This guide covers how to set up and run Appium tests for Android on Windows. It provides Windows-specific instructions for building, deploying, and testing the Android application.

Table of Contents

Prerequisites

  • Windows 10/11 (64-bit)
  • Android Studio or Android SDK Command-line Tools
  • Java Development Kit (JDK) 17 (NOT Java 24+ which is incompatible)
  • Node.js (version 20.x or later)
  • Android device or emulator
  • USB drivers (for physical device testing)

Quick Start

🚀 Fastest Workflow

REM 1. Create .env file in app\ directory with Auth0 configuration
REM See app\.env.example for required variables

REM 2. Setup environment and verify
scripts\windows\setup-test-env.bat

REM 3. Build and test (first run)
scripts\windows\run-local-test-android.bat --build welcome

REM 4. Fast iteration (subsequent runs)
scripts\windows\run-local-test-android.bat --skip-build welcome

REM 5. Run all tests
scripts\windows\run-local-test-android.bat all

⚡ Development Workflow

Scenario Command
Setup environment scripts\windows\setup-test-env.bat
List emulators scripts\windows\setup-test-env.bat --list-emulators
Start emulator scripts\windows\setup-test-env.bat --start-emulator Pixel_8_API_34
Stop Appium scripts\windows\setup-test-env.bat --stop-appium
Reuse last build scripts\windows\run-local-test-android.bat --skip-build welcome
Test specific file scripts\windows\run-local-test-android.bat .\test\specs\welcome.e2e.js
Run all tests scripts\windows\run-local-test-android.bat all
List suite tests scripts\windows\run-local-test-android.bat --dry-run welcome

Environment Setup

1. Install Java 17

Java 17 is required for Android development. Java 24+ is NOT compatible.

Option A: Eclipse Adoptium (Recommended)

  1. Download from Eclipse Adoptium
  2. Select Temurin 17 (LTS) for Windows x64
  3. Run the MSI installer
  4. During installation, check "Set JAVA_HOME variable"

Option B: Manual Installation

  1. Download and install JDK 17
  2. Set environment variables:
REM Set JAVA_HOME (adjust path to your installation)
setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-17.0.10+7-hotspot"

REM Add to PATH
setx PATH "%PATH%;%JAVA_HOME%\bin"

Verify Installation

java -version
REM Should show: openjdk version "17.x.x"

echo %JAVA_HOME%
REM Should show your JDK installation path

2. Install Android SDK

Option A: Android Studio (Recommended)

  1. Download Android Studio
  2. Run installer with default settings
  3. Complete the setup wizard (downloads SDK components)
  4. SDK will be installed at: %LOCALAPPDATA%\Android\Sdk

Option B: Command-line Tools Only

  1. Download Command-line tools
  2. Extract to C:\Android\cmdline-tools\latest
  3. Install required components:
cd C:\Android\cmdline-tools\latest\bin
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
sdkmanager "system-images;android-34;google_apis;x86_64"
sdkmanager --licenses

Set Environment Variables

REM Set ANDROID_HOME
setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"

REM Add tools to PATH
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools;%ANDROID_HOME%\emulator;%ANDROID_HOME%\cmdline-tools\latest\bin"

Verify Installation

adb --version
REM Should show Android Debug Bridge version

emulator -list-avds
REM Should list available emulators (may be empty initially)

3. Create Android Emulator (Optional)

If you don't have a physical device, create an emulator:

Using Android Studio

  1. Open Android Studio
  2. Go to Tools > Device Manager
  3. Click Create Device
  4. Select Pixel 8 (or similar)
  5. Select API 34 system image
  6. Complete wizard and click Finish

Using Command Line

REM Create emulator
avdmanager create avd -n Pixel_8_API_34 -k "system-images;android-34;google_apis;x86_64" -d "pixel_8"

REM List emulators to verify
emulator -list-avds

4. Install Node.js

  1. Download from nodejs.org
  2. Install the LTS version (20.x)
  3. Verify installation:
node --version
npm --version

5. Install Appium

REM Install Appium globally
npm install -g appium@3.1.1

REM Install UiAutomator2 driver for Android
appium driver install uiautomator2

REM Verify installation
appium --version
appium driver list --installed

6. USB Debugging (Physical Devices)

To test on a physical Android device:

  1. Enable Developer Options:

    • Go to Settings > About Phone
    • Tap "Build Number" 7 times

  2. Enable USB Debugging:

    • Go to Settings > Developer Options
    • Enable "USB Debugging"

  3. Connect Device:

    • Connect via USB cable
    • Accept the "Allow USB debugging?" prompt
    • Check "Always allow from this computer"

  4. Install USB Drivers (if needed):

    • For Google devices: Google USB Driver
    • For other manufacturers: Check manufacturer's website

  5. Verify Connection:

    adb devices
REM Should show your device with "device" status

7. Verify Environment

Run the setup script to load environment and check connectivity:

scripts\windows\setup-test-env.bat

This will:

  • ✅ Load environment variables from .env file
  • ✅ Configure platform-specific settings (Android/iOS)
  • ✅ Detect connected devices
  • ✅ Display configuration summary

To list available emulators:

scripts\windows\setup-test-env.bat --list-emulators

Running Tests

Using Batch Script

The primary way to run tests on Windows:

REM Run specific test suite
scripts\windows\run-local-test-android.bat welcome

REM Run all tests
scripts\windows\run-local-test-android.bat all

REM Run specific spec file
scripts\windows\run-local-test-android.bat .\test\specs\welcome.e2e.js

REM Build and run (when you've made app changes)
scripts\windows\run-local-test-android.bat --build welcome

REM Skip build, reuse last APK (fast iteration)
scripts\windows\run-local-test-android.bat --skip-build welcome

REM Use specific emulator
scripts\windows\run-local-test-android.bat --emulator Pixel_8_API_34 welcome

Using PowerShell

Alternative with better error handling:

# Run specific suite (uses .env file for Auth0 config)
.\scripts\windows\run-local-test-android.ps1 welcome

# Skip build, reuse last APK
.\scripts\windows\run-local-test-android.ps1 -SkipBuild welcome

# Use specific emulator
.\scripts\windows\run-local-test-android.ps1 -EmulatorName "Pixel_8_API_34" welcome

# Build and run (requires .env file with Auth0 configuration)
.\scripts\windows\run-local-test-android.ps1 -Build welcome

Note: The PowerShell script supports legacy -Environment and -ClientId parameters for backwards compatibility, but the recommended approach is to configure Auth0 settings in the .env file in the app\ directory.

Manual Testing Workflow

For more control over the process:

REM 1. Setup environment
scripts\windows\setup-test-env.bat

REM 2. Start Appium server (in separate terminal)
appium --address 127.0.0.1 --port 4723

REM 3. Run tests (this will build if needed)
scripts\windows\run-local-test-android.bat --build welcome

Scripts Reference

scripts\windows\run-local-test-android.bat

Main testing script that handles the complete workflow.

Prerequisites: .env file must exist in app\ directory with Auth0 configuration

Option Description
--build, -b Build the app before testing
--skip-build, -s Install existing APK from last build
--emulator Specify emulator AVD name to start
--list, --dry-run List all test cases without running them
--verbose, -v Enable verbose output
--help, -h Show help message

scripts\windows\setup-test-env.bat / setup-test-env.ps1

Sets up the test environment by loading .env variables and configuring platform settings.

Option Description
--platform, -p Target platform: android or ios (default: android)
--list-emulators, -l List available Android emulators
--start-emulator, -e Start Android emulator by AVD name
--start-appium, -a Start Appium server with inspector plugin
--stop-appium Stop all running Appium processes
--help, -h Show help message

scripts\windows\run-local-test-android.ps1

PowerShell alternative to the batch script with enhanced error handling.

Parameter Description
-Build Build the app before testing (requires .env file)
-SkipBuild Skip build and install existing APK from last build
-EmulatorName Specify emulator AVD name to start
-List, -DryRun List all test cases without running them
TestTarget Suite name, spec file, or 'all' (required)

Troubleshooting

Java Issues

"JAVA_HOME is not set"

REM Find your Java installation
where java

REM Set JAVA_HOME (adjust path as needed)
setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-17.0.10+7-hotspot"

REM Restart your terminal

"Unsupported class file major version 68"

This means you're using Java 24+. Install Java 17:

REM 1. Install Java 17 from Adoptium
REM 2. Set JAVA_HOME to Java 17 path
setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-17.0.10+7-hotspot"

REM 3. Stop Gradle daemons
cd app\android
gradlew --stop

REM 4. Clean and rebuild
gradlew clean

Android SDK Issues

"ANDROID_HOME is not set"

REM Set ANDROID_HOME (adjust if you installed SDK elsewhere)
setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"

REM Add to PATH
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools"

REM Restart your terminal

"adb is not recognized"

REM Check if adb exists
dir %ANDROID_HOME%\platform-tools\adb.exe

REM Add platform-tools to PATH
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools"

REM Or use full path
%ANDROID_HOME%\platform-tools\adb devices

Device Issues

Device not detected

  1. Check USB cable and try different port

  2. Ensure USB Debugging is enabled

  3. Revoke and re-authorize USB debugging:

    • Settings > Developer Options > Revoke USB debugging authorizations
    • Disconnect and reconnect device
    • Accept authorization prompt

  4. Install manufacturer USB drivers

  5. Try:

    adb kill-server
adb start-server
adb devices

"INSTALL_FAILED_UPDATE_INCOMPATIBLE"

REM Uninstall existing app first
adb uninstall com.softwareone.marketplaceMobile

REM Then install new APK
adb install path\to\app.apk

Emulator Issues

Emulator won't start

  1. Enable virtualization in BIOS (Intel VT-x or AMD-V)

  2. Install HAXM (Intel) or enable Windows Hypervisor Platform:

    • Control Panel > Programs > Turn Windows features on or off
    • Check "Windows Hypervisor Platform"
    • Restart computer

  3. Try with software rendering:

    emulator -avd YOUR_AVD -gpu swiftshader_indirect

Emulator is slow

  1. Use x86_64 system image instead of ARM
  2. Allocate more RAM to emulator
  3. Enable GPU acceleration in AVD settings
  4. Close other heavy applications

Appium Issues

"Appium not found"

REM Install Appium globally
npm install -g appium@3.1.1

REM Verify it's in PATH
where appium

"UiAutomator2 driver not found"

REM Install the driver
appium driver install uiautomator2

REM Verify installation
appium driver list --installed

Appium fails to start session

  1. Check device is connected: adb devices
  2. Verify app is installed: adb shell pm list packages | findstr softwareone
  3. Check Appium logs for specific error
  4. Try clearing app data: adb shell pm clear com.softwareone.marketplaceMobile

PowerShell Execution Policy

If you get an execution policy error:

# Check current policy
Get-ExecutionPolicy

# Allow local scripts (for current user only)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run script with bypass
powershell -ExecutionPolicy Bypass -File .\scripts\windows\run-local-test-android.ps1 welcome

Build Issues

Gradle build fails

cd app\android

REM Stop Gradle daemons
gradlew --stop

REM Clean project
gradlew clean

REM Try build again with more memory
set GRADLE_OPTS=-Xmx4096m
gradlew assembleDebug

"SDK location not found"

Create app\android\local.properties:

sdk.dir=C:\\Users\\YourUser\\AppData\\Local\\Android\\Sdk

CI/CD Considerations

GitHub Actions Windows Runner

While Windows runners can be used for Android testing, there are trade-offs:

Pros:

  • Native Windows environment
  • Good for Windows-specific testing
  • Access to Windows tools

Cons:

  • Slower emulator startup (no hardware acceleration in most runners)
  • Higher cost than Linux runners
  • Longer build times

Recommendation: Use macOS runners for Android CI/CD testing when possible, as they provide better emulator performance with hardware acceleration.

Example Windows Workflow

If you need Windows-based CI/CD:

name: Android E2E Tests (Windows)

on:
  workflow_dispatch:

jobs:
  test:
    runs-on: windows-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Java 17
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Setup Android SDK
        uses: android-actions/setup-android@v3
      
      - name: Install dependencies
        run: |
          cd app
          npm ci
      
      - name: Install Appium
        run: |
          npm install -g appium@3.1.1
          appium driver install uiautomator2
      
      # Note: Emulator setup on Windows CI is complex
      # Consider using macOS runners instead

Environment Variables Reference

Variable Description Default/Example
JAVA_HOME JDK installation path C:\Program Files\Eclipse Adoptium\jdk-17.0.10+7-hotspot
ANDROID_HOME Android SDK path %LOCALAPPDATA%\Android\Sdk
PLATFORM_NAME Target platform Android
DEVICE_UDID Device identifier Auto-detected
APP_PACKAGE Android app package com.softwareone.marketplaceMobile
APP_ACTIVITY Main activity .MainActivity
APPIUM_HOST Appium server host 127.0.0.1
APPIUM_PORT Appium server port 4723

Useful Commands

REM === Device Management ===
adb devices                              REM List connected devices
adb shell getprop ro.product.model       REM Get device model
adb shell getprop ro.build.version.sdk   REM Get Android API level

REM === App Management ===
adb install path\to\app.apk              REM Install APK
adb install -r path\to\app.apk           REM Replace existing app
adb uninstall com.package.name           REM Uninstall app
adb shell pm list packages               REM List installed packages
adb shell pm clear com.package.name      REM Clear app data

REM === Emulator ===
emulator -list-avds                      REM List available emulators
emulator -avd AVD_NAME                   REM Start emulator
emulator -avd AVD_NAME -no-audio         REM Start without audio

REM === Debugging ===
adb logcat                               REM View device logs
adb logcat | findstr "ReactNative"       REM Filter React Native logs
adb shell screencap /sdcard/screen.png   REM Take screenshot
adb pull /sdcard/screen.png              REM Pull file from device

REM === Appium ===
appium --version                         REM Check Appium version
appium driver list --installed           REM List installed drivers
appium --address 127.0.0.1 --port 4723   REM Start Appium server

Related Documentation

Note: This guide focuses on Windows-specific setup and commands. For cross-platform test architecture and writing tests, see the main testing documentation.