0
# Element Location
1

2
Appium-specific locator strategies for finding mobile elements across iOS and Android platforms. The AppiumBy class extends Selenium's By class with mobile-specific locators that are not available in standard WebDriver.
3

4
## Capabilities
5

6
### AppiumBy Locators
7

8
Extended locator class providing mobile-specific element finding strategies beyond standard WebDriver locators.
9

10
```python {.api}
11
class AppiumBy:
12
    # Standard WebDriver locators (inherited)
13
    ID: str = "id"
14
    XPATH: str = "xpath"
15
    LINK_TEXT: str = "link text"
16
    PARTIAL_LINK_TEXT: str = "partial link text"
17
    NAME: str = "name"
18
    TAG_NAME: str = "tag name"
19
    CLASS_NAME: str = "class name"
20
    CSS_SELECTOR: str = "css selector"
21
    
22
    # Appium-specific locators
23
    ACCESSIBILITY_ID: str = "accessibility id"
24
    ANDROID_UIAUTOMATOR: str = "-android uiautomator"
25
    ANDROID_VIEWTAG: str = "-android viewtag"
26
    ANDROID_DATA_MATCHER: str = "-android datamatcher"
27
    ANDROID_VIEW_MATCHER: str = "-android viewmatcher"
28
    IOS_PREDICATE: str = "-ios predicate string"
29
    IOS_CLASS_CHAIN: str = "-ios class chain"
30
    IMAGE: str = "-image"
31
    CUSTOM: str = "-custom"
32
    
33
    # Flutter integration locators
34
    FLUTTER_INTEGRATION_SEMANTICS_LABEL: str = "-flutter semantics label"
35
    FLUTTER_INTEGRATION_TYPE: str = "-flutter type"
36
    FLUTTER_INTEGRATION_KEY: str = "-flutter key"
37
    FLUTTER_INTEGRATION_TEXT: str = "-flutter text"
38
    FLUTTER_INTEGRATION_TEXT_CONTAINING: str = "-flutter text containing"
39
```
40

41
### Element Finding Methods
42

43
Standard element finding methods that work with AppiumBy locators for comprehensive mobile element location.
44

45
```python {.api}
46
def find_element(self, by: str, value: str):
47
    """
48
    Find single element using specified locator strategy.
49
    
50
    Args:
51
        by (str): Locator strategy (AppiumBy constant)
52
        value (str): Locator value/expression
53
        
54
    Returns:
55
        WebElement: Found element instance
56
        
57
    Raises:
58
        NoSuchElementException: If element not found
59
    """
60

61
def find_elements(self, by: str, value: str) -> list:
62
    """
63
    Find multiple elements using specified locator strategy.
64
    
65
    Args:
66
        by (str): Locator strategy (AppiumBy constant)
67
        value (str): Locator value/expression
68
        
69
    Returns:
70
        list: List of WebElement instances (empty if none found)
71
    """
72
```
73

74
## Usage Examples
75

76
### Cross-Platform Accessibility Locators
77

78
```python
79
from appium import webdriver
80
from appium.webdriver.common.appiumby import AppiumBy
81

82
# Accessibility ID - works across iOS and Android
83
login_button = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "loginButton")
84
login_button.click()
85

86
# Find multiple elements
87
menu_items = driver.find_elements(AppiumBy.ACCESSIBILITY_ID, "menuItem")
88
for item in menu_items:
89
    print(item.text)
90
```
91

92
### Android-Specific Locators
93

94
```python
95
# UiAutomator selector (Android only)
96
element = driver.find_element(
97
    AppiumBy.ANDROID_UIAUTOMATOR, 
98
    'new UiSelector().text("Login").className("android.widget.Button")'
99
)
100

101
# Complex UiAutomator queries
102
scrollable = driver.find_element(
103
    AppiumBy.ANDROID_UIAUTOMATOR,
104
    'new UiSelector().scrollable(true).instance(0)'
105
)
106

107
# View tag locator
108
tagged_element = driver.find_element(AppiumBy.ANDROID_VIEWTAG, "myViewTag")
109

110
# Data matcher for Espresso-style matching
111
espresso_element = driver.find_element(
112
    AppiumBy.ANDROID_DATA_MATCHER,
113
    '{"name":"hasEntry","args":["title","My Title"]}'
114
)
115
```
116

117
### iOS-Specific Locators
118

119
```python
120
# iOS Predicate String
121
element = driver.find_element(
122
    AppiumBy.IOS_PREDICATE, 
123
    "label CONTAINS 'Welcome' AND visible == 1"
124
)
125

126
# iOS Class Chain (more efficient than XPath)
127
chain_element = driver.find_element(
128
    AppiumBy.IOS_CLASS_CHAIN,
129
    '**/XCUIElementTypeCell[`label CONTAINS "Settings"`]'
130
)
131

132
# Complex predicate examples
133
user_element = driver.find_element(
134
    AppiumBy.IOS_PREDICATE,
135
    "type == 'XCUIElementTypeButton' AND name BEGINSWITH 'User'"
136
)
137
```
138

139
### Image-Based Location
140

141
```python
142
# Image locator using base64 encoded template image
143
import base64
144

145
with open("button_template.png", "rb") as image_file:
146
    template_b64 = base64.b64encode(image_file.read()).decode('utf-8')
147

148
image_element = driver.find_element(AppiumBy.IMAGE, template_b64)
149
image_element.click()
150
```
151

152
### Flutter Integration Locators
153

154
```python
155
# Flutter semantics label
156
flutter_button = driver.find_element(
157
    AppiumBy.FLUTTER_INTEGRATION_SEMANTICS_LABEL, 
158
    "Submit Button"
159
)
160

161
# Flutter widget type
162
text_fields = driver.find_elements(
163
    AppiumBy.FLUTTER_INTEGRATION_TYPE, 
164
    "TextField"
165
)
166

167
# Flutter key
168
key_element = driver.find_element(
169
    AppiumBy.FLUTTER_INTEGRATION_KEY, 
170
    "loginFormKey"
171
)
172

173
# Flutter text content
174
text_element = driver.find_element(
175
    AppiumBy.FLUTTER_INTEGRATION_TEXT, 
176
    "Welcome to App"
177
)
178

179
# Flutter partial text matching
180
partial_elements = driver.find_elements(
181
    AppiumBy.FLUTTER_INTEGRATION_TEXT_CONTAINING, 
182
    "Welcome"
183
)
184
```
185

186
### Combining Standard and Mobile Locators
187

188
```python
189
# Use standard WebDriver locators when appropriate
190
element_by_id = driver.find_element(AppiumBy.ID, "android:id/button1")
191
element_by_xpath = driver.find_element(AppiumBy.XPATH, "//android.widget.Button[@text='Click Me']")
192
element_by_class = driver.find_element(AppiumBy.CLASS_NAME, "android.widget.EditText")
193

194
# Combine with mobile-specific locators in the same test
195
accessibility_element = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "submitBtn")
196
uiautomator_element = driver.find_element(
197
    AppiumBy.ANDROID_UIAUTOMATOR, 
198
    'new UiSelector().resourceId("com.app:id/input")'
199
)
200
```
201

202
### Error Handling
203

204
```python
205
from selenium.common.exceptions import NoSuchElementException
206

207
try:
208
    element = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "nonExistentButton")
209
except NoSuchElementException:
210
    print("Element not found, trying alternative locator")
211
    element = driver.find_element(AppiumBy.XPATH, "//button[@text='Alternative']")
212

213
# Check if elements exist before interacting
214
elements = driver.find_elements(AppiumBy.CLASS_NAME, "android.widget.Button")
215
if elements:
216
    elements[0].click()
217
else:
218
    print("No buttons found")
219
```
220

221
## Types
222

223
```python {.api}
224
# Locator types
225
LocatorStrategy = str
226
LocatorValue = str
227
ElementList = List[WebElement]
228

229
# UiAutomator selector strings
230
UiAutomatorSelector = str  # e.g., 'new UiSelector().text("Login")'
231

232
# iOS predicate strings  
233
IOSPredicate = str  # e.g., "label CONTAINS 'Welcome'"
234

235
# iOS class chain strings
236
IOSClassChain = str  # e.g., '**/XCUIElementTypeCell[1]'
237

238
# Base64 encoded image data
239
ImageTemplate = str
240

241
# Flutter locator values
242
FlutterLocatorValue = str
243
```