Appium Automation

Appium Automation Skill

Cross-platform mobile automation agent for iOS, Android, and Mac Catalyst apps.

When to Use

• ✅ Automating UI interactions on iOS Simulator
• ✅ Automating UI interactions on Android Emulator
• ✅ Testing Mac Catalyst apps
• ✅ Reproducing issues on device
• ✅ Validating PR fixes with real device testing
• ✅ Exploring app UI structure (use --list-elements, --list-buttons, --page-source)

When NOT to Use

• ❌ Writing NUnit UI tests → Use uitest-coding-agent
• ❌ Full PR workflow → Use pr agent
• ❌ Just building/deploying Sandbox → Use sandbox-agent

Important Guidelines

🚫 Avoid Screenshots for Reading the Screen

Do NOT use --screenshot to read or understand the UI unless the user explicitly asks for a screenshot. Instead, use:

• --list-elements — List all elements with their IDs and text
• --list-buttons — List all button labels
• --page-source — Get the full XML element tree
• --get-text ID — Get text from a specific element

These are faster, more accurate, and consume less resources than screenshots.

💡 Recommend Adding AutomationId

When elements are hard to target (e.g., id=None or relying on text matching), suggest to the user that they add AutomationId to their XAML elements. This makes automation much more reliable.

Example suggestion:

"I notice some elements don't have AutomationId set. Would you like me to help add AutomationId attributes to your XAML? This will make UI automation more reliable."

Important: AutomationId Setup

For reliable element targeting, add AutomationId to your XAML elements:

<!-- Before: No way to reliably target this element -->
<Entry Placeholder="Enter amount" />

<!-- After: Can target with --tap AmountEntry or --type AmountEntry "100" -->
<Entry AutomationId="AmountEntry" Placeholder="Enter amount" />

Recommended Pattern

Add AutomationId to all interactive elements:

<Entry AutomationId="SubtotalEntry" ... />
<Button AutomationId="CalculateButton" ... />
<Label AutomationId="ResultLabel" ... />
<Slider AutomationId="TipSlider" ... />

Platform Mapping

Without AutomationId, you must use --tap-text or --tap-button which are less reliable.

Prerequisites

1. Appium Server

npm install -g appium
appium driver install xcuitest      # iOS/Catalyst
appium driver install uiautomator2  # Android
appium driver install mac2          # Mac Catalyst

Note: Appium auto-starts if not running when you run an automation command.

2. Python Dependencies

pip install Appium-Python-Client selenium

3. Platform Requirements

4. Mac Catalyst Setup (Required for Mac Catalyst only)

The Mac2 driver requires WebDriverAgentMac to be built before first use:

# Navigate to the WebDriverAgentMac project
cd ~/.appium/node_modules/appium-mac2-driver/WebDriverAgentMac

# Build WebDriverAgentRunner for macOS
xcodebuild -project WebDriverAgentMac.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'platform=macOS' \
  -configuration Debug \
  build

Note: This only needs to be done once after installing the mac2 driver. If you update the driver (appium driver update mac2), rebuild WebDriverAgentMac.

Quick Start

Start Appium Server

# Start in background
appium --relaxed-security &

# Or use the script
python .github/skills/appium-automation/scripts/automate.py --start-appium

List Available Devices

python .github/skills/appium-automation/scripts/automate.py --list-devices

Boot iOS Simulator

python .github/skills/appium-automation/scripts/automate.py --boot-simulator "iPhone 16 Pro"

CLI Reference

Basic Syntax

python .github/skills/appium-automation/scripts/automate.py \
  --platform <ios|android|maccatalyst> \
  --app-id <bundle.id.or.package> \
  [actions...]

Actions

Keyboard & Input

Alerts & Dialogs

Sliders

Gestures

App Lifecycle

Debug & Inspection

Common Workflows

.NET MAUI iOS Testing

# 1. Boot simulator and start Appium
python .github/skills/appium-automation/scripts/automate.py --boot-simulator "iPhone 16 Pro"
python .github/skills/appium-automation/scripts/automate.py --start-appium

# 2. Build and install app (using dotnet)
dotnet build src/Controls/samples/Controls.Sample.Sandbox -f net9.0-ios
xcrun simctl install booted path/to/Controls.Sample.Sandbox.app

# 3. Automate
python .github/skills/appium-automation/scripts/automate.py \
  --platform ios \
  --app-id com.microsoft.maui.sandbox \
  --tap NavigateButton --wait 1 --get-text ResultLabel

.NET MAUI Android Testing

# 1. Start emulator and Appium
emulator -avd Pixel_6_API_33 &
python .github/skills/appium-automation/scripts/automate.py --start-appium

# 2. Build and install (IMPORTANT: use EmbedAssembliesIntoApk for automation)
dotnet build src/Controls/samples/Controls.Sample.Sandbox -f net9.0-android -p:EmbedAssembliesIntoApk=true
adb install path/to/com.microsoft.maui.sandbox-Signed.apk

# 3. Automate
python .github/skills/appium-automation/scripts/automate.py \
  --platform android \
  --app-id com.microsoft.maui.sandbox \
  --tap NavigateButton --wait 1 --screenshot result.png

