Setting Up and Configuring for Mobile App automationSetting up a Real iOS Device

Setting up a Real iOS Device

Set up and configure a real iOS device for Appium-based mobile app automation testing.

Prerequisites

  • iOS Developer Account: Ensure that you have an Apple Developer account. If you do not have one, create it on the Apple Developer website.

  • Developer Certificate and Provisioning Profile: Create a developer certificate and provisioning profile for your iOS device on the Apple Developer portal. These are necessary for installing and running apps on a real device.

  • Install Xcode: Ensure that you have Xcode installed on your macOS machine. You can download it from the Mac App Store, or refer to the Setup and Configure Appium on Mac Operating System for iOS Devices.

    When setting up WebDriverAgent for Appium, you usually build and configure the WebDriverAgent project in Xcode.

    WebDriverAgent uses Xcode capabilities to deploy and run the WebDriverAgentRunner app on an iOS device.

    The Appium server communicates with WebDriverAgent using the WebDriver protocol, allowing it to interact with the UI elements of the iOS app.

  • Connect iOS Device: Use a USB cable to connect your iOS device to your macOS machine. Before you use your iPhone for testing, make sure that the iPhone and Mac are on the same network.

  • Enable Developer Mode on iOS Device:

    • On your iOS device, go to Settings.
    • Navigate to Privacy & Security > Developer Mode.
    • Turn on Developer Mode.
    • Restart your iOS device when prompted.

  • Unlock Your iOS Device: Ensure that your iOS device is unlocked and trusts the connected Mac. This step is crucial for successful communication between the device and the development environment.

  • Trust the Computer: When you connect your iOS device to your Mac for the first time, you might be prompted on the device to select “Trust This Computer.” Tap “Trust” to establish a connection.

    iOS VPN and Device Management screens showing Trust Apple Development dialog and WebDriverAgentRunner Verified

  • Download the required Python packages: Download the required Python packages from the Python website. You need to install the Python bindings for Appium-Python-Client. Follow the procedure described in the Test the Configuration Using Appium Python Client section.

    • If you have not installed Appium Inspector, refer to the steps in the Setting Up an iOS Simulator article.

      Add the desired capabilities by launching Appium Inspector as shown in the following code snippet, then start a session.

      from appium import webdriver
options = XCUITestOptions().load_capabilities({
    "platformName": "iOS",
    "platformVersion": "17.0.3",
    "automationName": "XCUITest",
    "xcodeSigningId": "iPhone Developer",
    "bundleId": "com.apple.Preferences",
    "udid": "00009999-00000000001ANBYD",
    "updatedWDABundleId": "UPXXXXXXX8",
})

Real Device Configuration

Add Device to Your Apple Account in Xcode

  1. Open Xcode on your Mac.
  2. Go to Xcode > Preferences > Accounts.
  3. Sign in with your Apple ID.
  4. Connect your iOS device. Xcode should prompt you to add the device to your account. Follow the prompts.

Configure the Device in Xcode

Perform the following steps:

  1. Open Xcode, go to the Window menu, and select Devices and Simulators.
  2. Add your connected iOS device to Xcode. Xcode prompts you to enable development on the device. Follow the prompts.

Find the WebDriverAgent Project Root

To find the WebDriverAgent project root, run the following command:

echo "$(dirname "$(find "$HOME/.appium" -name WebDriverAgent.xcodeproj)")"

The following output is displayed:

/Users/yourusername/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent

This command locates the WebDriverAgent project root, which you need to configure your real iOS device for testing.

Set Up the Project

Navigate to the WebDriverAgent project root in your terminal. Then, execute the following command to set up the project:

mkdir -p Resources/WebDriverAgent.bundle

This command prepares the project by creating the directory structure required by WebDriverAgent.

Configure App Signing in Xcode

Open the WebDriverAgent project in Xcode. Configure the code signing settings to use the developer certificate and provisioning profile created earlier.

Code Sign WebDriverAgentLib and WebDriverAgentRunner

This step ensures that WebDriverAgentLib is properly signed, allowing it to be deployed and run on an iOS device.

  1. Open WebDriverAgent.xcodeproj in Xcode.

    For both targets, select Automatically manage signing in the General tab and set up the development team. Manually update the bundle identifier if needed.

  2. Configure signing capabilities for WebDriverAgentLib and WebDriverAgentRunner.

    Navigate to Finder > Applications > Search > WebDriverAgent.

    Your username appears in the Team field.

    The following screen appears:

    Xcode Signing and Capabilities tab with Automatically manage signing checkbox and Bundle Identifier highlighted

  3. Automatically manage signing for WebDriverAgentLib.

    Select Automatically manage signing for the WebDriverAgentLib target and set up the development team.

  4. Automatically manage signing for WebDriverAgentRunner.

    If Xcode fails to create a provisioning profile for the WebDriverAgentRunner target, the following error messages appear:

    Xcode Signing and Capabilities panel for WebDriverAgentRunner showing bundle identifier errors

    To change the bundle ID manually, navigate to the Build Settings tab and change the Product Bundle Identifier from com.facebook.WebDriverAgentRunner to a unique value such as com.mycompany.WebDriverAgentRunner.

    Failed to register bundle identifier
