AWS Device Farm integration

AWS Device Farm only supports running tests written in frameworks such as Appium, so Katalon users cannot directly execute their mobile tests on AWS Device Farm. Katalon Studio develops an aws-device-farm-integration project that allows you to execute Katalon tests on AWS platform.

This tutorial shows you how to install and use the AWS Device Farm integration. We also provide the KatalonDemoProject as a usage example.

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.

• Sample Katalon project: AWS Device Farm integration
• Sample iOS application: Coffee Timer.ipa
• For CI/CD pipelines with Jenkins, clone or download CI samples from our repository.

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.

Important:

• An active Katalon Runtime Engine license.
• Apache Maven version 3.3.9 onwards.
• Java JDK 8 installed (This version is recommended).
• This integration is supported for Mobile app testing on Android, iOS and Web app testing on Android.

Configure your Katalon project

To configure your Katalon project for mobile testing, follow these steps:

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.

   Start your mobile test case 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.
   
   
   
   • In Remote server URL, enter the Appium server URL: http://127.0.0.1:4723/wd/hub .
   • In Remote server type, select Appium.
   • In Appium driver, select Android Driver for Android devices or iOS Driver for iOS devices.
3. Click Add to create a desired capability named platformName with the value Android for Android devices, or iOS for iOS devices.
4. Click Apply and Close.
   Note:

   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.
   
   

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

Update aws-device-farm-integration project

To update the aws-device-farm-integration project with your Katalon project settings and prepare it for AWS Device Farm, follow these steps:

1. Clone or download aws-device-farm-integration from our GitHub repository.
2. Inside aws-device-farm-integration, place your Katalon project .zip file in this directory: src/test/resources.
   
   
   
3. Open the config.properties 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_VERSION=8.1.0
   KATALON_PROJECT_PACKAGE_FILE=KatalonDemoProject.zip
   KATALON_EXECUTE_ARGS=-retry=0 -testSuitePath="Test Suites/Regression Tests" -executionProfile=default -browserType=Remote -reportFolder=$DEVICEFARM_LOG_DIR -apiKey=xxxxxxxx
4. Build the AWS Device Farm integration.
   At the folder aws-device-farm-integration, type this 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 zip-with-dependencies.zip.

   
   
   

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.

Input your Project Name, then hit Create.

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

1. Choose between Mobile App and Web App.

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

     
     
     

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

2. In the Setup test framework section, do as follows:
   • Click the dropdown button and select Appium Java JUnit.

   • In the Selected File section, upload the zip-with-dependencies.zip file.

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

   
   
   
3. Choose a suitable device pool in Select Devices, then click Next.

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

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

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

   
   
   

   
   
   

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