Skip to content

Non-macOS Devices

The Safari driver supports automating Safari on iOS and iPadOS, on both simulators and real devices.

In addition to the standard driver configuration, iOS/iPadOS tests have further requirements:

  • iOS/iPadOS must be at version 13 or later
  • The platformName capability must be set to iOS
  • If testing on simulators, Xcode and the iOS Simulator runtime must be installed

  • If testing on real devices, automation-related settings must be enabled on each device:

    Settings -> Apps -> Safari -> Advanced -> Turn Web Inspector ON

    Settings -> Apps -> Safari -> Advanced -> Turn Remote Automation ON

Unlike the XCUITest driver, the WebDriverAgentRunner application and all of its related configuration are not required.

A simple capability set for a new iOS/iPadOS session can then look as follows:

// This will launch Safari on the first connected real iOS device
{
  "platformName": "ios",
  "appium:automationName": "safari"
}

It is recommended to use Safari-specific capabilities such as safari:useSimulator, safari:deviceName, safari:deviceUDID and others to specify the exact test device:

// This will launch Safari on the simulator named 'iPhone 17'
{
  "platformName": "ios",
  "appium:automationName": "safari",
  "safari:useSimulator": true,
  "safari:deviceName": "iPhone 17"
}

Known Limitations

Because safaridriver only automates web content and does not control native iOS UI or simulator settings, XCUITest-specific capabilities (such as appium:safariAllowPopups, appium:locationServicesEnabled, or appium:locationServicesAuthorized) have no effect in the Safari driver. To bypass native iOS system permission prompts (such as geolocation alerts) on iOS Simulators, grant the permission beforehand via xcrun simctl privacy <udid> grant location com.apple.mobilesafari, or use the XCUITest driver with browserName: 'Safari' when native alert or permission handling is needed.