Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Capabilities and Sessions

XCUITest Capabilities for iOS

Configure iOS sessions with the XCUITest driver: app vs bundleId, simulator and real device capabilities, WebDriverAgent options, permissions and common startup fixes.

iOS sessions use the XCUITest driver. The ideas mirror Android: say what to launch, which device to use, how to reset, and how long to wait. The details differ because iOS adds WebDriverAgent, code signing and the simulator-versus-device split. This lesson covers the capabilities you will use in almost every iOS test.

Capability names are shown with the appium: prefix. Always check the XCUITest driver documentation for the version you installed, since options are added over time.

The minimum

JSON
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "iPhone 16",
  "appium:platformVersion": "18.2",
  "appium:app": "/builds/Shop.app"
}
  • appium:platformVersion must match an installed simulator runtime. If it does not exist, the session fails with a "no devices" style message.
  • appium:deviceName is the model name for a simulator and mostly a label for a real device.
  • appium:app is a .app folder (or a zip of it) for a simulator, and a signed .ipa for a real device.

What to launch

  • appium:app: install from a file.
  • appium:bundleId: launch an already installed app by its bundle identifier, such as com.example.shop. Use it without app for pre-installed apps, or alongside app to be explicit.
  • Apple system apps have well-known bundle ids you can launch directly, for instance com.apple.Preferences (Settings) or com.apple.mobilesafari (Safari). This is a standard way to automate system screens.
  • For mobile web, set browserName to Safari rather than app or bundleId.

Which device

  • appium:udid: the exact device id. For simulators, the UDID from xcrun simctl list; for real devices, the device's own id. The special value auto picks a connected real device.
  • Without a udid, the driver looks for a simulator matching deviceName and platformVersion and may create or boot one.
  • appium:simulatorStartupTimeout: how long to wait for a simulator to boot, in milliseconds.
  • appium:isHeadless: start the simulator without showing its window, useful on CI.

Reset and permissions

Capability Effect
appium:noReset Keep app data and state between sessions
appium:fullReset Uninstall the app and, for simulators, erase it for a very clean start
appium:shouldTerminateApp Terminate the app when the session ends
appium:forceAppLaunch Launch the app even if it is running
appium:permissions JSON string granting or denying permissions for a simulator app, e.g. {"com.example.shop": {"notifications": "YES"}}
appium:autoAcceptAlerts Automatically press the accept button on system alerts
appium:autoDismissAlerts Automatically dismiss system alerts

Automatic alert handling is convenient but blunt: it answers every alert the same way. For flows where a permission dialog is the thing under test, leave it off and handle the alert in your test.

WebDriverAgent options

WDA is the helper that does the real work (Xcode, iOS Simulators and Real iPhones). Useful capabilities:

  • appium:wdaLaunchTimeout: how long to wait for WDA to start (ms). Raise it on slow machines.
  • appium:wdaConnectionTimeout: how long to wait for the first response (ms).
  • appium:wdaLocalPort: fix the local port that forwards to WDA. Essential when running several real devices in parallel so ports do not collide.
  • appium:usePrebuiltWDA: use an already built WDA instead of compiling, which saves a minute or more.
  • appium:derivedDataPath: where to keep the build output so it can be reused between sessions.
  • appium:useNewWDA: force a fresh WDA instead of reusing one.
  • appium:webDriverAgentUrl: connect to a WDA that is already running at a URL.

On first use, leave these alone. Optimize only when startup time becomes a problem.

Real device signing

JSON
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:udid": "00008110-001234567890801E",
  "appium:app": "/builds/Shop.ipa",
  "appium:xcodeOrgId": "ABCDE12345",
  "appium:xcodeSigningId": "iPhone Developer",
  "appium:updatedWDABundleId": "com.example.wda.runner"
}

xcodeOrgId is your Apple developer team id, xcodeSigningId the identity name (iPhone Developer works for development certificates), and updatedWDABundleId a bundle id you own for WDA, needed because the default one belongs to Appium and cannot be signed by you.

Locale, orientation and other conveniences

  • appium:language and appium:locale: start the simulator in a given language and region.
  • appium:orientation: PORTRAIT or LANDSCAPE.
  • appium:includeSafariInWebviews: include Safari's tabs in the list of web contexts.
  • appium:connectHardwareKeyboard: use the Mac's keyboard instead of the soft keyboard.
  • appium:autoWebview: start the session directly in the first web view context.

Validate an iOS capability set

The stand-in below encodes the rules in this lesson. It does not run the driver; it models the reasoning so you can see which combination triggers which advice.

JS Stand-in: iOS capability checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Parallel runs need distinct ports

If you run two iOS sessions at once, both would try to use the same local WDA port and the same derived data folder. The stand-in assigns unique values from a base, a pattern that is also used for Android (systemPort).

JS Stand-in: unique ports per parallel session

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common iOS startup problems

  • No devices match: the runtime in platformVersion is not installed, or the simulator name does not exist in this Xcode.
  • WDA build fails: open the WDA project in Xcode once, fix signing, or use a prebuilt WDA.
  • Session hangs at "launching WDA": raise wdaLaunchTimeout, free the port, or restart the simulator.
  • Alert blocks the app: handle it explicitly, or use the auto accept option for flows where all alerts mean "yes".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which capability launches an installed iOS app by its identifier?

    iOS apps are identified by a bundle id such as com.example.shop.
  2. 2. What does a simulator need as an app file?

    Simulator builds are .app bundles compiled for the simulator; device builds are signed IPAs.
  3. 3. Why set wdaLocalPort when running several real devices in parallel?

    Each parallel session needs its own local port mapped to its device's WDA.
  4. 4. What does usePrebuiltWDA do?

    Reusing a built WDA avoids the long xcodebuild step at each session start.

Summary

  • Launch with appium:app, appium:bundleId or, for web, browserName: Safari.
  • Simulators use .app builds and platformVersion must be an installed runtime; real devices use signed IPAs.
  • WDA options (wdaLaunchTimeout, usePrebuiltWDA, wdaLocalPort) control startup and parallelism.
  • Real devices need xcodeOrgId, xcodeSigningId and often updatedWDABundleId.
  • Auto alert handling is blunt; handle alerts explicitly when they are part of the test.

Next: Session Lifecycle and Timeouts