[Mobile] Set up iOS real devices

This article shows you how to set up a real device on a macOS machine. After setting up the device, you can test iOS applications with Katalon Studio.

Note:

• From version 9.1.0 onwards, Katalon Studio supports Appium 2 for mobile testing.
• iOS mobile testing is not supported in Windows or Linux.

1. Install Xcode

Install Xcode version 10.2 or newer. You can download Xcode from the Apple Developer website: Download Xcode.

Note:

• Xcode must support the current version of your macOS and iOS device. Check that your macOS and iOS device are compatible with Xcode in this document supported iOS environments in Katalon Studio and Apple Developer document System requirements.

2. Install Appium, Xcode command-line tools, and other iOS dependencies

Install with built-in tools

You can install Appium, Xcode command-line tools (Xcode CLT), Homebrew, NodeJS, and other iOS dependencies with Katalon Studio built-in tools.

1. Go to Tools > Set up iOS environment and select Install Dependencies.
   
2. Katalon Studio will automatically install the latest version of Xcode CLT, Appium, Homebrew, NodeJS, and other iOS dependencies.
   

Install manually

1. Install Xcode command-line tools. You can download the command-line tools compatible with your Xcode version from the Apple Developer website here: Download.
   Alternatively, you can run the following commands in this order in the Terminal:

   xcode-select --install

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

2. Download and install Node.js from the Node.js website: Node.js Downloads.
   Make sure you install Node.js into a location where you have full Read/Write permissions.
3. Install Appium with the following commands in the Terminal:
   • For Katalon Studio 9.1.0 onwards, install the latest Appium version:

     npm install -g appium

   • For Katalon Studio before 9.1.0, install Appium 1.12.1+:

     npm install -g appium@version

   Note:

   • If you are using emulators other than Xcode simulators, some emulators come with Appium installed. If you want to run an application on an emulator, check your emulator settings before installing Appium.
4. Install Homebrew. Homebrew is a package manager that makes it easy to install extra dependencies. To install Homebrew, follow the instructions on the Homebrew website: Homebrew.
5. After installing Homebrew, you can now install the following dependencies in the Terminal:
   1. For 9.1.0 onwards:
      • Install Appium XCUITest driver version 4.32.24 or newer:

        appium driver install xcuitest

      • Install libimobiledevice with the following command:

        brew install libimobiledevice

   2. For versions before 9.1.0:

      • For Appium versions older than 1.20.0, you need to install Carthage. You can learn more about Carthage in this Github project: Carthage. To install Carthage via Homebrew, copy and paste the following command:

        brew install carthage

      • ios-deploy version 1.9.4 or newer. You can learn more about ios-deploy in this Github project: ios-deploy. To install ios-deploy, run the following command:

        brew install ios-deploy

      • Install libimobiledevice version 1.2.0 or newer with the following commands in the given order:

        brew tap kozyrap/libimobiledevice; (brew install --HEAD kozyrap/libimobiledevice/libimobiledevice || arch -arm64 brew install kozyrap/libimobiledevice/libimobiledevice) && brew unlink libimobiledevice && brew link libimobiledevice

      • For Appium versions older than 1.15.0, you also need to install ios-webkit-debug-proxy. You can learn more about ios-webkit-debug-proxy in this Github project: ios-webkit-debug-proxy. To install ios-webkit-debug-proxy, run the following command:

        brew install ios-webkit-debug-proxy

3. Set up the real iOS device

Important:

• You have enrolled in the Apple Developer Program. To learn more about the Apple Developer Program enrollment, refer to this Apple document: Enrollment.

1. Register your device for development with Xcode in Apple Developer. To learn about registering your device in Apple Developer, refer to this Apple document: Register a single device in Apple Developer.
2. In Xcode > Preferences > Account, click Add (+) to enter your Apple Developer Account ID and password.
3. Connect your iOS devices to your computer via a USB cable. Confirm to accept or trust the phone.
4. To enable UI Automation on the iOS device, navigate to Settings > Developer. In the UI Automation section, turn on Enable UI Automation.
5. If you want to execute mobile browser tests (Safari on iOS), you will need to enable the following settings in Settings > Safari > Advanced:
   • JavaScript
   • Web Inspector
   • Remote Automation

   

4. Install the WebDriverAgent

The WebDriverAgent is a WebDriver server used to control iOS devices remotely. For detailed instruction on WebDriverAgent installation, refer to Install WebDriverAgent for iOS devices.

5. Distribute your app to registered devices

To distribute your app for testing to registered devices, you need to archive and export an .ipa file. Do as follows:

Prepare your app for distribution

1. Open the project file with Xcode. For example, to open Coffee Timer.xcodeproj, go to your project folder > App > Your-First-iOS-App > Coffee Timer. Double-click the Coffee Timer.xcodeproj file.
   
2. After opening the project in Xcode, select a registered iOS device to launch the apps.
   
3. In the General tab, set deployment iOS version and select device type in the Deployment Info section.
   
4. Switch to the Signing & Capabilities tab, check the Automatically manage signing box, then choose the team that has your device registered in the Apple Developer Portal.

   By choosing the Automatically manage signing box, Xcode manages code signing assets for you. To learn more about automatic signing, you can refer to this Apple document: Automatic signing.

   

5. To build the .ipa file, click Product > Build.

Create an archive of your app

To archive the .ipa file, click Product > Archive. If the archive builds successfully, it appears in the Archives organizer.

Note:

• You can't create an archive if you set the run destination to a simulator.

Export your app using an ad hoc or development provisioning profile

When you export the app, Xcode re-signs the app using the code signing assets that you choose. To learn more about the distribution method, you can refer to this Apple document: Distribution method.

1. To open the Archives organizer, choose Window > Organizer and click Archives.
2. Select the archive you want to export, then click Distribute App and follow the instructions to get the .ipa file. Here, we choose a development provisioning profile to export the Coffee Timer.ipa file.
   

Install the app on user devices

1. Open Xcode, then navigate to Window > Devices and Simulators.
2. Choose your device from the Devices list.
3. Click Add (+) to browse the .ipa file.
   
4. Once installed successfully, the application appears in the Installed Apps section.