Appium Architecture & Appium - XCUITest Driver setup on Real iOS Device(Updated on 2nd June 2024 from United Kingdom)

Predominantly, smartphone users spend time on mobile applications. Thus developing a great mobile app experience is essential. To ensure our apps work seamlessly on both platform iOS and Android we need proper testing before releasing it in the respective app stores which are very critical.

To perform functional testing on mobiles apps we have mainly two testing technique:-

 

·      Testing to be done Non-Scripted by QA analyst (Human) - Testing does not use frameworks but may use guidelines, checklists, stringent processes to draft certain test cases.

·      Automation Testing which is done with the use of script, code, and automation tools (computer) by a tester. Automation testing uses frameworks like Data Drive, Keyword, Hybrid to accelerate the automation process.

Now, to perform automation testing we need certain tools to interact with the mobile applications and do testing for us, and here's come the picture of open-source tool Appium which we can use for both iOS and Android applications.

Before we dive into how Appium can setup for mac, we will explore what is Appium and how Appium works, mainly architecture.

 

What is Appium?

Appium is an open-source cross-platform automation testing tool. It provides seamless automation testing experience for a mobile application that runs on Android and iOS.

 

Now let’s dive into the Appium architecture.

Appium Architecture

 

 

If you’ve explored the above diagram then, getting a grasp of the architecture is going to be a breeze. To make it even easier, let me jot down the architecture in a pointwise manner:

• Appium is an HTTP server written using node.js 
• The client communicates to the server using a session, where key elements of the communication process are sent with the help JSON objects. Communication is handled by the mobile JSON Wire Protocol.
• The server differentiates between an iOS request and an Android request using the desiredCapabilites arguments which we usually send in our code. 

            for e.g. DesiredCapabilities caps = new DesiredCapabilities();

            caps.setCapability(platformName, "iOS"); 

• The Appium server then processes the request to the respective UI Automators as seen in the Appium architecture diagram above(UIAutomator for Android and UIAutomation(XCUI Test) for iOS).
• The UI Automator/XCUITest then processes the request and executes the command on a simulator/emulator/real device.
• The results of the test session are then communicated to the server and then back to the client system in terms of logs, using the mobile JSON Wire Protocol.

I am keeping the Appium architecture explanation in sort as the architecture diagram is clear enough to understand.

Below are some pictorial representation of architecture for both iOS and Android 

                                                                                                                                                                                    © https://www.edureka.co

Hope pictorial representation is sufficient enough to get an understanding of the architecture of  Appium. 

Appium comes in two different forms:-

1. Desktop Mode(Can be easily downloaded from http://appium.io )

2. Non-Desktop Mode(Handled through Terminal(mac) and cmd(Windows))

Desktop mode is usually useful for inspecting the elements of an app page. On 2nd June 2024 I updated my appium desktop version to v1.22.3

Now, The Non-Desktop mode is primary support for automating iOS apps is via the XCUITest driver. 

 

Hold on!!! At this point, you will think what is this crap XCUITest Driver😇😇

 

No problem I will cover this topic in a brief.

 

The XCUITest Driver for iOS

This driver leverages Apple's XCUITest libraries in order to facilitate the automation of your app. This access to XCUITest is mediated by the WebDriverAgent server. WebDriverAgent (also referred to as "WDA") is a project managed by Facebook, to which the Appium core team contributes heavily. WDA is a WebDriver-compatible server that runs in the context of an iOS simulator or device and exposes the XCUITest API. Appium's XCUITest driver manages WDA as a subprocess opaque to the Appium user, proxies commands to/from WDA, and provides a host of additional functionality.

Don't worry about WebDriverAgent, It is a WebDriver server implementation for iOS that can be used to remote control iOS devices. It allows you to launch & kill applications, tap & scroll views or confirm view presence on a screen. This makes it a perfect tool for application end-to-end testing or general-purpose device automation. It works by linking XCTest.framework and calling Apple's API to execute commands directly on a device. WebDriverAgent is developed and used at Facebook for end-to-end testing and is successfully adopted by Appium

 

 If you want to get more depth of WebDriverAgent server just click here for WebDriverAgent server.

 

This WDA will install on your iOS device(see below) or simulator when you hit your test command in Xcode after completing the Appium setup and exposes the XCUITest API.

I know you will find it more theoretical than practical till now but it will develop more clarity for setting up  XCUITest on the Real device. 

Real Device Setup

Automating a real device with XCUITest is considerably more complicated than Simulators, due to Apple's restrictions around running apps on real devices.  

Time has come for some practical part, we will learn how to install Appium with XCUITest on Mac OS in easy steps:

Installation of the non-GUI version of Appium is a 2 step process. The first step is to install Node.JS. The second step is to use Node.JS to install Appium.

Let’s have a look at each of these steps in detail.

Prerequisites

• We'll assume you have a Mac computer with macOS v13.6.4 (Ventura) and a real iOS device running on iOS v16.6.1 (the example will work on lower versions as well, just fix the version numbers accordingly)

Step 1 – Install Node.JS

You’ll need to use mac Terminal not only to install Node.js but also to use it with NPM.

Before you can install Node, you’ll need to install two other applications. Fortunately, once you’ve got these on your machine(Xcode), installing Node takes just a few minutes.

1.    Xcode - Apple’s Xcode development software is used to build Mac and iOS apps, but it also includes the tools you need to compile software for use on your Mac. Xcode is free and you can find it in the Apple App Store. The Xcode version 14.3.1 is used for setup.

You can find the DMGs or XIPs for Xcode and other development tools on https://developer.apple.com/download/more/ (requires Apple ID to login).

2.    Homebrew - Homebrew is a package manager for the Mac — it makes installing the most open-source software (like Node) as simple as writing -  brew install node but hold on we will do it once brew get install.

Ø  Install Brew if  not installed run below command in terminal

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

Run below command in your terminal to add Homebrew to you PATH

‘eval “$(/opt/homebrew/bin/brew shellenv)”’ >> /Users/loactionOfYourBashProfile/.bash_profile 

      Check  Latest installed version —> brew –v will give the version 4.x.x(Mine is 4.2.8)

You’ll see messages in the Terminal explaining what you need to do to complete the installation process.

Note: - When installing Node via the installer, you have to use the Sudo command to make sure it installs properly.

Sudo lets the installer place files in areas of your file system that are only accessible to administrators.

Ø  Uninstall brew if already installed run below command in terminal

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

Installation

Installing Node.js and NPM is pretty straightforward using Homebrew. Homebrew handles downloading, unpacking, and installing Node and NPM on your system. The whole process (after you have XCode and Homebrew installed) should only take you a few minutes.

              1.    Open the Terminal app and type -> brew install node@18 or install below link for particular version - https://nodejs.org/dist/v18.16.0/

Follow command to set path – 

If you need to have node@18 first in your PATH, run:

 echo 'export PATH="/opt/homebrew/opt/node@18/bin:$PATH"' >> /Users/c0278391/.bash_profile

 

vi .bash_profile > I to insert

 

For compilers to find node@18 you may need to set:

 export LDFLAGS="-L/opt/homebrew/opt/node@18/lib"

 export CPPFLAGS="-I/opt/homebrew/opt/node@18/include"

              2.    Sit back and wait. Homebrew downloads some files and installs them. And that’s it.

To make sure you have Node and NPM installed, run two simple commands to see what version of each is installed:

o To see if the Node is installed, type node -v in Terminal. This should print the version number  so you'll see something like this v18.16.0

o To see if NPM is installed, type npm -v in Terminal. This should print the version number so you'll see something like this v9.5.1

Ø  Set NPM default directory by typing below command in terminal.

o   Npm config get prefix  (will give /opt/homebrew)
o   If we do not get the expected output then.

    Npm config set prefix /opt/homebrew

 

Ø  Again check with get prefix command for npm default directory. 

 Ø  To change the ownership for a directory(not mandatory command, use if required)

Sudo chown –R $USER /opt/homebrew

Step 2 – Install Appium using Node.js

Appium 1.22.3

How can we install it?

· Remove any old installation:

npm uninstall -g Appium@(mention version installed)

And then install any version which is compatible:

npm install -g appium@1.22.3

Ø  To get path and version of installed appium 

• o   Check appium version-> appium –v  or appium - -version will give 1.22.3
• o   Which appium (will give the path)-->  ‘/opt/homebrew/bin/appium’

 

Ø  To uninstall appium from machine

o   Npm uninstall appium (if appium is installed locally)

o   Npm uninstall –g appium(if appium is installed globally)

Ø  External dependencies

In addition to the above modules mentioned, appium depends on libimobiledevice to do certain things. 

libimobiledevice – It’s a software library that talks the protocols to support iPhone, iPod Touch, iPad and Apple TV devices running iOS

For example, you can use the libimobiledevice tools to install or launch apps on iOS devices, view the system log of the iOS devices and more.

We can Install libimobiledevice with Homebrew

Type in Terminal:-

brew install libimobiledevice --HEAD # install from HEAD to get important updates

•  

Ø  There is also a dependency, made necessary by Facebook's WebDriverAgent, for the Carthage dependency manager. If you do not have Carthage on your system, it can also be installed with Homebrew

      o   brew install carthage

Ø  we also need to install ios-deploy

 o   npm install -g ios-deploy

Note: - If the above command doesn’t work type Sudo npm -g install ios-deploy --unsafe-perm=true

For real devices, we can use xcpretty to make Xcode output more reasonable. This can be installed by

o   sudo gem install xcpretty

WebDriverAgent configure

WebDriverAgent is get installed at the time of Appium installation.

Ø  Navigate to webdriveragent installed path in terminal by hitting below command:

cd /opt/homebrew/lib/node_modules/appium/node_modules/appium-webdriveragent

Ø  Hit the below command in terminal now:

Mkdir –p Resources/WebDriverAgent.bundle

 sh ./Scripts/bootstrap.sh –d 

Ø  Hit below path in Finder->Go->Go to Folder 

/opt/homebrew/lib/node_modules/appium/node_modules/appium-webdriveragent

This will open the finder window in you mac machine with folder structure

Double click the file “WebDriverAgent.xcodeproj “ and this will open in Xcode.

*Below is optional for certain system but not always required. Skip it if not required

Imp-> WebDriverAgent needs to be built with development team and provisioning profile installed on the device. You can construct an xcconfig file, the path to which is passed into the system using the xcodeConfigFile desired capability:

Steps to create a config file

Xcode -> File->New->File..->Choose Configuration Setting File Templete as shown in below image

Ø  In configuration create file Config.xcconfig and put below content:

DEVELOPMENT_TEAM = <Team ID>

CODE_SIGN_IDENTITY = iPhone Developer

In either case, the Team ID is a unique 10-character string generated by Apple that is assigned to your team. You can find your Team ID using your developer account (Sign in to developer.apple.com/account, and click Membership in the sidebar. Your Team ID appears in the Membership Information section under the team name. 

· Open WebDriverAgent.xcodeproj in Xcode. Select your development team for both the WebDriverAgentLib and WebDriverAgentRunner targets. This should be an auto select Signing Certificate. The outcome will look as shown below when WebDriverAgentLib Folder is selected.

Ø  Also, check Automatically manage signing for WebDriverAgentRunner folder.

Ø  Build WebDriverAgent once to verify all the above steps worked.

Ø  Now type below command in terminal

xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

e.g- xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=be0f042e88a3ac87fa157a25a1239b6cf0454d97' test

Alternatively, you can test you xcodebuild through Xcode by navigating to “Product” on top menu bar and select test – This will install WebdriverAgent app on device which will act like server which will control the iOS device as already discussed under the above topic “The XCUITest Driver for iOS”

Ø  Now move to default path in your terminal and type:

appium --automation-name XCUITest -U <udid> --ipa <Path of your ipa build(Make sure app name should be without space)> --platform-version <iOS version of device> --platform-name iOS -a <ip of your internet network or local ip> -p <Port>

E.g.

XXXXX:~ xxxx.yyyy$  -> appium --automation-name XCUITest -U be0f042e88a3ac87fa157a25a1239b6cf0454d97 --ipa /Users/xxxsuser/Desktop/BuildAdHoc.ipa --platform-version 13.5.1 -- platform-name iOS -a 10.1xx.2x.223 -p 4723

Configuring the app under test

Not only does WebDriverAgent need to be configured to run on your device, but your app must also be able to run on your device. The central requirements are the same: to have a build of your app (a .ipa file) signed with a development provisioning profile. 

In a little more detail, to get started on a real device, you will need the following:

• An Apple Developer ID and a valid Developer Account with a configured development certificate and provisioning profile.
• A valid iOS Development Certificate and Provisioning Profile are necessary to test on a real device. Your app will also need to be signed. You can find information about this in the Apple documentation.
• An iPad or iPhone. Make sure this has been set up for development in Xcode.
• A signed .app or .ipa file of your app, or the source code to build one.
• A Mac with Xcode and the Xcode Command Line Developer Tools.

Appium handles installing the application to the device, using ideviceinstaller (which is installed as part of libimobiledevice), but it is sometimes easier to pre-install your app using Xcode to ensure there are no problems.

This brings us to the end of this “Appium architecture and setup of Appium – XCUITest Driver for iOS real device.

 

Thanks!!