Skip to content

Non-macOS Hosts

The XCUITest driver has limited support for Windows and Linux host machines.

The key constraint for such sessions is the lack of Xcode and its related utilities. This brings several limitations:

  • Only real devices are supported (simulators can only be run on macOS)
  • Real devices must be running iOS/tvOS 18 or later
  • Automatic device selection is not supported
  • The default xcodebuild-based WebDriverAgent (WDA) startup strategy is not supported

Prerequisites

Device communication on non-macOS hosts is provided by the appium-ios-remotexpc optional dependency. In most cases, it will be automatically installed along with the XCUITest driver. If installing manually, ensure you are using version 5.1.0 or later.

Once the package is installed, you should:

  • Set up its Windows/Linux-specific prerequisites
  • Create a RemoteXPC tunnel

Check the RemoteXPC Tunnels guide for further information.

Creating a Session

All Windows and Linux sessions must use several additional capabilities in order to avoid Xcode-related codepaths.

Since automatic device selection is not supported, it is always required to use the appium:udid and appium:platformVersion capabilities in order to explicitly specify the device under test. Furthermore, since it is not possible to build WDA without Xcode, one of the following approaches must be used:

Example Capability Sets

If using the pre-installed WDA approach:

{
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:platformVersion": "26.0",
  "appium:udid": "<device udid>",
  "appium:usePreinstalledWDA": true,
  "appium:updatedWDABundleId": "<updated bundle id>"
}

If using the externally managed WDA approach:

{
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:platformVersion": "26.0",
  "appium:udid": "<device udid>",
  "appium:webDriverAgentUrl": "http://<reachable ip address for the device>:8100"
}