Emulator Management

Android emulator lifecycle management including discovery, launching, availability checking, and automated emulator selection for React Native development.

Capabilities

Emulator Discovery

Functions for discovering and listing available Android emulators on the development system.

/**
 * Get list of available Android emulators
 * Scans the Android SDK for configured emulator instances
 * @returns Array of emulator names
 */
function getEmulators(): string[];

Note: This function is internal and not directly exportable from the main package.

Emulator Launching

Automated emulator launching with success/failure reporting and optional port configuration.

/**
 * Attempt to launch Android emulator
 * @param adbPath - Path to ADB executable
 * @param emulatorName - Optional specific emulator name to launch
 * @param port - Optional port number for emulator
 * @returns Promise resolving to launch result with success status and error details
 */
async function tryLaunchEmulator(
  adbPath: string, 
  emulatorName?: string, 
  port?: number
): Promise<{success: boolean; error?: string}>;

Launch Result Interface:

interface EmulatorLaunchResult {
  /** Whether emulator launch was successful */
  success: boolean;
  /** Error message if launch failed */
  error?: string;
}

Note: This function is internal and not directly exportable from the main package. It's used internally by the run-android command for automatic emulator launching.

Internal Emulator Operations

/**
 * Launch specific emulator instance
 * Internal function for emulator launching with detailed configuration
 * @param emulatorName - Name of emulator to launch
 * @param adbPath - Path to ADB executable
 * @param port - Optional port number for emulator instance
 * @returns Promise resolving to true if launch successful
 */
async function launchEmulator(emulatorName: string, adbPath: string, port?: number): Promise<boolean>;

Emulator Management Details

Emulator Discovery Process

The getEmulators() function:

1. Scans Android SDK: Looks in $ANDROID_HOME/avd/ directory
2. Parses AVD files: Reads emulator configuration files
3. Filters valid emulators: Returns only properly configured emulators
4. Returns display names: Provides human-readable emulator names

Launch Process

The tryLaunchEmulator() function implements a comprehensive launch process:

1. Validation: Checks if emulator name exists and is valid
2. Port Management: Allocates available port if not specified
3. Launch Command: Executes emulator binary with proper arguments
4. Status Monitoring: Waits for emulator to become available
5. Error Handling: Captures and reports launch failures
6. Result Reporting: Returns structured success/failure information

Emulator Selection Logic

When no specific emulator is provided:

1. Auto-selection: Chooses first available emulator
2. Preference order: Prioritizes recently used emulators
3. Fallback handling: Provides clear error messages if none available

Port Configuration

Emulator port management:

• Default ports: Uses Android standard ports (5554, 5556, 5558, etc.)
• Port conflicts: Automatically finds available ports
• Multiple instances: Supports running multiple emulators simultaneously
• Port validation: Ensures port is not in use before launch

Launch Timeouts and Retry Logic

The launch process includes:

• Startup timeout: Waits reasonable time for emulator boot
• Health checks: Verifies emulator is responsive via ADB
• Retry mechanism: Attempts launch multiple times if initial attempt fails
• Resource cleanup: Properly handles failed launch cleanup

Error Handling

Common Launch Failures

The emulator management system handles various failure scenarios:

• Emulator not found: Invalid or non-existent emulator name
• Android SDK issues: Missing or misconfigured Android SDK
• Hardware acceleration: Insufficient hardware virtualization support
• Port conflicts: Requested port already in use
• Resource constraints: Insufficient system memory or disk space
• Permission issues: File system or device permissions

Error Reporting

Error messages provide actionable information:

const result = await tryLaunchEmulator(adbPath, "invalid-emulator");
if (!result.success) {
  // result.error contains specific failure reason:
  // "Emulator 'invalid-emulator' not found"
  // "Android SDK not configured properly"
  // "Insufficient system resources"
  // "Port 5554 is already in use"
}

Integration with React Native CLI

Automatic Emulator Selection

When using React Native CLI commands:

• run-android: Automatically launches emulator if no device connected
• Device preference: Prioritizes physical devices over emulators
• Interactive selection: Prompts user to choose from available emulators
• Launch coordination: Manages emulator startup before app deployment

Development Workflow Integration

Emulator management integrates seamlessly with development workflows:

1. Project startup: Automatically launches appropriate emulator
2. Multi-device testing: Supports launching multiple emulator instances
3. CI/CD integration: Provides programmatic emulator control
4. Debug workflows: Coordinates with debugger and Metro bundler

Usage in Development Scripts:

import { getEmulators, tryLaunchEmulator, getAdbPath } from "@react-native-community/cli-platform-android";

async function setupDevelopmentEnvironment() {
  const adbPath = getAdbPath();
  const emulators = getEmulators();
  
  if (emulators.length === 0) {
    console.error("No emulators configured. Please create an AVD first.");
    return;
  }
  
  // Launch first available emulator
  const result = await tryLaunchEmulator(adbPath, emulators[0]);
  if (result.success) {
    console.log(`Development emulator ${emulators[0]} is ready`);
  } else {
    console.error(`Failed to launch emulator: ${result.error}`);
  }
}