Execute mobile tests with Appium 2.x

Warning:

• Since January 1, 2022, the Appium core team no longer maintains Appium 1.x. As such, all latest versions of the officially supported platform drivers are no longer compatible to Appium 1.x, and requires Appium 2 to run.

• Katalon Studio added support for Appium 2 from version 9.1.0 and later versions. If your team is migrating from Appium 1.x to Appium 2.x, refer to the following documentation:

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

The following documentation provides guidance on how to configure and execute mobile tests with Appium 2.x, and more.

Requirements

• Katalon Studio version 9.1.0 and later versions.
• 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) to avoid issues.

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. As such, install the Appium XCUITest Driver for iOS and Appium UiAutomator2 Driver for Android.

   • For iOS: 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.

     Run the following command to install the latest version of Appium XCUITest driver (version 5.0.0):

     appium driver install xcuitest@5.0.0

     Note:

     • If you are using Appium 2.0 and Xcode 14 to test 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.

   • For Android: 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.

     Run the following command to install the recommended version of the Appium UiAutomator2 driver (version 2.45.1):

     appium driver install uiautomator2@2.45.1
3. If you have both Appium 1 and Appium 2 on your machine, make sure to specify the Appium version to execute your test with. To do so, 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 the 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 the latest version of the 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. Navigate to the WebDriverAgent folder in this directory: /Users/your_username/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent.

   For example: Users/john_smith/.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.