Execute mobile tests with Appium 2.x

Warning:

• Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. All recent versions of officially supported platform drivers are not compatible to Appium 1.x, and require Appium 2 to run.

• Katalon Studio added support for Appium 2 from version 9.1.0. If your team is migrating from Appium 1.x to Appium 2.x, read:

  • Migrate Katalon Studio from 8.x to 9.0.0

  • Migrating from Appium 1.x to 2.x

In Appium 2.x, one major change is the independence of drivers. This change separates tools and processes of building and using drivers for different platforms. With the ability to install and work with decoupled web drivers based on your application platform (iOS, Android, etc.), you can reduce your setup time and improve mobile testing performance in Katalon Studio.

This document guides you through configuration steps to execute mobile tests with Appium 2.x.

Requirements

• Katalon Studio version 9.1.0 onwards.
• Node.js 14+.
• Node Package Manager 8+ (NPM). This is usually bundled with Node.js, but you can upgrade independently.

Note:

We recommend downloading and installing Node.js from the official website instead of using package manager (e.g., brew or apk).

Install Appium 2.x and execute mobile tests

This section shows you how to install Appium 2x, install the required drivers for mobile execution in Katalon Studio, and execute tests using Appium 2.x.

1. Install Appium 2.x via NPM using the following command:

   npm i --location=global appium
2. Installing Appium 2.0 only installs the Appium server, but not the drivers since all drivers have been isolated from the Appium server app. Install the Appium XCUITest Driver for iOS and Appium UiAutomator2 Driver for Android.

   • The Appium XCUITest Driver, which is based on the Apple XCTest framework, is used for iOS native and web apps (via hybrid mode), and can only be used on macOS. To learn more about Appium XCUITest Driver, refer to the Appium repository on GitHub: appium-xcuitest-driver.

     Install Appium XCUITest driver version 4.32.24 or newer with the following command:

     appium driver install xcuitest

     Note:

     • If you are using Appium 2.0 and Xcode 14 to run mobile tests with physical iOS devices, you need to manually install WebDriverAgent. See the following article for more information: Build WebDriverAgent for real iOS devices with Appium 2.0 and Xcode 14.

   • The Appium UiAutomator2 Driver for Android native and web apps (via hybrid mode) is based on the Google UiAutomator framework. To learn more about Appium UiAutomator2 Driver, refer to the Appium repository on GitHub: appium-uiautomator2-driver.

     To install the latest versions of the Appium UiAutomator2 driver, run the following command:

     appium driver install uiautomator2
3. If you have both Appium 1 and Appium 2 on your machine, specify the Appium version to execute your test with. Go to Preferences > Katalon > Mobile > Appium Directory.
   Click Apply and Close.
4. Execute your mobile test.

After you executed your test in Katalon Studio, switch to the Console tab to check whether Katalon Studio detects the NodeJS location, starts Appium, and loads all drivers you installed as shown below:

In Log Viewer, the example below shows that Katalon Studio has successfully started the application with Appium version 2.x:

To learn more about execution logs in Katalon Studio, refer to the following document: View and customize execution log in Katalon Studio.

For troubleshooting, refer to the following document: Unable to Start Application on this device: Appium directory is invalid.

Build WebDriverAgent for real iOS devices with Appium 2.0 and Xcode 14

• You have installed Appium XCUITest Driver. See Install Appium 2.x and execute mobile tests.

If you are using Appium 2.0 and Xcode 14 to run mobile tests with real iOS devices, you need to manually install WebDriverAgent on Xcode.

1. Open Xcode. In Xcode > Preferences > Account, click Add (+) to enter your Apple Developer Account ID and password.
2. After installing the Appium XCUITest Driver, navigate to the WebDriverAgent folder in this directory: /Users/<username>/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
   Double-click on the WebDriverAgent.xcodeproj file in the selected folder to open it in Xcode.
3. Build the IntegrationApp target with the following steps:
   1. Select the IntegrationApp target. In the Signing & Capabilities section, check the Automatically manage signing box, then choose a team added in Step 1.
      
   2. On the menu bar, select Product > Build.
4. Build the WebDriverAgentLib target with the following steps:
   1. Select the WebDriverAgentLib target. In the Signing & Capabilities section, check the Automatically manage signing box, then choose a team added in Step 1.
      
   2. On the menu bar, select Product > Build.
5. Build the WebDriverAgentRunner target with the following steps:
   1. Select the WebDriverAgentRunner target. In the Signing & Capabilities section, check the Automatically manage signing box, then choose a team added in Step 1.
      
   2. On the menu bar, select Product > Build.

You have successfully installed the WebDriverAgent manually.