Open in app

Sign in

Write

Sign in

Comprehensive Guide to Manually Configuring Appium 2.1 for iOS 17.x on Real Devices

Yashwant Das (Yash)
10 min readNov 4, 2023

--

Welcome to our detailed guide for setting up Appium 2.1 on macOS Sonoma to test iOS apps on a real device running iOS 17.x. Whether you’re new to mobile app testing or have experience, this guide will help you configure Appium for your iOS testing needs. We’ll begin by making sure you have the right macOS and Xcode versions, resolving common issues, installing necessary drivers, and using Appium Inspector for testing.

Step 1: Verify Xcode and macOS Versions

First, ensure that you have the latest version of Xcode installed on your Mac. In my case, the macOS and Xcode versions were:

  • macOS: 14.1
  • Xcode: 15.0.1

Step 2: Install Appium

To install Appium globally on your system, use the following command:

npm i --location=global appium

2.1: Access Appium

After installing Appium, you can access it from the command line by running the following command:

appium

You should see some output that looks like this.

Step 3: Diagnose and Resolve Common Node and iOS Configuration Issues

In this step, we’ll diagnose and address common configuration issues with Appium. Follow these sub-steps:

3.1: Install Appium Doctor

Begin by installing appium-doctor with the following command:

npm install @appium/doctor --location=global

3.2: Run Appium Doctor for iOS

Now, run the following command to diagnose and check if necessary dependencies are installed:

appium-doctor --ios

If any essential dependencies are missing, follow the suggested recommendations to ensure you see the green checkmarks for all necessary dependencies.

Reference Links:

Step 4: Install Appium Driver

Since version 2.0, all drivers have been isolated from the Appium server app and can be managed independently using the appium driver command-line interface.

4.1: Install XCUITest Driver

To install the XCUITest driver, run the following command:

appium driver install xcuitest

This driver is specifically designed for iOS app automation.

Reference Link:

Step 5: Install Appium Inspector

Unlike older versions of Appium, the inspector functionality of Appium Desktop has been moved to its own app. In this step, we will install Appium Inspector for Appium 2.1.

5.1: Download and Install Appium Inspector

Download and install the latest version of Appium Inspector from the official page:

For your reference, you can use the following link for version 2023.10.1:

5.2: Launch Appium Inspector

Open the application from your Mac OS Launchpad.

If the app fails to launch, try the following:

  • Go to Mac OS Settings > Privacy & Security > Open Anyway.

Step 6: Verify Xcode Configurations

6.1: Ensure That You Are Logged in with an Apple Account

Before proceeding with the Xcode configurations, make sure you are logged in with your Apple Developer account. To check, follow these steps:

  • Open Xcode.
  • In the menu bar, go to Xcode > Preferences.
  • Under the “Accounts” tab, ensure that your Apple ID is listed, and it shows “Personal Team.”

This is a crucial step for code-signing your apps and WebDriverAgent.

6.2: Confirm xcrun simctl Configuration

In this step, we’ll confirm the xcrun simctl configuration. This is an essential component for managing Simulator runtimes and is crucial for the successful execution of Appium.

  • Open your terminal.
  • Run the following command:
xcrun simctl

This command is used to manage the Simulator and should display information about its usage. In most cases, you should see the expected output:

usage: simctl [--set <path>] [--profiles <path>] <subcommand> ...
       simctl help [subcommand]
Command line utility to control the Simulator

If you encounter an error, such as:

xcrun: error: unable to find utility "simctl", not a developer tool or in PATH

To fix this issue, follow these steps:

  • Open Xcode.
  • Go to Xcode settings > Locations.
  • Under the ‘Command Line Tools’ dropdown, select the appropriate Xcode version.
  • After selecting the right item from the dropdown, run the following command:
xcode-select -p
  • You should see the correct path:
/Applications/Xcode.app/Contents/Developer
  • If, by any chance, you get the wrong path like:
/Library/Developer/CommandLineTools

It indicates an incorrect configuration. Ensure that you select the correct Xcode version in the ‘Command Line Tools’ settings to resolve this issue.

6.3: Prepare iPhone for Development

Before you can use your iPhone for testing, follow these steps:

On your iPhone, enable Developer Mode in Settings > Privacy & Security. You may need to restart the device after that.

This ensures that your iPhone is recognized by Xcode and is ready for development and testing.

Step 7: Real Device Configuration

This step includes multiple subsections.

7.1: 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 expected output should be something like:

/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.

7.2: 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.

7.3: Code Sign WebDriverAgentLib & WebDriverAgentRunner

Open WebDriverAgent.xcodeproj in Xcode. For both the WebDriverAgentLib and WebDriverAgentRunner targets, select "Automatically manage signing" in the "General" tab, and then select your Development Team. This should also auto-select the Signing Certificate.

7.3.1: Automatically manage signing for WebDriverAgentLib

This step should proceed smoothly without any issues.

7.3.2: Automatically manage signing for WebDriverAgentRunner

Xcode may fail to create a provisioning profile for the WebDriverAgentRunner target.

Expected errors are:

“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, go to the ‘Build Settings’ tab and change the ‘Product Bundle Identifier’ from com.facebook.WebDriverAgentRunner to something like com.<SomeUniqueName>.WebDriverAgentRunner. For example, you can change the Product Bundle Identifier to something like com.mycompany.WebDriverAgentRunner.
  • Return to the ‘General’ tab, and you should see that Xcode has created a provisioning profile for the WebDriverAgentRunner target.

