0
# Configuration Options
1

2
Platform-specific capability configuration classes for Android (UiAutomator2, Espresso), iOS (XCUITest, Safari), and other platforms. These options classes provide type-safe configuration of Appium capabilities and driver-specific settings.
3

4
## Capabilities
5

6
### Base Options Class
7

8
Foundation class for all platform-specific options providing common capability management functionality.
9

10
```python {.api}
11
class AppiumOptions:
12
    def __init__(self):
13
        """Initialize options with empty capabilities."""
14
    
15
    def set_capability(self, name: str, value):
16
        """
17
        Set a capability value.
18
        
19
        Args:
20
            name (str): Capability name
21
            value: Capability value (any type)
22
        """
23
    
24
    def get_capability(self, name: str):
25
        """
26
        Get a capability value.
27
        
28
        Args:
29
            name (str): Capability name
30
            
31
        Returns:
32
            Any: Capability value or None if not set
33
        """
34
    
35
    def load_capabilities(self, caps: dict):
36
        """
37
        Load multiple capabilities from dictionary.
38
        
39
        Args:
40
            caps (dict): Dictionary of capability name-value pairs
41
        """
42
    
43
    def to_w3c(self) -> dict:
44
        """
45
        Convert capabilities to W3C format.
46
        
47
        Returns:
48
            dict: W3C-formatted capabilities
49
        """
50
    
51
    def to_capabilities(self) -> dict:
52
        """
53
        Convert to capabilities dictionary.
54
        
55
        Returns:
56
            dict: Capabilities dictionary ready for WebDriver
57
        """
58
```
59

60
### Android Options
61

62
Android platform-specific options classes for UiAutomator2 and Espresso drivers.
63

64
```python {.api}
65
class UiAutomator2Options(AppiumOptions):
66
    """Options for Android UiAutomator2 driver with 100+ capability mixins."""
67
    
68
    # Core Android capabilities
69
    platform_name: str = "Android"
70
    device_name: str = None
71
    platform_version: str = None
72
    udid: str = None
73
    
74
    # App capabilities
75
    app: str = None
76
    app_package: str = None
77
    app_activity: str = None
78
    app_wait_package: str = None
79
    app_wait_activity: str = None
80
    
81
    # Device capabilities
82
    system_port: int = None
83
    device_ready_timeout: int = None
84
    android_device_ready_timeout: int = None
85
    
86
    # ADB capabilities
87
    adb_port: int = None
88
    adb_exec_timeout: int = None
89
    
90
    # Chrome/WebView capabilities
91
    chromedriver_executable: str = None
92
    chromedriver_port: int = None
93
    chrome_options: dict = None
94
    
95
    def __init__(self):
96
        """Initialize UiAutomator2 options with Android defaults."""
97

98
class EspressoOptions(AppiumOptions):
99
    """Options for Android Espresso driver."""
100
    
101
    platform_name: str = "Android"
102
    automation_name: str = "Espresso"
103
    
104
    def __init__(self):
105
        """Initialize Espresso options with Android defaults."""
106
```
107

108
### iOS Options
109

110
iOS platform-specific options classes for XCUITest and Safari drivers.
111

112
```python {.api}
113
class XCUITestOptions(AppiumOptions):
114
    """Options for iOS XCUITest driver with 100+ capability mixins."""
115
    
116
    # Core iOS capabilities
117
    platform_name: str = "iOS"
118
    device_name: str = None
119
    platform_version: str = None
120
    udid: str = None
121
    
122
    # App capabilities
123
    app: str = None
124
    bundle_id: str = None
125
    
126
    # Simulator capabilities
127
    simulator_startup_timeout: int = None
128
    simulator_tracing_timeout: int = None
129
    
130
    # WebDriverAgent capabilities
131
    wda_launch_timeout: int = None
132
    wda_connection_timeout: int = None
133
    wda_startup_retries: int = None
134
    wda_base_url: str = None
135
    
136
    # WebView capabilities
137
    safari_options: dict = None
138
    webkit_response_timeout: int = None
139
    
140
    def __init__(self):
141
        """Initialize XCUITest options with iOS defaults."""
142

143
class SafariOptions(AppiumOptions):
144
    """Options for iOS Safari driver."""
145
    
146
    platform_name: str = "iOS"
147
    browser_name: str = "Safari"
148
    
149
    def __init__(self):
150
        """Initialize Safari options with iOS defaults."""
151
```
152

153
### Other Platform Options
154

155
Options classes for additional platforms including Mac, Windows, and specialized drivers.
156

