[KShare] One-time setup for iOS Mobile testing Successes

Have you ever run into troubles whilst setting up Mobile testing environments, especially with the Apple’s iOS mobile operating system, such as:

  1. Cannot load the devices successfully (real devices or simulators/emulators)
  • We can try to unplug and plug in the real devices to make sure the devices can be recognized by the machines.

  • We may get unexpected issues regarding dependencies.

  1. Cannot start the application successfully.
  • We can try to run the application id com.apple.Preferences

  • If you are unable to successfully launch the above-mentioned application ID, then the problem is caused by Appium.

Appium and Dependencies are the most intricate issues that require proper solution. We at Katalon Product Support team has created a simple, 5-step guide for you to follow below. :point_down:

:pushpin: Please make sure that you that these steps followed thoroughly, precisely, and in the correct order.

The Guide

1. Uninstall the dependencies below (In the correct Order)

brew uninstall ios-webkit-debug-proxy
brew uninstall libimobiledevice
brew uninstall ios-deploy
brew uninstall carthage
brew uninstall appium
brew uninstall node

2. Uninstall Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

Please follow the guide below on more information on how to uninstall Homebrew:

After uninstalling homebrew, you will notice the message below from the terminal

==> Homebrew uninstalled!
The following possible Homebrew files were not deleted:
You may wish to remove them yourself.

Now, we have to follow the message by removing the folder /opt/homebrew manually.

3. Uninstall NodeJS

There are several ways to install the NodeJS, such as homebrew, nvm, download and install it manually, and so on. Those ways lead to different paths and versions that you might have.

Katalon Studio will browse the NodeJS in your machines automatically. Thus, there may be some risks such as Katalon could not find correctly the nodeKS path or version to run if we install the NodeJS by ourself.

Let Katalon Studio install the NodeJS for you through the Tools → iOS → Install Dependencies

Now, If your NodeJS was installed by nvm, please refer to the steps below to uninstall it.

  • Determine which node you currently have

  • Remove the .nvm and .npm folders

  • Remove the node files manually which exist in the folder paths below

4. Remove all Homebrew and NodeJS Shell Configuration

User Home → Show hidden files → Open each file before via the text editor → Remove lines including information regarding homebrew, node, nvm → Save file.

Below are the list of files you need to open and check:


5. Install dependencies via Katalon Studio

It may take a long time during the first installation, please do not stop or abort it!

The dependencies will be installed in order accordingly to make sure all things works as expected.

Time to check if everything works as expected

1. Trigger the Record Mobile / Spy Mobile functions to check the loaded devices

If the simulators/emulators do not load properly, please leave a comment below. :point_down:

:information_source: If you are one of our enterprise user, you can also submit a support case with your enterprise accounts through the Support Portal for faster support.

2. Check your iOS version (Simulators/emulators/real devices)

  • If your iOS version is below 16, then you can use Appium 1 and 2.
  • If your iOS version is 16 or higher, then you can only use Appium 2.

You should also make sure that the versions of xCode and iOS devices are compatible with each other. Please refer to this article from Apple for more information: Xcode - Support - Apple Developer

3. Run with Appium 1

  • Downgrade appium versions from 2.x to 1.x, you can use the command below
npm install -g appium@1.x

4. Run with Appium 2

  • Run the command below via the terminal to install the xcuitest driver
appium driver install xcuitest

You can refer to the documentation Install Appium 2.x and execute mobile tests for more details.

  • Download the dev build below, which supports Appium 2 because Katalon hasn’t officially supported it yet.

Below are the appium builds that support iOS version 16 and xCode version 14


Below are the appium builds that support iOS version 17 and xCode version 15


You may need to run the command below to open the Katalon Studio from the Dev Builds above:

xattr -cr /Applications/Katalon\ Studio.app
  • Select Appium version 2.x (beta) option from the Project Settings → Execution → Mobile

5. Steps in Katalon Studio → Mobile Recorder

  • Run the application ID: com.apple.Preferences

If you encounter the below error message …

… then, access the Katalon Studio → Preferences → Katalon → Mobile , remove the appium path and click on the “Apply and Close “ button.


Finally, re-trigger the Mobile Recorder function, the appium path will be loaded automatically.

For real devices, we need to install WebDriverAgents by following the instructions below:

:information_source: Note: You should install it manually.

If you find this topic helpful, then go ahead and give us a heart :heart: ! Your feedback and support help us to deliver better and more insightful topics like this one in the future! :hugs:

:information_source: If you are one of our enterprise customers, then you can also submit a support ticket via the Support Portal for faster support from us!

To view more topics like this, simply navigate to the support tag.


Thank you Product Support team (@support.squad) for this insightful topic. And also a big shout-out to the two individuals below for your contribution to this topic:

Linh Nguyen Thong Tran
Linh Nguyen (@linh.nguyen) - Product Support Manager at Katalon Thong Tran (@thong.tran) - Senior Software Engineer at Katalon
Linh is the Product Support team Manager at Katalon. She spent many years working as an Automation Testing QA before joining Katalon Product Support as a technical support expert. Based on her experiences, she usually provides customers with highly applicable solutions. She now manages her team with a user-centric approach to guarantee customers greater success with Katalon Products. A passionate Katalon developer with a wealth of programming and testing expertise. Thong has been dedicated to providing exceptional enterprise support for the past five years, helping Katalon’s customers achieve their testing goals with ease.

Hello everyone,
I am excited to share with you KS version 9.1.0, which supports XCode 16 and iOS 17. It also supports both current versions of the appium, 1. x and 2. x.

You may check it out via Katalon Studio Free Download | Katalon and discuss the results with the community in this article.


Do you have an idea for a topic that you would like the Product Supoprt team to cover in their next KShare article? Then share them with us by simply fill in the form below :point_down: