Appium iOS Testing with XCUITest: Advanced Techniques and Troubleshooting

// wdio.ios.conf.js
export const config = {
  capabilities: [{
    platformName: "iOS",
    "appium:automationName": "XCUITest",
    "appium:deviceName": "iPhone 15",
    "appium:platformVersion": "17.2",
    "appium:app": "/path/to/MyApp.app",
    
    // WDA configuration
    "appium:wdaLaunchTimeout": 120000,       // Time to build and launch WDA
    "appium:wdaConnectionTimeout": 60000,    // Time to connect to WDA after launch
    "appium:wdaStartupRetries": 3,           // Retry if WDA fails to start
    "appium:wdaStartupRetryInterval": 20000, // Wait between retries
    
    // Session configuration
    "appium:newCommandTimeout": 90,          // Session expires after 90s idle
    "appium:simulatorStartupTimeout": 120000,
    
    // Reduce test flakiness
    "appium:usePrebuiltWDA": true,           // Skip rebuild if WDA already installed
    "appium:shouldUseSingletonTestManager": false,
    
    // App-specific
    "appium:bundleId": "com.example.myapp",
    "appium:noReset": false,  // Clean state per session
  }]
};

// By accessibility label (set via accessibilityLabel in Swift/ObjC)
await $("-ios predicate string:label == 'Sign In'");

// By accessibility identifier (most reliable)
await $("-ios predicate string:identifier == 'login-button'");

// By type
await $("-ios predicate string:type == 'XCUIElementTypeButton'");

// Combining conditions
await $("-ios predicate string:type == 'XCUIElementTypeTextField' AND placeholderValue == 'Email'");

// Partial match
await $("-ios predicate string:label CONTAINS[cd] 'sign'");  // case-insensitive

// Multiple values
await $("-ios predicate string:label IN {'Cancel', 'Close', 'Dismiss'}");

// Direct child
await $("**/XCUIElementTypeButton[`label == 'Submit'`]");

// At any depth
await $("**/XCUIElementTypeScrollView/**/XCUIElementTypeButton[`label == 'Next'`]");

// By index (1-based)
await $("**/XCUIElementTypeTable/XCUIElementTypeCell[3]");

// Last element
await $("**/XCUIElementTypeButton[-1]");

// Queries accessibility identifier — works on iOS and Android
await $("~submit-button");

// Scroll down within a scroll view
await driver.execute("mobile: scroll", {
  direction: "down",
  distance: 0.5  // 0.0 to 1.0, fraction of screen height
});

// Scroll to a specific element
await driver.execute("mobile: scroll", {
  direction: "down",
  predicateString: "label == 'Terms of Service'"
});

// Scroll within a specific element
const scrollView = await $("-ios predicate string:type == 'XCUIElementTypeScrollView'");
await driver.execute("mobile: scroll", {
  element: scrollView.elementId,
  direction: "down"
});

// Swipe left (for carousel/onboarding)
await driver.execute("mobile: swipe", {
  direction: "left"
});

// Swipe with velocity
await driver.execute("mobile: swipe", {
  direction: "up",
  velocity: 1500  // pixels per second
});

// Pinch to zoom out
await driver.execute("mobile: pinch", {
  scale: 0.5,    // 0.0 = zoom out, 1.0+ = zoom in
  velocity: 1.0
});

// Zoom in
await driver.execute("mobile: pinch", {
  scale: 2.0,
  velocity: 1.5
});

// Long press via touch action
await driver.execute("mobile: touchAndHold", {
  x: 200,
  y: 400,
  duration: 1.5  // seconds
});

// Long press on element
const element = await $("~my-element");
const { x, y } = await element.getLocation();
const { width, height } = await element.getSize();
await driver.execute("mobile: touchAndHold", {
  x: x + width / 2,
  y: y + height / 2,
  duration: 1.5
});

await driver.execute("mobile: dragFromToForDuration", {
  fromX: 100,
  fromY: 300,
  toX: 300,
  toY: 300,
  duration: 1.0
});

// Auto-accept all alerts
"appium:autoAcceptAlerts": true

// Auto-dismiss all alerts
"appium:autoDismissAlerts": true

async function handleAlert(action = "accept") {
  try {
    const alert = await driver.getAlertText();
    if (alert) {
      if (action === "accept") {
        await driver.acceptAlert();
      } else {
        await driver.dismissAlert();
      }
    }
  } catch (e) {
    // No alert present
  }
}

// Allow location permission
await $("~request-location-button").click();
await handleAlert("accept");  // Clicks "Allow" or "Allow While Using App"

// Enroll biometrics on simulator
await driver.execute("mobile: enrollBiometric", { isEnabled: true });

// Simulate successful Face ID match
await driver.execute("mobile: sendBiometricMatch", {
  type: "faceId",
  match: true
});

// Simulate failed Face ID
await driver.execute("mobile: sendBiometricMatch", {
  type: "faceId",
  match: false
});

// Test Face ID flow
it("should authenticate with Face ID", async () => {
  await driver.execute("mobile: enrollBiometric", { isEnabled: true });
  
  await $("~use-face-id-button").click();
  
  // Simulate successful recognition after short delay
  await driver.pause(1000);
  await driver.execute("mobile: sendBiometricMatch", { type: "faceId", match: true });
  
  await $("~authenticated-screen").waitForDisplayed({ timeout: 5000 });
});

it("all interactive elements have accessibility labels", async () => {
  const buttons = await $$("-ios predicate string:type == 'XCUIElementTypeButton'");
  
  for (const button of buttons) {
    const label = await button.getAttribute("label");
    const identifier = await button.getAttribute("name");
    
    // Buttons should have either label or identifier
    const hasAccessibility = (label && label.length > 0) || 
                            (identifier && identifier.length > 0);
    
    if (!hasAccessibility) {
      const location = await button.getLocation();
      console.warn(`Button at (${location.x}, ${location.y}) has no accessibility label`);
    }
    
    expect(hasAccessibility).toBeTruthy();
  }
});

it("text fields have placeholder or label", async () => {
  const textFields = await $$("-ios predicate string:type == 'XCUIElementTypeTextField'");
  
  for (const field of textFields) {
    const placeholder = await field.getAttribute("placeholderValue");
    const label = await field.getAttribute("label");
    expect(placeholder || label).toBeTruthy();
  }
});

const fs = require("fs");
const path = require("path");

async function takeScreenshot(name) {
  const screenshot = await driver.takeScreenshot();
  const filePath = path.join("screenshots", `${name}-${Date.now()}.png`);
  fs.writeFileSync(filePath, screenshot, "base64");
  return filePath;
}

it("login screen matches baseline", async () => {
  await LoginPage.waitForVisible();
  const screenshotPath = await takeScreenshot("login-screen");
  
  // Compare with baseline (using your preferred visual comparison library)
  // Example with pixelmatch or similar
  expect(screenshotPath).toMatchScreenshot("login-screen-baseline.png", {
    threshold: 0.01  // 1% pixel difference tolerance
  });
});

# Check Xcode command line tools
xcode-select --print-path
# Should be /Applications/Xcode.app/Contents/Developer

# Verify iOS simulator runtime
xcrun simctl list runtimes

# Manual WDA build test
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/WebDriverAgent
xcodebuild build-for-testing \
  -scheme WebDriverAgentRunner \
  -destination "platform=iOS Simulator,name=iPhone 15,OS=17.2"

lsof -i :8100  # Should be empty

"appium:simulatorStartupTimeout": 180000,
"appium:wdaLaunchTimeout": 180000,
"appium:wdaConnectionTimeout": 120000,

const element = await $("~my-element");
await element.waitForDisplayed({ timeout: 10000 });
await element.click();

// Scroll to element, then wait for it to be fully visible
await element.scrollIntoView();
await driver.pause(500);  // Brief pause for animation
await element.click();

# .github/workflows/ios-tests.yml
jobs:
  ios-tests:
    runs-on: macos-14  # Use latest macOS runner with Xcode 15+
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Select Xcode version
        run: sudo xcode-select -s /Applications/Xcode_15.2.app
      
      - name: List available simulators
        run: xcrun simctl list devices available
      
      - name: Boot simulator
        run: |
          xcrun simctl boot "iPhone 15" 2>/dev/null || true
          xcrun simctl list devices | grep "iPhone 15"
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - run: npm ci
      
      - name: Install Appium
        run: |
          npm install -g appium
          appium driver install xcuitest
      
      - name: Run tests
        run: npx wdio wdio.ios.conf.js
        env:
          APPIUM_DEVICE_NAME: "iPhone 15"
          APPIUM_PLATFORM_VERSION: "17.2"
      
      - name: Upload screenshots on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: ios-test-screenshots
          path: screenshots/