iOS Testing with Appium: Complete Guide to Apple Device Automation

# Install command line tools
xcode-select --install
 
# Accept license agreement
sudo xcodebuild -license accept
 
# Verify installation
xcode-select -p
# Should output: /Applications/Xcode.app/Contents/Developer

# Install Appium
npm install -g appium
 
# Install the XCUITest driver
appium driver install xcuitest
 
# Verify the driver
appium driver list --installed

# For simulators, WDA builds automatically
# For real devices, you may need to configure signing
 
# Navigate to WDA project
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
 
# Open in Xcode to configure signing
open WebDriverAgent.xcodeproj

# Run Appium Doctor
npm install -g @appium/doctor
appium-doctor --ios
 
# Should show all checks passing

const capabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone 15 Pro',
  'appium:platformVersion': '17.0',
  'appium:app': '/path/to/MyApp.app',
};

# List available simulators
xcrun simctl list devices
 
# Boot a simulator
xcrun simctl boot "iPhone 15 Pro"
 
# Install app on simulator
xcrun simctl install booted /path/to/MyApp.app
 
# Uninstall app
xcrun simctl uninstall booted com.example.myapp
 
# Erase all content
xcrun simctl erase "iPhone 15 Pro"

# With device connected
xcrun xctrace list devices
# Or use: instruments -s devices

const capabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone',
  'appium:platformVersion': '17.0',
  'appium:udid': 'your-device-udid-here',
  'appium:app': '/path/to/MyApp.ipa',
  'appium:xcodeOrgId': 'YOUR_TEAM_ID',
  'appium:xcodeSigningId': 'iPhone Developer',
};

const capabilities = {
  // Platform settings
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:platformVersion': '17.0',
  'appium:deviceName': 'iPhone 15 Pro',
 
  // App settings
  'appium:app': '/path/to/app.app',  // .app for sim, .ipa for device
  'appium:bundleId': 'com.example.myapp', // Alternative to app path
 
  // Session behavior
  'appium:noReset': false,
  'appium:fullReset': false,
};

const capabilities = {
  // ... basic capabilities ...
 
  // Performance
  'appium:wdaLaunchTimeout': 120000,
  'appium:wdaConnectionTimeout': 240000,
  'appium:newCommandTimeout': 300,
 
  // WebDriverAgent
  'appium:useNewWDA': false,
  'appium:usePrebuiltWDA': true,
  'appium:webDriverAgentUrl': 'http://localhost:8100',
 
  // UI interaction
  'appium:waitForQuiescence': true,
  'appium:shouldUseSingletonTestManager': false,
 
  // Alerts
  'appium:autoAcceptAlerts': false,
  'appium:autoDismissAlerts': false,
 
  // Screenshot
  'appium:screenshotQuality': 2, // 0=low, 1=medium, 2=high
};

const capabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:browserName': 'Safari',
  'appium:deviceName': 'iPhone 15',
  'appium:platformVersion': '17.0',
};
 
// Then use like Selenium
await driver.url('https://example.com');

// Set in iOS code: element.accessibilityIdentifier = "login_button"
const element = await driver.$('~login_button');

// Match by label
await driver.$('-ios predicate string:label == "Login"');
 
// Match by type and label
await driver.$('-ios predicate string:type == "XCUIElementTypeButton" AND label CONTAINS "Submit"');
 
// Case-insensitive match
await driver.$('-ios predicate string:label CONTAINS[c] "login"');
 
// Match value
await driver.$('-ios predicate string:value BEGINSWITH "Hello"');
 
// Match name (accessibility identifier)
await driver.$('-ios predicate string:name == "username_field"');

// Direct child
await driver.$('-ios class chain:**/XCUIElementTypeButton[`label == "Login"`]');
 
// Multiple levels
await driver.$('-ios class chain:**/XCUIElementTypeCell/XCUIElementTypeTextField');
 
// Index-based selection
await driver.$('-ios class chain:**/XCUIElementTypeButton[2]'); // Second button
 
// Combining predicates
await driver.$('-ios class chain:**/XCUIElementTypeCell[`name BEGINSWITH "user"`]/XCUIElementTypeButton');

await driver.$('//XCUIElementTypeButton[@label="Login"]');
await driver.$('//XCUIElementTypeCell//XCUIElementTypeStaticText[@value="Welcome"]');

// Tap at coordinates
await driver.touchAction([
  { action: 'tap', x: 200, y: 400 }
]);
 
// Long press
await driver.touchAction([
  { action: 'longPress', element, duration: 2000 },
  { action: 'release' }
]);
 