157
```python {.api}
158
class Mac2Options(AppiumOptions):
159
    """Options for Mac automation."""
160
    
161
    platform_name: str = "Mac"
162
    automation_name: str = "Mac2"
163
    
164
    def __init__(self):
165
        """Initialize Mac2 options."""
166

167
class WindowsOptions(AppiumOptions):
168
    """Options for Windows automation."""
169
    
170
    platform_name: str = "Windows"
171
    automation_name: str = "Windows"
172
    
173
    def __init__(self):
174
        """Initialize Windows options."""
175

176
class GeckoOptions(AppiumOptions):
177
    """Options for Gecko (Firefox) automation."""
178
    
179
    browser_name: str = "firefox"
180
    automation_name: str = "Gecko"
181
    
182
    def __init__(self):
183
        """Initialize Gecko options."""
184

185
class FlutterIntegrationOptions(AppiumOptions):
186
    """Options for Flutter integration."""
187
    
188
    automation_name: str = "Flutter"
189
    
190
    def __init__(self):
191
        """Initialize Flutter integration options."""
192
```
193

194
## Usage Examples
195

196
### Basic Android Configuration
197

198
```python
199
from appium import webdriver
200
from appium.options.android import UiAutomator2Options
201

202
# Create and configure Android options
203
options = UiAutomator2Options()
204
options.platform_name = "Android"
205
options.device_name = "Android Emulator"
206
options.platform_version = "11"
207
options.app = "/path/to/your/app.apk"
208
options.app_package = "com.example.myapp"
209
options.app_activity = ".MainActivity"
210

211
# Additional Android-specific settings
212
options.system_port = 8200
213
options.chromedriver_port = 9515
214
options.device_ready_timeout = 60
215
options.adb_exec_timeout = 20000
216

217
# Start driver with options
218
driver = webdriver.Remote("http://localhost:4723", options=options)
219
```
220

221
### iOS Configuration
222

223
```python
224
from appium import webdriver
225
from appium.options.ios import XCUITestOptions
226

227
# Create and configure iOS options
228
options = XCUITestOptions()
229
options.platform_name = "iOS"
230
options.device_name = "iPhone 14"
231
options.platform_version = "16.0"
232
options.app = "/path/to/your/app.ipa"
233
options.bundle_id = "com.example.myapp"
234

235
# iOS-specific settings
236
options.wda_launch_timeout = 60000
237
options.wda_connection_timeout = 60000
238
options.simulator_startup_timeout = 180000
239

240
# WebView testing configuration
241
options.safari_options = {
242
    "webInspectorDebugProxyPort": 9999
243
}
244

245
# Start driver with options
246
driver = webdriver.Remote("http://localhost:4723", options=options)
247
```
248

249
### Advanced Capability Configuration
250

251
```python
252
# Using generic capability setting
253
options = UiAutomator2Options()
254

255
# Set individual capabilities
256
options.set_capability("appium:deviceName", "Pixel 4")
257
options.set_capability("appium:platformVersion", "12")
258
options.set_capability("appium:noReset", True)
259
options.set_capability("appium:fullReset", False)
260

261
# Load capabilities from dictionary
262
caps_dict = {
263
    "appium:automationName": "UiAutomator2",
264
    "appium:newCommandTimeout": 300,
265
    "appium:unicodeKeyboard": True,
266
    "appium:resetKeyboard": True
267
}
268
options.load_capabilities(caps_dict)
269

270
# Get capability values
271
device_name = options.get_capability("appium:deviceName")
272
print(f"Device name: {device_name}")
273

274
# Convert to different formats
275
w3c_caps = options.to_w3c()
276
legacy_caps = options.to_capabilities()
277
```
278

279
### Chrome/WebView Configuration
280

281
```python
282
# Configure for hybrid app testing
283
options = UiAutomator2Options()
284
options.platform_name = "Android"
285
options.device_name = "Android Emulator"
286
options.app = "/path/to/hybrid/app.apk"
287

288
# Chrome/WebView specific settings
289
options.chromedriver_executable = "/path/to/chromedriver"
290
options.chromedriver_port = 9515
291

292
# Chrome options for WebView
293
chrome_options = {
294
    "w3c": False,
295
    "args": ["--disable-web-security", "--allow-running-insecure-content"]
296
}
297
options.chrome_options = chrome_options
298

299
# Additional WebView settings
300
options.set_capability("appium:chromedriverExecutableDir", "/usr/local/bin")
301
options.set_capability("appium:autoWebview", True)
302
options.set_capability("appium:autoWebviewTimeout", 20000)
303
```
304

305
### Multi-Platform Testing Setup
306

307
```python
308
def create_android_options():
309
    """Create Android testing options."""
310
    options = UiAutomator2Options()
311
    options.platform_name = "Android"
312
    options.device_name = "Android Emulator"
313
    options.app = "/path/to/android/app.apk"
314
    options.app_package = "com.example.app"
315
    options.app_activity = ".MainActivity"
316
    return options
317

318
def create_ios_options():
319
    """Create iOS testing options."""
320
    options = XCUITestOptions()
321
    options.platform_name = "iOS"
322
    options.device_name = "iPhone 14"
323
    options.app = "/path/to/ios/app.ipa"
324
    options.bundle_id = "com.example.app"
325
    return options
326

327
def create_safari_options():
328
    """Create Safari web testing options."""
329
    options = SafariOptions()
330
    options.platform_name = "iOS"
331
    options.browser_name = "Safari"
332
    options.device_name = "iPhone 14"
333
    return options
334

335
# Platform detection and configuration
336
import sys
337

338
def get_platform_options(platform):
339
    """Get options based on platform."""
340
    if platform.lower() == "android":
341
        return create_android_options()
342
    elif platform.lower() == "ios":
343
        return create_ios_options()
344
    elif platform.lower() == "safari":
345
        return create_safari_options()
346
    else:
347
        raise ValueError(f"Unsupported platform: {platform}")
348

349
# Usage
350
platform = "android"  # Could be from command line or config
351
options = get_platform_options(platform)
352
driver = webdriver.Remote("http://localhost:4723", options=options)
353
```
354

355
### Real Device Configuration
356

357
```python
358
# Android real device
359
def configure_android_real_device():
360
    options = UiAutomator2Options()
361
    options.platform_name = "Android"
362
    options.device_name = "Samsung Galaxy S21"
363
    options.udid = "R58M40B1234"  # Device UDID
364
    options.platform_version = "12"
365
    options.app = "/path/to/app.apk"
366
    
367
    # Real device specific settings
368
    options.set_capability("appium:systemPort", 8200)
369
    options.set_capability("appium:skipServerInstallation", True)
370
    options.set_capability("appium:skipDeviceInitialization", True)
371
    
372
    return options
373

374
# iOS real device
375
def configure_ios_real_device():
376
    options = XCUITestOptions()
377
    options.platform_name = "iOS"
378
    options.device_name = "iPhone 13"
379
    options.udid = "00008110-001234567890123A"  # Device UDID
380
    options.platform_version = "15.4"
381
    options.bundle_id = "com.example.app"
382
    
383
    # Real device specific settings
384
    options.set_capability("appium:xcodeOrgId", "TEAM12345")
385
    options.set_capability("appium:xcodeSigningId", "iPhone Developer")
386
    options.set_capability("appium:useNewWDA", False)
387
    options.set_capability("appium:usePrebuiltWDA", True)
388
    
389
    return options
390
```
391

392
### Cloud Testing Configuration
393

394
```python
395
# Sauce Labs configuration
396
def configure_sauce_labs():
397
    options = UiAutomator2Options()
398
    options.platform_name = "Android"
399
    options.device_name = "Samsung Galaxy S.*"
400
    options.platform_version = "12"
401
    options.app = "sauce-storage:app.apk"
402
    
403
    # Sauce Labs specific capabilities
404
    options.set_capability("appium:appiumVersion", "2.0.0")
405
    options.set_capability("sauce:options", {
406
        "name": "My Test",
407
        "build": "Build 123",
408
        "tags": ["mobile", "android"]
409
    })
410
    
411
    return options
412

413
# BrowserStack configuration  
414
def configure_browserstack():
415
    options = XCUITestOptions()
416
    options.platform_name = "iOS"
417
    options.device_name = "iPhone 14"
418
    options.platform_version = "16"
419
    options.app = "bs://app-id-from-upload"
420
    
421
    # BrowserStack specific capabilities
422
    options.set_capability("bstack:options", {
423
        "projectName": "My Project",
424
        "buildName": "Build 123",
425
        "sessionName": "iOS Test"
426
    })
427
    
428
    return options
429
```
430

431
## Types
432

433
```python {.api}
434
# Base types
435
CapabilityName = str
436
CapabilityValue = Union[str, int, bool, dict, list]
437
CapabilitiesDict = Dict[str, CapabilityValue]
438

439
# Platform identifiers
440
PlatformName = str  # "Android", "iOS", "Windows", "Mac"
441
DeviceName = str    # Device name or pattern
442
PlatformVersion = str  # OS version
443
UDID = str         # Device unique identifier
444

445
# App identifiers
446
AppPath = str      # File path to app binary
447
PackageName = str  # Android package name
448
BundleId = str     # iOS bundle identifier
449
ActivityName = str # Android activity name
450

451
# Connection settings
452
ServerURL = str    # Appium server URL
453
Port = int        # Port number
454
Timeout = int     # Timeout in milliseconds
455

456
# Chrome/WebView settings
457
ChromeOptions = Dict[str, Union[bool, List[str]]]
458
ChromeDriverPath = str
459

460
# Cloud service settings
461
SauceOptions = Dict[str, Union[str, List[str]]]
462
BrowserStackOptions = Dict[str, str]
463
```