0
# Emulator Management
1

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

4
## Capabilities
5

6
### Emulator Discovery
7

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

10
```typescript { .api }
11
/**
12
 * Get list of available Android emulators
13
 * Scans the Android SDK for configured emulator instances
14
 * @returns Array of emulator names
15
 */
16
function getEmulators(): string[];
17
```
18

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

21
### Emulator Launching
22

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

25
```typescript { .api }
26
/**
27
 * Attempt to launch Android emulator
28
 * @param adbPath - Path to ADB executable
29
 * @param emulatorName - Optional specific emulator name to launch
30
 * @param port - Optional port number for emulator
31
 * @returns Promise resolving to launch result with success status and error details
32
 */
33
async function tryLaunchEmulator(
34
  adbPath: string, 
35
  emulatorName?: string, 
36
  port?: number
37
): Promise<{success: boolean; error?: string}>;
38
```
39

40
**Launch Result Interface:**
41
```typescript { .api }
42
interface EmulatorLaunchResult {
43
  /** Whether emulator launch was successful */
44
  success: boolean;
45
  /** Error message if launch failed */
46
  error?: string;
47
}
48
```
49

50
**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.
51

52
### Internal Emulator Operations
53

54
```typescript { .api }
55
/**
56
 * Launch specific emulator instance
57
 * Internal function for emulator launching with detailed configuration
58
 * @param emulatorName - Name of emulator to launch
59
 * @param adbPath - Path to ADB executable
60
 * @param port - Optional port number for emulator instance
61
 * @returns Promise resolving to true if launch successful
62
 */
63
async function launchEmulator(emulatorName: string, adbPath: string, port?: number): Promise<boolean>;
64
```
65

66
## Emulator Management Details
67

68
### Emulator Discovery Process
69

70
The `getEmulators()` function:
71
1. **Scans Android SDK**: Looks in `$ANDROID_HOME/avd/` directory
72
2. **Parses AVD files**: Reads emulator configuration files
73
3. **Filters valid emulators**: Returns only properly configured emulators
74
4. **Returns display names**: Provides human-readable emulator names
75

76
### Launch Process
77

78
The `tryLaunchEmulator()` function implements a comprehensive launch process:
79

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

87
### Emulator Selection Logic
88

89
When no specific emulator is provided:
90
1. **Auto-selection**: Chooses first available emulator
91
2. **Preference order**: Prioritizes recently used emulators
92
3. **Fallback handling**: Provides clear error messages if none available
93

94
### Port Configuration
95

96
Emulator port management:
97
- **Default ports**: Uses Android standard ports (5554, 5556, 5558, etc.)
98
- **Port conflicts**: Automatically finds available ports
99
- **Multiple instances**: Supports running multiple emulators simultaneously
100
- **Port validation**: Ensures port is not in use before launch
101

102
### Launch Timeouts and Retry Logic
103

104
The launch process includes:
105
- **Startup timeout**: Waits reasonable time for emulator boot
106
- **Health checks**: Verifies emulator is responsive via ADB
107
- **Retry mechanism**: Attempts launch multiple times if initial attempt fails
108
- **Resource cleanup**: Properly handles failed launch cleanup
109

110
## Error Handling
111

112
### Common Launch Failures
113

114
The emulator management system handles various failure scenarios:
115

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

123
### Error Reporting
124

125
Error messages provide actionable information:
126
```typescript
127
const result = await tryLaunchEmulator(adbPath, "invalid-emulator");
128
if (!result.success) {
129
  // result.error contains specific failure reason:
130
  // "Emulator 'invalid-emulator' not found"
131
  // "Android SDK not configured properly"
132
  // "Insufficient system resources"
133
  // "Port 5554 is already in use"
134
}
135
```
136

137
## Integration with React Native CLI
138

139
### Automatic Emulator Selection
140

141
When using React Native CLI commands:
142
- **run-android**: Automatically launches emulator if no device connected
143
- **Device preference**: Prioritizes physical devices over emulators
144
- **Interactive selection**: Prompts user to choose from available emulators
145
- **Launch coordination**: Manages emulator startup before app deployment
146

147
### Development Workflow Integration
148

149
Emulator management integrates seamlessly with development workflows:
150
1. **Project startup**: Automatically launches appropriate emulator
151
2. **Multi-device testing**: Supports launching multiple emulator instances
152
3. **CI/CD integration**: Provides programmatic emulator control
153
4. **Debug workflows**: Coordinates with debugger and Metro bundler
154

155
**Usage in Development Scripts:**
156

157
```typescript
158
import { getEmulators, tryLaunchEmulator, getAdbPath } from "@react-native-community/cli-platform-android";
159

160
async function setupDevelopmentEnvironment() {
161
  const adbPath = getAdbPath();
162
  const emulators = getEmulators();
163
  
164
  if (emulators.length === 0) {
165
    console.error("No emulators configured. Please create an AVD first.");
166
    return;
167
  }
168
  
169
  // Launch first available emulator
170
  const result = await tryLaunchEmulator(adbPath, emulators[0]);
171
  if (result.success) {
172
    console.log(`Development emulator ${emulators[0]} is ready`);
173
  } else {
174
    console.error(`Failed to launch emulator: ${result.error}`);
175
  }
176
}
177
```