// Swipe
await driver.touchAction([
  { action: 'press', x: 200, y: 500 },
  { action: 'wait', ms: 500 },
  { action: 'moveTo', x: 200, y: 100 },
  { action: 'release' }
]);
 
// Pinch/Zoom (using mobile: command)
await driver.execute('mobile: pinch', {
  scale: 0.5, // < 1 to zoom out, > 1 to zoom in
  velocity: 1.5
});

// Scroll until element is visible
await driver.execute('mobile: scroll', {
  strategy: 'accessibility id',
  selector: 'target_element',
  direction: 'down'
});
 
// Scroll by direction
await driver.execute('mobile: scroll', {
  direction: 'down'  // up, down, left, right
});
 
// Scroll to specific element
await driver.execute('mobile: scrollToElement', {
  element: await driver.$('~target').elementId,
  scrollViewElement: await driver.$('~scroll_view').elementId
});

// Get current orientation
const orientation = await driver.getOrientation();
console.log(orientation); // PORTRAIT or LANDSCAPE
 
// Set orientation
await driver.setOrientation('LANDSCAPE');
await driver.setOrientation('PORTRAIT');

// Activate Siri with a command
await driver.execute('mobile: siriCommand', {
  text: 'Open Calculator'
});

// Accept alert
await driver.acceptAlert();
 
// Dismiss alert
await driver.dismissAlert();
 
// Get alert text
const text = await driver.getAlertText();
 
// Set text in prompt
await driver.sendAlertText('Input text');
 
// Auto-handle alerts (in capabilities)
// 'appium:autoAcceptAlerts': true

async function handlePermissionAlert() {
  try {
    const alert = await driver.$('-ios class chain:**/XCUIElementTypeAlert');
    if (await alert.isDisplayed()) {
      const allowButton = await alert.$('~Allow');
      await allowButton.click();
    }
  } catch (e) {
    // No alert present
  }
}
 
// Or use capabilities
const capabilities = {
  // ... other caps
  'appium:autoAcceptAlerts': true, // Auto-tap Allow
};

// Check if keyboard is shown
const isKeyboardShown = await driver.isKeyboardShown();
 
// Hide keyboard
await driver.hideKeyboard();
 
// Hide keyboard with specific strategy
await driver.hideKeyboard('pressKey', 'Done');
await driver.hideKeyboard('pressKey', 'return');

// Send push notification (requires proper setup)
await driver.execute('mobile: pushNotification', {
  title: 'Test Notification',
  body: 'This is a test',
  bundleId: 'com.example.myapp'
});

// Enroll biometrics
await driver.execute('mobile: enrollBiometric', { isEnabled: true });
 
// Simulate successful authentication
await driver.execute('mobile: sendBiometricMatch', { type: 'faceId', match: true });
 
// Simulate failed authentication
await driver.execute('mobile: sendBiometricMatch', { type: 'faceId', match: false });

// Take screenshot
await driver.saveScreenshot('./screenshot.png');
 
// Start screen recording
await driver.startRecordingScreen();
 
// Stop and save recording
const video = await driver.stopRecordingScreen();
const fs = require('fs');
fs.writeFileSync('recording.mp4', Buffer.from(video, 'base64'));

// Get the element hierarchy
const source = await driver.getPageSource();
console.log(source);
 
// Save to file for analysis
fs.writeFileSync('page_source.xml', source);

const capabilities = {
  // Reuse existing WDA session
  'appium:usePrebuiltWDA': true,
  'appium:useNewWDA': false,
 
  // Use derived data path
  'appium:derivedDataPath': '/path/to/derived-data',
 
  // Skip app install if already present
  'appium:skipLogCapture': true,
};

const capabilities = {
  // Don't reset app state
  'appium:noReset': true,
 
  // Keep WDA running between sessions
  'appium:webDriverAgentUrl': 'http://localhost:8100',
  'appium:usePrebuiltWDA': true,
};

// Bad: XPath is slow on iOS
await driver.$('//XCUIElementTypeButton[@label="Login"]');
 
// Better: Accessibility ID
await driver.$('~login_button');
 
// Better: Predicate string
await driver.$('-ios predicate string:label == "Login"');

# Rebuild WDA
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'platform=iOS Simulator,name=iPhone 15' build
 
# Check for port conflicts
lsof -i :8100

// Add explicit wait
await driver.waitUntil(
  async () => (await driver.$('~element')).isDisplayed(),
  { timeout: 10000 }
);
 
// Scroll to element
await driver.execute('mobile: scroll', {
  strategy: 'accessibility id',
  selector: 'element',
  direction: 'down'
});