Note: Issue tracking for this repo has been disabled. Please use the main Appium issue tracker instead.

• Setting geo location (appium/appium#6856)
• Auto accepting/dismissing alerts (appium/appium#6863)
• Touch Actions

• Unable to interact with elements on devices in Landscape mode (appium/appium#6994)
• shake is not implemented due to lack of support from Apple
• lock is not implemented due to lack of support from Apple
• Setting geo-location not supported due to lack of support from Apple
• Through multi action API, zoom works but pinch does not, due to Apple issue.

In addition to the git submodules mentioned below (see Development), this package currently depends on libimobiledevice to do certain things. Install it with Homebrew,

brew install libimobiledevice --HEAD  # install from HEAD to get important updates
brew install ideviceinstaller         # only works for ios 9. for ios 10, see below

There is also a dependency, made necessary by Facebook's WebDriverAgent, for the Carthage dependency manager. If you do not have Carthage on your system, it can also be installed with Homebrew

brew install carthage

ideviceinstaller doesn't work with iOS 10 yet. So we need to install ios-deploy

npm install -g ios-deploy

For real devices we can use xcpretty to make Xcode output more reasonable. This can be installed by

gem install xcpretty

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.

The appium-xcuitest-driver has provisional support for iOS real devices. Not all functionality is currently supported.

WebDriverAgent needs to be built with development team and provisioning profile installed on device. The easiest way to do this is to specify them as desired capabilities:

{
  "xcodeOrgId": "<Team ID>",
  "xcodeSigningId": "iPhone Developer"
}

Alternatively, you can construct an xcconfig file, the path to which is passed in to the system using the xcodeConfigFile desired capability:

DEVELOPMENT_TEAM = <Team ID>
CODE_SIGN_IDENTITY = iPhone Developer

In either case, the Team ID is a unique 10-character string generated by Apple that is assigned to your team. You can find your Team ID using your developer account (Sign in to developer.apple.com/account, and click Membership in the sidebar. Your Team ID appears in the Membership Information section under the team name. You can also find your team ID listed under the "Organizational Unit" field in your iPhone Developer certificate in your keychain).

Note that these are mutually exclusive strategies; use either the xcodeConfigFile capability or the combination of xcodeOrgId and xcodeSigningId.

Alternatively, the profile can be manually associated with the project (keep in mind that this will have to be done each time the WebDriverAgent is updated, and is not recommended):

• Open terminal go to node_modules/appium-xcuitest-driver/WebDriverAgent (this path is relative to your appium installation).

  mkdir -p Resources/WebDriverAgent.bundle
  sh ./Scripts/bootstrap.sh -d
  

• Open WebDriverAgent.xcodeproj in Xcode. Select your development team for both the WebDriverAgentLib and WebDriverAgentRunner targets. This should also auto select Signing Ceritificate. The outcome should look as shown below.

  

• Build WebDriverAgent once to verify all above steps worked.

    xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test
  
  

  One of the last lines of build output from the above command should be something like Test Case '-[UITestingUITests testRunner]' started.. To completely verify, you can try accessing the WebDriverAgent server status (note: on a real device you will need to know the device url, and substitute it for localhost in the DEVICE_URL environment variable below):

    export DEVICE_URL='http://localhost:8100'
    export JSON_HEADER='-H "Content-Type: application/json;charset=UTF-8, accept: application/json"'
    curl -X GET $JSON_HEADER $DEVICE_URL/status
  

After many failures on real devices, there can be a state where the device will no longer accept connections. To possibly remedy this, set the useNewWDA capability to true.

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

On some systems there are Accessibility restrictions that make the WebDriverAgent system unable to run. 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.

Should be the same for Appium

Differences noted here

This project has git submodules!

Clone with the git clone --recursive flag. Or, after cloning normally run git submodule init and then git submodule update

The git diff --submodule flag is useful here. It can also be set as the default diff format: git config --global diff.submodule log

git config status.submodulesummary 1 is also useful.

npm run watch

npm test

There are also a number of environment variables that can be used when running the tests locally. These include:

• REAL_DEVICE - set to anything truthy, makes the tests use real device capabilities
• _FORCE_LOGS - set to 1 to get the log output, not just spec
• PLATFORM_VERSION - change the version to run the tests against (defaults to 9.3)
• XCCONFIG_FILE - specify where the xcode config file is for a real device run (if blank, and running a real device test, it will search for the first file in the root directory of the repo with the extension "xcconfig")
• UICATALOG_REAL_DEVICE - path to the real device build of UICatalog, in case the npm installed one is not built for real device

Updating FaceBook's WebDriverAgent is as simple as running updating the submodule and then committing the change:

git checkout -b <update-branch-name>
git submodule update --remote
git add WebDriverAgent
git commit -m "Updating upstream WebDriverAgent changes"

There is a chance that the update changed something critical, which will manifest itself as xcodebuild throwing errors. The easiest remedy is to delete the files, which are somewhere like /Users/isaac/Library/Developer/Xcode/DerivedData/WebDriverAgent-eoyoecqmiqfeodgstkwbxkfyagll. This is also necessary when switching SDKs (e.g., moving from Xcode 7.3 to 8).