Troubleshooting
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 https://github.com/facebook/WebDriverAgent/issues/507 for more details.
- iPhone/iPad real devices show overlay, which has
Automation Running Hold both volume buttons to stoptext, 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.
- Please make sure your environment has Open SSL v1 for NodeJS environment, or prepare an OpenSSL v3 build by patching
shakeis 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 http://10.35.4.122:8100/session] 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: