Element Location

class AppiumBy:
    # Standard WebDriver locators (inherited)
    ID: str = "id"
    XPATH: str = "xpath"
    LINK_TEXT: str = "link text"
    PARTIAL_LINK_TEXT: str = "partial link text"
    NAME: str = "name"
    TAG_NAME: str = "tag name"
    CLASS_NAME: str = "class name"
    CSS_SELECTOR: str = "css selector"
    
    # Appium-specific locators
    ACCESSIBILITY_ID: str = "accessibility id"
    ANDROID_UIAUTOMATOR: str = "-android uiautomator"
    ANDROID_VIEWTAG: str = "-android viewtag"
    ANDROID_DATA_MATCHER: str = "-android datamatcher"
    ANDROID_VIEW_MATCHER: str = "-android viewmatcher"
    IOS_PREDICATE: str = "-ios predicate string"
    IOS_CLASS_CHAIN: str = "-ios class chain"
    IMAGE: str = "-image"
    CUSTOM: str = "-custom"
    
    # Flutter integration locators
    FLUTTER_INTEGRATION_SEMANTICS_LABEL: str = "-flutter semantics label"
    FLUTTER_INTEGRATION_TYPE: str = "-flutter type"
    FLUTTER_INTEGRATION_KEY: str = "-flutter key"
    FLUTTER_INTEGRATION_TEXT: str = "-flutter text"
    FLUTTER_INTEGRATION_TEXT_CONTAINING: str = "-flutter text containing"

def find_element(self, by: str, value: str):
    """
    Find single element using specified locator strategy.
    
    Args:
        by (str): Locator strategy (AppiumBy constant)
        value (str): Locator value/expression
        
    Returns:
        WebElement: Found element instance
        
    Raises:
        NoSuchElementException: If element not found
    """

def find_elements(self, by: str, value: str) -> list:
    """
    Find multiple elements using specified locator strategy.
    
    Args:
        by (str): Locator strategy (AppiumBy constant)
        value (str): Locator value/expression
        
    Returns:
        list: List of WebElement instances (empty if none found)
    """

from appium import webdriver
from appium.webdriver.common.appiumby import AppiumBy

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

# Find multiple elements
menu_items = driver.find_elements(AppiumBy.ACCESSIBILITY_ID, "menuItem")
for item in menu_items:
    print(item.text)

# UiAutomator selector (Android only)
element = driver.find_element(
    AppiumBy.ANDROID_UIAUTOMATOR, 
    'new UiSelector().text("Login").className("android.widget.Button")'
)

# Complex UiAutomator queries
scrollable = driver.find_element(
    AppiumBy.ANDROID_UIAUTOMATOR,
    'new UiSelector().scrollable(true).instance(0)'
)

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

# Data matcher for Espresso-style matching
espresso_element = driver.find_element(
    AppiumBy.ANDROID_DATA_MATCHER,
    '{"name":"hasEntry","args":["title","My Title"]}'
)

# iOS Predicate String
element = driver.find_element(
    AppiumBy.IOS_PREDICATE, 
    "label CONTAINS 'Welcome' AND visible == 1"
)

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

# Complex predicate examples
user_element = driver.find_element(
    AppiumBy.IOS_PREDICATE,
    "type == 'XCUIElementTypeButton' AND name BEGINSWITH 'User'"
)

# Image locator using base64 encoded template image
import base64

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

image_element = driver.find_element(AppiumBy.IMAGE, template_b64)
image_element.click()

# Flutter semantics label
flutter_button = driver.find_element(
    AppiumBy.FLUTTER_INTEGRATION_SEMANTICS_LABEL, 
    "Submit Button"
)

# Flutter widget type
text_fields = driver.find_elements(
    AppiumBy.FLUTTER_INTEGRATION_TYPE, 
    "TextField"
)

# Flutter key
key_element = driver.find_element(
    AppiumBy.FLUTTER_INTEGRATION_KEY, 
    "loginFormKey"
)

# Flutter text content
text_element = driver.find_element(
    AppiumBy.FLUTTER_INTEGRATION_TEXT, 
    "Welcome to App"
)

# Flutter partial text matching
partial_elements = driver.find_elements(
    AppiumBy.FLUTTER_INTEGRATION_TEXT_CONTAINING, 
    "Welcome"
)

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

# Combine with mobile-specific locators in the same test
accessibility_element = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "submitBtn")
uiautomator_element = driver.find_element(
    AppiumBy.ANDROID_UIAUTOMATOR, 
    'new UiSelector().resourceId("com.app:id/input")'
)

from selenium.common.exceptions import NoSuchElementException

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

# Check if elements exist before interacting
elements = driver.find_elements(AppiumBy.CLASS_NAME, "android.widget.Button")
if elements:
    elements[0].click()
else:
    print("No buttons found")

# Locator types
LocatorStrategy = str
LocatorValue = str
ElementList = List[WebElement]

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

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

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

# Base64 encoded image data
ImageTemplate = str

# Flutter locator values
FlutterLocatorValue = str