App Center integration

App Center Test supports only tests using frameworks such as Appium written in Java with JUnit. Therefore, Katalon users cannot directly execute their tests on App Center Test.

However, you can execute your Katalon test scripts with devices provided on App Center Test by using sideload to package Katalon projects in JUnit format. For more information, see Visual Studio App Center documentation: App Center Test and Preparing Appium Tests for Upload.

This tutorial shows you how to integrate with App Center Test using sideload. We also provide the KatalonDemoProject as a usage example.

Integrate with App Center

• An active Katalon Runtime Engine license.
• A Katalon API Key.
• Apache Maven version 3.3.9 or later installed.
• NodeJSversion 6.3 or later installed.
• App Center CLI installed and logged in.

To initiate testing with App Center Test, start by manually setting up an Appium Driver instance in Katalon Studio, then proceed to configure your project and update sideload. Follow these steps:

1. Create an Appium Driver instance.
   Open your project in Katalon Studio. At the beginning of your test script or in the Before Test Case listener, input the following snippet:

   import com.kms.katalon.core.appium.driver.AppiumDriverManager
   import org.openqa.selenium.remote.DesiredCapabilities
   import io.appium.java_client.MobileElement
   import io.appium.java_client.android.AndroidDriver
   import io.appium.java_client.remote.MobileCapabilityType
   
   String remoteServerUrl = System.getenv('XTC_SERVICE_ENDPOINT_APPIUM') + 'wd/hub'
   
   DesiredCapabilities capabilities = new DesiredCapabilities();
   capabilities.setCapability(MobileCapabilityType.DEVICE_NAME, 'S10 Plus')
   capabilities.setCapability(MobileCapabilityType.PLATFORM_NAME, 'android')
   capabilities.setCapability('appActivity', 'com.hmh.api.ApiDemos')
   capabilities.setCapability('appPackage', 'com.hmh.api')
   capabilities.setCapability('appWaitActivity', '*')
   capabilities.setCapability(MobileCapabilityType.AUTOMATION_NAME, AppiumDriverManager.UIAUTOMATOR2)
   capabilities.setCapability('autoGrantPermissions', true)
   
   AndroidDriver<MobileElement> driver = new AndroidDriver<MobileElement>(new URL(remoteServerUrl), capabilities)
   AppiumDriverManager.setDriver(driver)
2. Configure your Katalon project.
   1. Change the desired capabilities corresponding to your app. See Appium documentation: Capabilities.

      Since you have created a custom Appium driver, you need to comment out or remove all the Mobile.startApplication(...) or Mobile.startExistingApplication(...) in your current test cases.

   2. Package your Katalon project into a .zip file.
      Note:

      • When running tests on App Center with the .zip file packaged by macOS default file compress tool, you can sometimes encounter the error: No such file or directory.

      • To resolve this error, try running this command from the directory where the .zip file is located: zip -d <katalon_project_package_file> __MACOSX/\*, then continue with the following steps to update sideload.

