Skip to main content

AWS Device Farm Integration

aws-device-farm-integration is built for executing Katalon Studio tests on AWS Device Farm. AWS Device Farm only supports running tests using supported frameworks such as Appium. Hence, Katalon users cannot execute their tests on AWS Device farm directly. See this AWS document for further information: Working with Appium and AWS Device Farm.

You can execute your Katalon test scripts with devices provided on AWS Device Farm by using aws-device-farm-integration. This tutorial shows you how to integrate with AWS Device Farm using aws-device-farm-integration. We also provide the KatalonDemoProject as a usage example.

Example Katalon project

You can clone or download our sample project and iOS application here. This step is optional, you can still use your own project in this tutorial.

Integrate with AWS Device Farm

To run your Katalon project with AWS Device Farm, you have to configure your Katalon projects and make updates in the aws-device-farm-integration.

  • An active Katalon Runtime Engine license.
  • Katalon Runtime Engine version 7.8.0 onwards.
  • Apache Maven version 3.3.9 onwards.
  • Java JDK 8 installed (This version is recommended).

Supported testing types and platforms:

  • Mobile app on Android
  • Mobile app on iOS
  • Web app on Android

Web app on iOS is currently not supported.

Configure your Katalon project

  1. In Katalon Studio, open your desired Katalon Project. Prepare your Katalon test cases and test suites that can successfully run on your local device.

    Your mobile test case should start with the keyword: Start Existing Application. This is because AWS Device Farm already installs the application on devices under test before every run. To learn more about this mobile keyword, see [Mobile] Start Existing Application.

  2. To change the desired capabilities corresponding to your app, open Project Settings > Desired Capabilities > Remote.

    configure desired capabilities

    • In Remote server URL, enter the Appium server URL:
    • In Remote server type, select Appium.
    • In Appium driver, select Android Driver for Android devices or iOS Driver for iOS devices.

    Click Add to create a desired capability named platformName with the value Android for Android devices, or iOS for iOS devices.

    When you are done with the configuration, click Apply and Close.


    For Android app testing, we need to add two extra desired capabilities: appPackage: [app ID] and appActivity: [main activity name]. The main activity can retrieve after uploading the app to AWS Device Farm.

    Android main activity

  3. Package your Katalon project into a .zip file.

Update aws-device-farm-integration project

  1. Clone or download aws-device-farm-integration from our repository: Katalon Studio AWS Device Farm Integration.
  2. Inside aws-device-farm-integration, place your Katalon Project .zip file in this directory: src/test/resources.

    zip demo project

  3. Open the file and change the following variables as your context:

    • KATALON_VERSION: Katalon Runtime Engine version.
    • KATALON_PROJECT_PACKAGE_FILE: Your package file.
    • KATALON_EXECUTE_ARGS: The arguments part of your Katalon run command
      • The -browserType argument must be set to "Remote".
      • The -reportFolder=$DEVICEFARM_LOG_DIR argument allows us to download the execution report in Files/Customer Artifact of the AWS Device Farm Job.
      • For more arguments, refer to Command Syntax.

    For example:

    KATALON_EXECUTE_ARGS=-retry=0 -testSuitePath="Test Suites/Regression Tests" -executionProfile=default -browserType=Remote -reportFolder=$DEVICEFARM_LOG_DIR -apiKey=xxxxxxxx
  4. To build the aws-device-farm-integration, at the folder aws-device-farm-integration, typing the below command in the terminal:

    mvn clean package -DskipTests=true

    When the build runs successfully, in the target folder, you will see a .zip file named

    build project with maven

Configure a test project on AWS Device Farm

After preparing your Katalon Project, log in to the AWS Console and go to Device Farm > Mobile Device: Projects to create a new project.

create test project

Input your Project Name, then hit Create.

This section guides you through 4 steps to configure your Katalon test project on AWS Device Farm.

  1. Choose application

    Choose between Mobile App and Web App with the toggle button.

    • For mobile app testing, select Mobile App. Upload your application under test, which is an .apk file for an Android application or an .ipa file for an iOS application. Wait for the file to upload, then click Next.

      upload mobile app

    • For Web app testing, select Web App. Enter your run name, then click Next. The Configure page appears.

  2. Configure

    In the Setup test framework section, click the dropdown button and select Appium Java JUnit.

    In the Selected File section, upload the file.

    In the Choose your execution environment, choose Run your test in a custom environment, then click Next.

    upload zip file

  3. Select Devices

    Choose a suitable device pool, then click Next.

    The Specify device state page appears. Review other settings and change when needed, then click Next.

  4. Review and start Run

    Review all of the configurations one last time, then click Confirm and Start Run.

    In AWS Console, a new test run is created. Its status is pending.

    finish creating run

    After the run starts, you can click on the test run name and a specified device to view the test status.

    view test run status

    test runs finish

    After the run finishes, you can download the execution report at Files/Customer Artifacts.

    download report