No profiles found for 'com.facebook.WebDriverAgentRunner' were found

  5. Perform a clean build. This is a one-time step.

    In Xcode, go to the Product menu and select Clean Build Folder.

    Xcode Product menu open with Clean Build Folder option highlighted

  6. Build the WebDriverAgent.xcodeproj project.

    Connect your iPhone using a USB cable and copy the device identifier from Xcode.

    Return to the General tab. Xcode should have created a provisioning profile for the WebDriverAgentRunner target.

    Xcode device window for Algoshack11iphone showing Installed Apps: WebDriverAgentRunner-Runner and IntegrationApp

    • Navigate to the WebDriverAgent project root where you worked in the previous steps.

    • Execute the following command in your terminal:

      xcodebuild build-for-testing test-without-building -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<YOUR_DEVICE_UDID>'

      Replace YOUR_DEVICE_UDID with the actual UDID of your iOS device.

      If you encounter issues, you may see the following error:

      Testing failed: The request to open "com.yashworks.WebDriverAgentRunner.xctrunner" failed. WebDriverAgentRunner-Runner encountered an error (Failed to install or launch the test runner. (Underlying Error: The request to open "com.yashworks.WebDriverAgentRunner.xctrunner" failed.))

      If you encounter this issue, trust the Developer App certificate for your account on your device as described in the prerequisites.

      If the build is successful, you will see a Build Success message in the terminal.

Troubleshoot build issues

If the build still fails, try the following command with the -allowProvisioningUpdates flag:

xcodebuild build-for-testing test-without-building -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<YOUR_DEVICE_UDID>' -allowProvisioningUpdates

This flag helps resolve provisioning issues during the build process.

This command may prompt you to enter your system password and click Always Allow. This step helps resolve provisioning issues.

codesign keychain access dialog with password field and Allow, Deny, Always Allow buttons

If you see the Automation Running message for the WebDriverAgent app on your real mobile device, WebDriverAgentRunner has been successfully installed and is ready for further testing and configuration.

iOS App Library screen with Automation Running overlay and hold volume buttons to stop message

Test the Configuration Using Appium Python Client

Now that WebDriverAgentRunner is successfully configured on your device, verify the setup using the Appium Python Client by opening Apple's Settings app on your real iOS device.

  1. Download the required Python packages.

    Download the required Python packages from the Python website.

    Run the following command to install the Appium-Python-Client:

    pip install Appium-Python-Client

    Set the Python path with the following command:

    export PATH=$PATH:/Users/apple/Library/Python/3.9/bin

    The installation produces output similar to the following:

    allure-behave 2.9.43 allure-python

allure-behave 2.9.43
allure-python-commons 2.9.43
Appium-Python-Client 1.2.0
async-generator 1.10
atomicwrites 1.4.0
attrs 21.2.0
beautifulsoup4 4.11.1
behave 1.2.6
certifi 2021.10.8
cffi 1.15.0
colorama 0.4.4
cryptography 36.0.0
cycler 0.11.0
fonttools 4.28.2
h11 0.12.0
idna 3.3
imageio 2.13.0
iniconfig 1.1.1
kiwisolver 1.3.2
labelImg 1.8.3
lxml 4.9.1
matplotlib 3.5.0
networkx 2.6.3
numpy 1.21.2
opencv-python 4.5.3.56
outcome 1.1.0
packaging 21.3
parse 1.19.0
parse-type 0.5.2
Pillow 8.3.0
pip 20.2.3
pixelmatch 0.3.0
pluggy 0.13.1
py 1.11.0
pycparser 2.21
pyOpenSSL 21.0.0
pyparsing 3.0.6
PyQt5 5.15.7
PyQt5-Qt5 5.15.2
PyQt5-sip 12.11.0
pytest 6.2.4
python-dateutil 2.8.2
PyWavelets 1.2.3
PyYAML 5.4.1
scikit-image 0.16.2
scipy 1.7.1
selenium 3.141.0
setuptools 49.2.1
setuptools-scm 6.3.2
six 1.16.0
sniffio 1.2.0
sortedcontainers 2.4.0
soupsieve 2.3.2.post1
toml 0.10.0
tomli 1.2.0
trio 0.19.0
trio-websocket 0.9.0
urllib3 1.26.7
wsproto 1.0.0
xmltodict 0.12.0

    This installs the necessary Python packages for Appium to interact with the iOS device.

  2. Enter the desired capabilities.

    Enter the desired capabilities in Appium Inspector as described in the Setting Up an iOS Simulator article.

Was this page helpful?