Setting up a Real iOS Device

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

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 the 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 the Appium Inspector, refer to the steps described in 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

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.
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.
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.
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.
App Signing in Xcode

Configure code signing in Xcode to use your developer certificate and provisioning profile.
Open the WebDriverAgent project in Xcode. Configure code signing settings to use the developer certificate and provisioning profile created earlier.
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 > Applications > Search > WebDriverAgent.
  
  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 the following error messages are expected:
  
  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.
```
"Failed to register bundle identifier"
"No profiles found for 'com.facebook.WebDriverAgentRunner' were found
```
Perform Clean Build process. Note that this is a one-time job.

In the WebDriverAgent window, navigate to Window menu and select Clean Build Folder.
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 the 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 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.

Download the required Python packages from the Python website.

Run the following command in the terminal to install the Python bindings for Appium-Python-Client and verify the configuration:

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

This adds the Python bin directory to your PATH so that Appium can interact with the iOS device.

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

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

Was this page helpful?