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 with AWS Device Farm.

However, you can execute Katalon tests on the AWS platform by using aws-device-farm-integration.

See this AWS document for further information: Working with Appium and AWS Device Farm.

This tutorial shows you how to configure your Katalon project, update the aws-device-farm-integration project, and create a test project on AWS Device Farm.

You can clone or download our sample project and iOS application. 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.

requirements

• 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. This includes verifying that your device is properly connected, the application under test is accessible, and the test scripts are free of errors.

   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. Select Add to create a desired capability named platformName with the value Android for Android devices, or iOS for iOS devices.
4. Select 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 per 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. Determine the framework for your test.

   If you want to run with TestNG java-based framework:

   • Go to aws-device-farm-integration-main/src/test/java/com/kms/example/aws_ios/test/TestIos.java

   • Enable the line import org.testng.annotations.Test;
   • Then comment on the line import org.junit.Test;

   

   If you want to run with JUnit open-source framework:

   • Go to aws-device-farm-integration-main/src/test/java/com/kms/example/aws_ios/test/TestIos.java

   • Enable the line import org.junit.Test;
   • Then comment on the line import org.testng.annotations.Test;

   

5. 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, sign in to the AWS Console and go to Device Farm > Mobile Device: Projects to create a new project.

Input your Project Name, then select 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:
   • Select the dropdown button and choose 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 select Next.

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

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

4. Review all of the configurations one last time, then select Confirm and Start Run.
   In AWS Console, a new test run is created. Its status is pending.
   
   
   

   After the run starts, you can select 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.