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 to install Xcode, refer to this article Setup and Configure Appium on Mac operating system for iOS devices.
  
  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.
  
  

• 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 step 10.
  
  

  • If you have not installed Appium inspector, refer to the steps described in Setting up an iOS Simulator article.
    Add the desired capabilities by launching 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

1. Open Xcode and Add Device to Account:
   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.
      
      
2. Device Configuration in Xcode
   Perform the following:
   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.
      
      
3. Finding WebDriverAgent Project Root on the Local File System

   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.

   
   

4. Setting the Project

   Navigate to the previously identified “WebDriverAgent project root” location in your terminal. Afterward, 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.
   
   

5. App Signing in Xcode
6. Open your M-App project in Xcode. Configure code signing settings to use the developer certificate and provisioning profile created earlier.
   
   

7. Code Sign WebDriverAgentLib & 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. Signing capabilities both in  WebDriverAgentLib & WebDriverAgentRunner
      
      Automatically manage signing for WebDriverAgentLib
      
      Navigate to Finder > Application > Search > Web Driver Agent.
      Note that 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 following error messages are expected: 

      “Failed to register bundle identifier” “No profiles found for ‘com.facebook.WebDriverAgentRunner’ were found

      
      
      To resolve these errors, follow these steps:
      To change the bundle ID for the target manually, 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.
      
      
8. Perform  Clean Build  process. Note that this is a one time job.
   In the WebDriver Agent window, navigate to Windows option and select Clean Build Process.
   
   
   
9. Build the WebDriverAgent.xcodeproj
   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.
   • Now, execute the following commands 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.

     
     Expected Output:
     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 ope
     n "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, then you will see Build success message as follows: 
     
   • Troubleshooting 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 on “Always allow.” This step helps resolve provisioning issues.
     

     
     
     
   • If you are able to see the Automation running message for WebDriver Agent App on your real mobile device , then this indicates that the WebDriverAgentRunner has been successfully installed and is ready for further testing and configuration's..
     
     
10. Test the Configuration Using Appium Python Client
    Now that the WebDriverAgentRunner is successfully configured on your device. In this step, the Appium Python Client is used 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 commands in the terminal to install Python bindings for Appium-Python-Client

       pip install Appium-Python-Client 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.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

       
       Run the following command in the terminal to verify the configuration.
       export PATH=$PATH:/Users/apple/Library/Python/3.9/bin
       
       

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

    2. Enter the desired capabilities in the Appium inspector screen as described in this step 5 of the article Setting up an iOS Simulator.