7.3.3: Taking note of updated WDABundleId

To ensure the correct configuration of the WebDriverAgent, take note of the updated WDABundleId. To do that, click on the info button next to Provisioning Profile-Xcode Managed Profile and copy the 10-digit number under the Certificate section.

7.4: Build the WebDriverAgent.xcodeproj

  • To build the WebDriverAgent project, connect your iPhone using a USB cable and copy the device identifier from Xcode.
  • 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 open "com.yashworks.WebDriverAgentRunner.xctrunner" failed....
  • If you encounter issues, you may need to trust the Developer App certificate for your account on your device.
  • Open Settings on the device and navigate to General -> VPN & Device Management, then select your Developer App certificate to trust it.

If you find the WebDriverAgentRunner app listed under the “Recently added” section on your device, you are on the right track. This indicates that the WebDriverAgentRunner has been successfully installed and is ready for further testing and configuration..

7.5: 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.

Great! Let’s move on to Step 8:

Step 8: Test the Configuration Using Appium Python Client

Now that we’ve successfully configured the WebDriverAgentRunner on your device, let’s put it to the test. In this step, we’ll use the Appium Python Client to verify our setup by opening Apple’s Settings app on your real iOS device.

8.1: Install Required Python Packages

Assuming you have Python installed on your Mac, you need to install the Python bindings for Appium-Python-Client and Selenium. Use the following commands to install them:

pip install Appium-Python-Client
pip install selenium

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

8.2: Write and Run Python Code

Now, let’s write Python code to open Apple’s Settings app on your real iOS device using Appium. Before running the code, make sure to update the following keys with the correct information for your device and account:

platformVersion: The iOS version on your device (e.g., 17.0).
uuid: The UDID (Unique Device Identifier) of your iPhone.
updatedWDABundleId: Use the data from Step 7.3.3 - "Taking note of updated WDABundleId."

Here’s a reference Python code snippet:

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",
    }
)
driver = webdriver.Remote(
    "http://127.0.0.1:4723",
    options=options,
)

8.3: Run the Test Script

  • Start Appium by running the following command in your terminal:
appium
  • Ensure Appium is running at http://127.0.0.1:4723.
  • In Visual Studio Code or your preferred Python development environment, run the test script you created in Step 8.2.

If everything is configured correctly, the Apple Settings app should open on your real device.

If something goes wrong, double-check the configuration steps and verify that the Developer App certificate for your account is trusted on your device.

Let’s move on to Step 9 (Optional)

Step 9: Test the Configuration Using Appium Inspector on a Real Device (Optional)

In this step, we’ll will use Appium Inspector to interact with your real iOS device.

9.1: Launch Appium and Appium Inspector

In this part of the process, we’re launching both Appium and the Appium Inspector app. Follow these steps to get everything up and running:

  • Open your terminal and start Appium with the following command:
appium
  • Ensure that Appium is running correctly at http://127.0.0.1:4723.
  • Now, it’s time to launch Appium Inspector. If you’ve previously installed Appium Inspector, you can locate it in your Mac OS Launchpad. However, if you haven’t installed it yet, you can refer to the instructions in Step 5 to download and install Appium Inspector

9.2: Set Up Appium Inspector for Real Device Testing

Once Appium Inspector is launched, you’ll need to set up the desired capabilities to run tests on your real iOS device. Follow these steps:

  • In Appium Inspector, click on “Edit Configurations.”
  • In the “Desired Capabilities” section, configure the following capabilities:
platformName: iOS
appium:platformVersion: The iOS version on your device (e.g., 17.0).
appium:automationName: XCUITest
appium:xcodeSigningId: iPhone Developer
appium:bundleId: The bundle identifier of the app you want to test. e.g. "com.apple.Preferences"
appium:udid: The UDID (Unique Device Identifier) of your iPhone.

Here’s a handy JSON configuration for Appium Inspector:

You can easily copy and paste this JSON into Appium Inspector’s desired capabilities section and customize it to fit your testing requirements.

{
  "platformName": "iOS",
  "appium:platformVersion": "17.0.3",
  "appium:automationName": "XCUITest",
  "appium:xcodeSigningId": "iPhone Developer",
  "appium:bundleId": "com.apple.Preferences",
  "appium:udid": "00009999-00000000001ANBYD"
}
  • Connect your real iOS device to your Mac if it’s not already connected.
  • In Appium Inspector, click the “Start Inspector Session” button.
  • Enter your iPhone password for “XCtest”
  • On the left, you can see the Appium Inspector View, and on the right, there’s a screen capture of my iPhone using Quicktime.

9.4: Troubleshooting

If you face any issues in this stage, consider the following troubleshooting actions:

  • Review Configuration Steps: Double-check your Xcode, WebDriverAgent, and Appium settings to ensure they are correctly configured.
  • Rebuild WebDriverAgent Project: If you encounter problems, rebuild the WebDriverAgent project to resolve potential issues.
  • Verify Developer App Certificate: Ensure that your Developer App certificate is trusted on your device.

That’s it! Your comprehensive guide to manually configuring Appium 2.1 for iOS 17.x on real devices is complete. Happy testing! 😘

Appium
IOS
Python
Xcode
Automation Testing

--

--

Yashwant Das (Yash)

Written by Yashwant Das (Yash)

41 Followers

To infinity and beyond!

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams