Skip to content

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 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

Clear the application local data explicitly for real devices

There might be a situation where application data is present on the real device although application itself is not installed. This could happen if: - The app is in offload state - The application state is cached - There was an unexpected failure while installing the app. An example of such failure is the ApplicationVerificationFailed which happens while installing an app signed with an invalid provisioning profile.

Under the circumstances above the application identifier won't be listed in the mobile: listApps output neither deleted by mobile: isAppInstalled command. Setting appium:fullReset or appium:enforceAppInstall capabilities to true won't help to clear this data too.

The only way to completely get rid of the cached application data is to call the mobile: removeApp command with the appropriate bundle identifier.

The driver automatically tries to resolve application installs that failed because of MismatchedApplicationIdentifierEntitlement, although, if you explicitly ask it to not perform the application uninstall then consider calling mobile: removeApp beforehand MismatchedApplicationIdentifierEntitlement error occurs only when the previously installed application's provisioning profile is different from what currently the driver is trying to install.

Below are example steps of the manual approach mentioned above:

  1. Start a session without appium:app and appium:bundleId
  2. Call mobile: removeApp for the target application's bundle id
  3. Install the test target with mobile: installApp
  4. Launch the application with mobile: launchApp or mobile: activateApp

Weird state

stop responding

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

Get a response after 60+ seconds after a session starts frequently

Did you experience an additional 60 seconds of slow command response that usually should not take long?

It might be that the testmanagerd process on the device under test has crashed. In such case, the OS tries to restore it causing the above delay while waiting for the resurrected daemon is connecting to the target process. This can be fixed by terminating the target application process. For example, if this behavior occurs in mobile: queryAppState command call, you could terminate the application once, or restart the device entirely.

Please check WebDriverAgent#774 pull request for more details.

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:

$HOME/Library/Logs/CoreSimulator/*
$HOME/Library/Developer/Xcode/DerivedData/*