Skip to content


Known problems

  • After many failures on real devices it could transition to a state where connections are no longer being accepted. To possibly remedy this issue reboot the device. Read for more details.
  • iPhone/iPad real devices show overlay, which has Automation Running Hold both volume buttons to stop text, since iOS/iPadOS 15. This is a known limitation of XCTest framework. This limitation does not affect screenshooting APIs though (e.g. the overlay is not visible on taken screenshots).
  • iPhone/iPad real devices require passcode or touch id when they start a XCTest session since iOS/iPadOS 15. Disabling passcode/touch id in the device preference allows to workaround the behaviour above.
  • OpenSSL v3 breaks secure communication with real devices. It can cause a Failed to receive any data within the timeout error in appium-ios-device. Please read this issue for more details.
    • Please make sure your environment has Open SSL v1 for NodeJS environment, or prepare an OpenSSL v3 build by patching OPENSSL_TLS_SECURITY_LEVEL=1. (e.g. an article)
    • This configuration is only necessary for XCUITest driver v4.3.0 or lower.
  • shake is implemented via AppleScript and works only on Simulator due to lack of support from Apple

Weird state

Note: Running WebDriverAgent tests on a real device is particularly flakey. If things stop responding, the only recourse is, most often, to restart the device. Logs in the form of the following may start to occur:

info JSONWP Proxy Proxying [POST /session] to [POST] with body: {"desiredCapabilities":{"ap..."
dbug WebDriverAgent Device: Jul 26 13:20:42 iamPhone XCTRunner[240] <Warning>: Listening on USB
dbug WebDriverAgent Device: Jul 26 13:21:42 iamPhone XCTRunner[240] <Warning>: Enqueue Failure: UI Testing Failure - Unable to update application state promptly. <unknown> 0 1
dbug WebDriverAgent Device: Jul 26 13:21:57 iamPhone XCTRunner[240] <Warning>: Enqueue Failure: UI Testing Failure - Failed to get screenshot within 15s <unknown> 0 1
dbug WebDriverAgent Device: Jul 26 13:22:57 iamPhone XCTRunner[240] <Warning>: Enqueue Failure: UI Testing Failure - App state of (null) is still unknown <unknown> 0 1

Real device security settings

On some systems, especially CI ones, where tests are executed by a command line agents, macOS Accessibility restrictions make the WebDriverAgent system unable to retrieve the development keys from the system keychain. This is usually manifest by xcodebuild returning an error code 65. A workaround for this is to use a private key that is not stored on the system keychain. See this issue and this Stack Exchange post.

To export the key, use

security create-keychain -p [keychain_password] MyKeychain.keychain
security import MyPrivateKey.p12 -t agg -k MyKeychain.keychain -P [p12_Password] -A

where MyPrivateKey.p12 is the private development key exported from the system keychain.

The full path to the keychain can then be sent to the Appium system using the keychainPath desired capability, and the password sent through the keychainPassword capability.

Simulator Resetting

By default, this driver will create a new iOS simulator and run tests on it, deleting the simulator afterward.

If you specify a specific simulator using the udid capability, this driver will boot the specified simulator and shut it down afterwards.

If a udid is provided and the simulator is already running, this driver will leave it running after the test run.

In short, this driver tries to leave things as it found them.

You can use the noReset capability to adjust this behavior. Setting noReset to true will leave the simulator running at the end of a test session.

Delete files generated by test runs to avoid possible caching issue

Testing on iOS generates files that can sometimes get large. These include logs, temporary files, and derived data from Xcode runs. Generally the following locations are where they are found, should they need to be deleted: