appium-automation

name	appium-automation
description	Cross-platform mobile app automation using Appium. Supports iOS Simulator, Android Emulator, and Mac Catalyst. Use for UI testing, reproducing issues, and validating fixes on device.

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

Platform	AutomationId maps to
iOS	name attribute
Android	resource-id (e.g., com.app:id/SubtotalEntry)
Mac Catalyst	identifier attribute

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

Platform	Requirements
iOS	Xcode, booted iOS Simulator
Android	Android SDK, running emulator or connected device
Mac Catalyst	Xcode, app installed on Mac, WebDriverAgentMac built (see below)

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

Action	Description	Example
--tap ID	Tap element by AutomationId	--tap SubmitButton
--tap-button TEXT	Tap button by visible text	--tap-button "Sign In"
--tap-text TEXT	Tap any element with text	--tap-text "Welcome"
--tap-like PARTIAL	Tap element with partial ID match	--tap-like Submit
--double-tap ID	Double-tap element	--double-tap ImageView
--long-press ID	Long press element	--long-press ListItem
--type ID TEXT	Type into text field (clears first)	--type EmailField "[e-mail]"
--clear ID	Clear text from field	--clear SearchField
--get-text ID	Get element text content	--get-text ResultLabel
--exists ID	Check if element exists	--exists ErrorMessage
--is-enabled ID	Check if element is enabled	--is-enabled SubmitButton
--is-visible ID	Check if element is visible	--is-visible LoadingSpinner
--expect ID TEXT	Assert element contains text	--expect TotalLabel "€ 100"
--wait N	Wait N seconds	--wait 2
--wait-for ID	Wait for element to appear	--wait-for LoadingSpinner

Keyboard & Input

Action	Description	Example
--dismiss-keyboard	Dismiss on-screen keyboard	--dismiss-keyboard
--press-key KEY	Press key (Enter/Tab/Escape)	--press-key Enter

Alerts & Dialogs

Action	Description	Example
--accept-alert	Accept/tap OK on alert	--accept-alert
--dismiss-alert	Dismiss/cancel alert	--dismiss-alert
--get-alert	Get alert text	--get-alert

Sliders

Action	Description	Example
--set-slider ID PCT	Set slider to percentage (0-100)	--set-slider TipSlider 25
--drag ID X Y [SEC]	Drag element by offset	--drag Handle 100 0 0.5

Gestures

Gesture	Description	Example
--swipe DIR	Swipe up/down/left/right	--swipe up
--scroll DIR	Scroll screen in direction	--scroll down
--scroll-to ID	Scroll until element visible	--scroll-to BottomButton
--tap-coords X Y	Tap at coordinates	--tap-coords 100 200

App Lifecycle

Command	Description
--activate	Bring app to foreground
--terminate	Close/kill app
--install PATH	Install .app or .apk

Debug & Inspection

Command	Description
--screenshot PATH	Save screenshot
--page-source	Print XML element tree
--list-buttons	List all button labels
--list-elements	List all elements with IDs
--find-text TEXT	Find elements with text
--get-rect ID	Get element position/size

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 Note: The session server is now the default — subsequent CLI calls reuse the same Appium session (~0.3-1s each). You can still chain operations in a single call for atomic execution.

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: Creating a new Appium/WebDriverAgent session is slow (~10-50s on iOS).

Default behavior: The agent now uses a persistent session server that keeps the Appium driver alive between CLI calls. The first call takes ~15-20s (starts server + creates session), but subsequent calls complete in ~0.3-1s.

# First call: starts server + creates session (~15-20s)
python automate.py --platform ios --app-id com.example --tap Field1

# Subsequent calls: reuse session (~0.3-1s each!)
python automate.py --platform ios --app-id com.example --type Field1 "text"
python automate.py --platform ios --app-id com.example --list-elements
python automate.py --platform ios --app-id com.example --get-text Result

# Check server status
python automate.py --platform ios --app-id com.example --server-status

# Stop the server when done
python automate.py --platform ios --app-id com.example --server-stop

Session server details:

• Auto-starts on first CLI call (no manual setup needed)
• Auto-stops after 10 minutes of inactivity
• Each platform+app combo gets its own server on a unique port
• Use --no-server to bypass and connect directly (old behavior)
• Use --server-stop to explicitly stop a running server

Alternative: Chain multiple operations in a single CLI call:

# All operations in one session
python automate.py --platform ios --app-id com.example \
  --tap Field1 --type Field1 "text" --get-text Result --expect Result "success"

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

Feature	iOS	Android	Mac Catalyst
tap	✅	✅	✅
type_text	✅	✅	✅
swipe	✅	✅	✅
long_press	✅	✅	✅
double_tap	✅	✅	✅
set_slider	✅	✅	✅
expect	✅	✅	✅
dismiss_keyboard	✅	✅	❌
accept_alert	✅	✅	✅
press_back	❌	✅	❌
orientation	✅	✅	❌