Chained Actions

# Multiple actions in sequence (RECOMMENDED for performance)
python .github/skills/appium-automation/scripts/automate.py \
  --platform ios --app-id com.example.app \
  --tap UsernameField --type UsernameField "testuser" \
  --tap PasswordField --type PasswordField "password123" \
  --tap-button "Sign In" --wait 2 \
  --get-text WelcomeLabel

Performance Tip: Chain multiple operations in a single CLI call. Each invocation creates a new Appium session (~10-50s on iOS). Chaining operations runs them all in one session, making subsequent operations nearly instant.

Debug: Explore App Structure

# List all buttons
python .github/skills/appium-automation/scripts/automate.py \
  --platform ios --app-id com.example.app \
  --list-buttons

# Full element tree
python .github/skills/appium-automation/scripts/automate.py \
  --platform ios --app-id com.example.app \
  --page-source > elements.xml

Python API

from appium_agent import AppiumAgent

# iOS
with AppiumAgent(platform="ios", app_id="com.microsoft.maui.sandbox") as agent:
    agent.tap("NavigateButton")
    agent.type_text("SearchField", "hello world")
    agent.wait(1)
    result = agent.get_text("ResultLabel")
    agent.screenshot("result.png")

# Android
with AppiumAgent(platform="android", app_id="com.microsoft.maui.sandbox") as agent:
    agent.tap("SubmitButton")
    agent.swipe("up")
    buttons = agent.list_buttons()

# Mac Catalyst
with AppiumAgent(platform="maccatalyst", app_id="com.example.macapp") as agent:
    agent.tap_button("Preferences")

.NET MAUI Element Identification

In .NET MAUI, use AutomationId for element identification:

<Button Text="Submit" AutomationId="SubmitButton" />
<Entry Placeholder="Email" AutomationId="EmailField" />
<Label x:Name="resultLabel" AutomationId="ResultLabel" />

The agent finds elements by:

1. AutomationId (accessibility ID)
2. x:Name (name attribute)
3. Visible text (label/text attribute)

Troubleshooting

"No booted iOS simulator found"

xcrun simctl boot "iPhone 16 Pro"
# or
python automate.py --boot-simulator "iPhone 16 Pro"

"No Android device/emulator found"

# Start emulator
emulator -avd <avd_name> &

# Or check connected devices
adb devices

"Appium server not running"

appium --relaxed-security &
# or
python automate.py --start-appium

Element not found

1. Use --list-buttons to see available buttons
2. Use --list-elements to see all elements with IDs
3. Use --page-source to get full XML tree
4. Verify AutomationId is set in XAML

Android "Fast Deployment" crash

Symptom: App crashes immediately on launch with error:

No assemblies found in '.../__override__/arm64-v8a' or '<unavailable>'. 
Assuming this is part of Fast Deployment. Exiting...

Cause: Debug builds use "Fast Deployment" which doesn't embed assemblies in the APK. The assemblies are pushed separately by Visual Studio/dotnet tooling. When launched via Appium (outside VS), the app can't find the assemblies.

Fix: Build with embedded assemblies:

dotnet build -f net9.0-android -p:EmbedAssembliesIntoApk=true

Or use a Release build which embeds assemblies by default.

Note: The agent already sets appium:noReset=true by default to preserve app state between sessions.

Slow performance / Session startup

Symptom: Each CLI call takes 10-50 seconds on iOS.

Cause: Each CLI invocation creates a new Appium/WebDriverAgent session. Session startup is slow, especially on iOS (~10-50s).

Fix 1: Use session caching with --keep-session and --reuse-session:

# First call creates session and keeps it alive (~10s)
python automate.py --platform ios --app-id com.example --keep-session --tap Field1

# Subsequent calls reuse the session (~2s each!)
python automate.py --platform ios --app-id com.example --reuse-session --keep-session --type Field1 "text"
python automate.py --platform ios --app-id com.example --reuse-session --keep-session --list-elements

# When done, end the session
python automate.py --end-session

Fix 2: Chain multiple operations in a single CLI call:

# 1 session for all operations - executed IN ORDER specified!
python automate.py --platform ios --app-id com.example \
  --tap Field1 --type Field1 "text" --get-text Result --expect Result "success"

Note: Actions are executed in the order you specify on the command line. You can interleave actions as needed:

# Type, check value, type more, check again
--type Amount 100 --get-text Total --type Tip 20 --expect Total "€ 120"

Assertions

The --expect action is used for automated testing. It checks if an element contains expected text:

# Pass: exits 0
python automate.py --platform ios --app-id com.example --expect Label "expected text"

# Fail: prints failure and exits 1
python automate.py --platform ios --app-id com.example --expect Label "wrong"
# Output: ✗ expect 'Label' contains 'wrong': FAIL (actual: expected text)

Use --expect in test scripts to verify UI state after actions:

python automate.py --platform ios --app-id com.example \
  --type SubtotalEntry 100 \
  --set-slider TipSlider 20 \
  --expect TipAmountValue "€ 20,00" \
  --expect TotalValue "€ 120,00"

Platform Feature Matrix

Converted and distributed by TomeVault — claim your Tome and manage your conversions.