3. Update sideload.
   1. Clone or download sideload from our repository at katalon-studio/sideload.
   2. Inside sideload, place your Katalon project .zip file in this directory: src/test/resources.
   3. Configure sideload.
      There are two ways to update sideload for you to choose:

      • Configure .bat file: upload.sh/upload.bat

      • Configure .java file: src/test/java/com/katalon/sideload/SideloadTest.java

      Note: If

      both files contain the configuration, the configuration in the .bat file will be prioritized.

      Configure .bat file

      Open the upload.bat file. Change the following variables as your context:

      • <app_name>: Your App Name on App Center.
      • <device_id/device_name>: Device ID or Device Name on App Center. To find your Device ID or Device Name on App Center, go to Test > Device sets.
      • <path_to_app_file>: The App to upload to App Center.
      • <katalon_version>: The version of Katalon Studio used to execute. Left blank or set as "latest" to run with the latest version of Katalon Studio.
      • <katalon_project_package_file>: Your package file.
      • <katalon_project_path>: Relative path of Katalon project's folder inside the zip package.
      • <katalon_execute_args>: The arguments part of your Katalon run command.
        • The argument browserType must be set as "Chrome"
        • The argument projectPath must be excluded from this parameter
        • For more arguments, see Command syntax.

      For example:

      appcenter test run appium ^
      --app "katalon/Sideload" ^
      --devices "katalon/nexus" ^
      --app-path "apps/APIDemos.apk" ^
      --test-series "master" ^
      --locale "en_US" ^
      --build-dir target/upload ^
      --test-parameter "test_env=KATALON_VERSION=" ^
      --test-parameter "test_env=KATALON_PROJECT_PACKAGE_FILE=KatalonDemoProject.zip" ^
      --test-parameter "test_env=KATALON_PROJECT_PATH=" ^
      --test-parameter "test_env=KATALON_EXECUTE_ARGS=-retry=0 -testSuitePath=""Test Suites/Regression Tests"" -executionProfile=default -browserType=Chrome -apiKey=""12345678-aaaa-bbbb-cccc-91011121314"""
      Configure .java file

      Open src/test/java/com/katalon/sideload/SideloadTest.java, find the SideloadTest section and change the following variables as your context:

      • API_KEY: Your API key.
      • KATALON_VERSION: The version of Katalon Studio used to execute. Left blank or set as "latest" to run with the latest version of Katalon Studio.
      • KATALONPROJECTPACKAGE_FILE: Your package file.

      • KATALONPROJECTPATH: Path to the Katalon project inside the package file.

      • KATALONEXECUTEARGS: The arguments part of your Katalon run command.

        • The argument browserType must be set as "Chrome"
        • The argument projectPath must be excluded from this parameter
        • For more arguments, refer to Command syntax

      For example:

      public class SideloadTest {
      /**
       * Your Katalon API Key
       */
      private static final String API_KEY = "12345678-aaaa-bbbb-cccc-91011121314";
      
      /**
       * Katalon version which will be used to run the test
       */
      private static final String KATALON_VERSION = ""; // Leave it blank to always use the latest version
      
      /**
       * The package file under the "src/test/resources" folder
       */
      private static final String KATALON_PROJECT_PACKAGE_FILE = "KatalonDemoProject.zip";
      
      /**
       * Path to the katalon project inside the package file.
       * If not specified it will use the same name with the package file.
       * (In this case, it is: KatalonDemoProject)
       */
      private static final String KATALON_PROJECT_PATH = "";
      
      /**
       * Katalon arguments
       * @apiNote Remember to always set "browserType" to "Chrome". This will prevent Katalon from inject inappropriate configurations in execution.
       * @apiNote Besides, you do not need to include project path in the argument list.
       */
      private static final String KATALON_EXECUTE_ARGS = String.format("-retry=0 -testSuitePath=\"Test Suites/Regression Tests\" -executionProfile=default -browserType=Chrome -apiKey=\"%s\"", API_KEY);

Upload KatalonDemoProject

This section provides a usage example on how to package a project, upload sideload to App Center Test, and start a test run in App Center Test.

To upload the KatalonDemoProject to App Center Test using sideload, follow these steps:

1. Clone or download sideload from our repository at Katalon Studio sideload.
2. Open the workspace of the usage example project by following the path: src/test/resources/KatalonDemoProject.zip.

   On App Center Test, create and start a new test run. See Starting a test run.

   • Device: Android 7.1.1 or prior. Ex: Motorola Nexus 6

   • Test framework: Appium

3. Execute the file package.bat/package.sh to pack your sideload project.
4. Configure in the file upload.sh/upload.bat.
5. Execute the file upload.sh/upload.bat to upload and run your sideload project in App Center Test.
6. View test reports on App Center Test. See Microsoft documentation: Test reports.

Troubleshooting: Object is null error

When handling relative object paths in the App Center test script, you might encounter Object is null error message.

Katalon Studio version earlier than 7.9.1 cannot handle relative object path, you must direct App Center to use Katalon Studio version 8.0.0 onwards.

1. From the SideloadTest.java file in the java folder src/test/java/com.katalon.sideload/SideloadTest.java, indicate version 8.0.0 by assigning the variable String katalonVersion.
   
2. From the KatalonDownloadUtils.java file, use KatalonVersion version = katalonVersion.