Skip to main content

App Center Integration

Sideload is built for executing Katalon Studio tests on App Center Test. App Center Test only supports running tests using supported frameworks such as Appium tests written in Java with JUnit; hence, Katalon users cannot execute their tests on App Center Test directly.

You can execute your Katalon test scripts with devices provided on App Center Test by using sideload to package Katalon projects in JUnit format. 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​

Important:

To run your Katalon projects with App Center Test, you have to configure your Katalon project and make updates in sideload.

Configure your Katalon Project​

Before executing any test, you need to manually create an Appium Driver instance and set it as the currently used instance in Katalon Studio.

  1. 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)

  1. Change the desired capabilities corresponding to your app.

    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.

Update sideload​

  1. Clone or download sideload from our repository: 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 fileUpload

    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, refer to 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);

  4. To pack your sideload project, execute the file package.bat/package.sh.

  5. To upload and run your sideload project on the App Center, execute the file upload.sh/upload.bat.

Upload KatalonDemoProject​

This section provides you a usage example on how to upload KatalonDemoProject packaged in JUnit by sideload and start a test run in App Center Test.

  1. Clone or download sideload from our repository: 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 Microsoft documentation: Starting a test run.

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

  3. To pack your sideload project, execute the file package.bat/package.sh.

  4. Upload sideload:

    • Before uploading, you should configure in the file upload.sh/upload.bat.
    • To upload and run your sideload project on the App Center, execute the file upload.sh/upload.bat.

    You can view test reports on App Center Test. See Microsoft documentation: Test reports.

Handle relative object paths​

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 our sample, indicate version 8.0.0 by assigning the variable String katalonVersion.
    katalonVersion in SideloadTest.java
  2. From the KatalonDownloadUtils.java file, use KatalonVersion version = katalonVersion.
    katalonVersion in KatalonDownloadUtils.java