# Setting up the Environment for iOS Testing on Real Device

# Prerequisites

Follow the instructions for setting up an iOS testing environment.

# Install Required dependencies for real devices

Appium's iOS real device support depends on a third-party software suite called libimobiledevice. Run

brew install libimobiledevice --HEAD


If you get the error Requested 'libusbmuxd >= 1.1.0' but version of libusbmuxd is 1.0.10 while running a test, follow the steps below to update these dependencies.

brew update
brew uninstall --ignore-dependencies libimobiledevice
brew uninstall --ignore-dependencies usbmuxd
brew install --HEAD usbmuxd
brew unlink usbmuxd
brew link usbmuxd
brew install --HEAD libimobiledevice

The following dependencies are also required for Appium version below 1.15:

  1. ios-deploy brew install ios-deploy
  2. authorize-ios npm install -g authorize-ios
  3. ideviceinstaller brew install ideviceinstaller
  4. ios_webkit_debug_proxy brew install ios-webkit-debug-proxy


For Appium 1.15 or above, you do not need to install ios_webkit_debug_proxy.

# Prepare Signing Certificate and Provisioning Profile

Before your app can be installed on a device, it must be signed with a certificate issued by Apple. A provisioning profile is a collection of digital entities that uniquely ties developers and devices to an authorized iPhone Development Team and enables a device to be used for testing.

If you already have Development Signing Certificate and Provisioning Profile on your Mac, please ignore content below.

  • First, you'll need a paid iOS Development Account. If you don't have one, you can enroll here.

  • Once you have an iOS Development Account, add your iOS Development Account to Xcode.

    1. Open Xcode
    2. Go to Xcode -> Preferences...
    3. Click the Accounts tab
    4. Click the + button to add an account
    5. Select Apple ID as the account type and click Continue
    6. Enter your Apple ID and password
    7. Click Add. Your account should look like the picture below add-development-account
  • Now, use Xcode to generate a Development Signing Certificate

    1. Go to Xcode -> Preferences...
    2. Click the Accounts tab
    3. Select Account on the left side
    4. Select your Team then click Manage Certificates.... The Signing certificates dialog will open
    5. In the lower left hand corner of the signing certificates sheet, click the Add button +
    6. Choose Apple Development certificate from the pop-up menu
    7. Open Keychain Access (it's located in the Applications>utilities folder). Choose My Certificates and check for the certificate development-certificate
  • Finally, prepare Development Provisioning Profile by following these steps.

    1. Login to the iOS Provisioning Portal.
    2. Add your iOS test device to your Provisioning Profile.
    3. Create a Development Provisioning Profile.


You can share your Development Signing Certificate (.p12) and Development Provisioning Profile (.mobileprovision) by exporting them and then installing them on another Mac. The details can be found in the building WebDriverAgent section.

# Building WebDriverAgent

# Building with a local Certificate and Provisioning Profile

After preparing a Signing Certificate and a Provisioning Profile on your Mac, you can follow the full manual configuration guide on the Appium website to build WebDriverAgent.

# Build with shared Certificate and Provisioning Profile

On the other hand, if you want to share a Signing Certificate and Provisioning Profile to build WebDriverAgent on another Mac. Please follow the steps below.

  1. On your Mac, export your development signing certificate (example_Certificates.p12) and development provisioning profile (example_Provision.mobileprovision).

  2. On the target Mac, open "Keychain Access" (located in Applications/utilities). Choose "My Certificates" then drag & drop example_Certificates.p12 to import the certificate.

  3. Open the terminal and run the following command:

  • For Appium Desktop Users:
cd /Applications/Appium.app/Contents/Resources/app/node_modules/appium-webdriveragent

./Scripts/bootstrap.sh –d

mkdir -p Resources/WebDriverAgent.bundle
  • For Appium-Server Users (command line only) :
cd /usr/local/lib/node_modules/appium/node_modules/appium-webdriveragent

./Scripts/bootstrap.sh –d

mkdir -p Resources/WebDriverAgent.bundle
  1. Open WebDriverAgent.xcodeproj with Xcode. It's located in the folder ./appium-webdriveragent.

    • Select WebDriverAgent > WebDriverAgentRunner.
    • Deselect the Automatically manage signing checkbox.
    • Under provisioning profile > select the example_Provision.mobileprovision file that you prepared earlier.
    • On the menubar, select Product > build.


# Re-sign an Application Under Test

To install an unpublished application on your iOS test device, its provisioning profile must include the device's UDID. Sometimes, we need to replace the application's embedded profile (to add more devices or switch from distribution to development for testing Hybrid application) and we don't want to rebuild the app from its source. Here's how:

  1. Export your development provisioning profile to a location on your Mac.

  2. Get a <Signing Identity> by going to Applications/Utilities/Keychain Access and selecting My Certificates Signing Identity

  3. Run the following commands in the folder containing your AUT's ipa file ex: YourAUT.ipa

security cms -D -i path/to/YourProfile.mobileprovision > provision.plist

/usr/libexec/PlistBuddy -x -c 'Print :Entitlements' provision.plist > entitlements.plist

unzip YourAUT.ipa

rm -rf Payload/YourAUT.app/_CodeSignature/

cp path/to/YourProfile.mobileprovision Payload/YourAUT.app/embedded.mobileprovision 

codesign -f -s "<Signing Identity>" --entitlements entitlements.plist Payload/YourAUT.app

zip -qr YourAUT-resigned.ipa Payload/

# gondola.json

Here are the Appium desiredCapabilities for a real device. You'll need to modify them to match your project/device.

    // Lines removed for brevity
    "Appium": {
        // Lines removed for brevity
        "app": "<Full path to your app>",
        "desiredCapabilities": {
            "automationName": "XCUITest",
            "platformName": "iOS",
            "platformVersion": "13.1", // the real device's iOS version
            "deviceName": "iPhone 11 Pro Max", //the device name
            "udid": "<udid of real device>", //If there is only one real device attached, udid can be set to "auto". If a device is attached it will run on the device, if not, it will run on a simulator.
            // Lines removed for brevity
    // Lines removed for brevity

# Mobile Safari on a Real iOS Device

Before you can run your tests in Safari, you will need to enable the following Safari settings on your device (settings > safari > advanced)

  1. JavaScript
  2. Web Inspector
  3. Remote Automation

Safari Setting

Last Updated: 12/28/2020, 4:12:58 AM