Setting up a Real iOS Device

Prerequisites

• iOS Developer Account: Ensure you have an Apple Developer account. If not, create one 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. This is 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 article.

  When setting up WebDriverAgent for Appium, the WebDriverAgent project is usually built and configured within Xcode. WebDriverAgent leverages Xcode's 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 can use your iPhone for testing, make sure the iPhone and Mac laptop are on the same network.

• Enable Developer Mode on iOS Device:

  • On your iOS device, go to Settings.
  • Navigate to General > About > Software Information.
  • Tap on the Build Number until you can enable the Developer Mode.
  • Enter your macOS machine passcode when prompted.

• Unlock Your iOS Device: Ensure your iOS device is unlocked and trusts the connected Mac. This step is crucial for successful communication between the device and 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 "Trust This Computer." Tap Trust to establish a connection.

  

• 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 the Appium Inspector, refer to the steps described in the Setting Up an iOS Simulator article.

    Add the desired capabilities by launching the Appium Inspector as shown in the code snippet and 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 Your iOS Device to 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, and Xcode should prompt you to add the device to your account. Follow the prompts to do so.

Configure the Device in Xcode

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 helps locate the WebDriverAgent project root, which is essential for configuring your real iOS device for testing.

Set Up the Project

Navigate to the previously identified WebDriverAgent project root location in your terminal. Execute the following command to set up the project:

mkdir -p Resources/WebDriverAgent.bundle

This command prepares the project by creating the necessary directory structure for WebDriverAgent.

Configure App Signing in Xcode

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

Code Sign WebDriverAgentLib and WebDriverAgentRunner

This step is crucial for ensuring 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. Automatically manage signing for WebDriverAgentLib: Navigate to Finder > Applications > Search > WebDriverAgent.

   Note that your username displays in the Team text box.

   The following screen appears:

   

3. Automatically manage signing for WebDriverAgentRunner: If Xcode fails to create a provisioning profile for the WebDriverAgentRunner target, then the following error messages are expected:

   

   To resolve these errors, navigate to the Build Settings tab and change the Product Bundle Identifier from com.facebook.WebDriverAgentRunner to com.SomeUniqueName.WebDriverAgentRunner.

   For example, you can change the Product Bundle Identifier to something like com.mycompany.WebDriverAgentRunner.

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

Perform a Clean Build

Note that this is a one-time job. In the WebDriverAgent window, go to the Window menu and select Clean Build Folder.

Build the WebDriverAgent Project

To build the WebDriverAgent project, connect your iPhone using a USB cable and copy the device identifier from Xcode.

Return to the General tab, and you should see that Xcode has created a provisioning profile for the WebDriverAgentRunner target.

Navigate to the WebDriverAgent project root where you have been working 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 issues, you need to trust the Developer App certificate for your account on your device as described in the prerequisite.

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

Troubleshoot Build Issues

If you are still encountering build failed errors, try the following command, which includes the -allowProvisioningUpdates flag. The addition of -allowProvisioningUpdates can help resolve certain provisioning issues during the build process.

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

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

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

Test the Configuration Using Appium Python Client

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

1. Download the required Python packages from the Python website.

   Run the following command in the terminal to set the Python path:

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

   Install the Appium-Python-Client:

   pip install Appium-Python-Client
   

   The installed packages include:

   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.1
   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.0
   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.2
   tomli 1.2.2
   trio 0.19.0
   trio-websocket 0.9.2
   urllib3 1.26.7
   wsproto 1.0.0
   xmltodict 0.12.0
   

2. Enter the desired capabilities in the Appium Inspector screen as described in the Adding the Required Capabilities section of the Setting Up an iOS Simulator article.