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.

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

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.
Katalon Runtime Engine version 7.8.0 onwards.
Apache Maven version 3.3.9 onwards.
Java JDK 8 installed (This version is recommended).

Note:

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

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

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.
Package your Katalon project into a .zip file.

Update aws-device-farm-integration project

Clone or download aws-device-farm-integration from our repository: Katalon Studio AWS Device Farm Integration.
Inside aws-device-farm-integration, place your Katalon Project .zip file in this directory: src/test/resources.
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
```
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 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.

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.

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.
- For Web app testing, select Web App. Enter your run name, then click Next. The Configure page appears.
Configure

In the Setup test framework section, 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.
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.
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.

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.