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.
- 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
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:
- 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
platformNamewith the value
Androidfor Android devices, or
iOSfor 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.
- In Remote server URL, enter the Appium server URL:
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:
config.propertiesfile 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
-browserTypeargument must be set to
-reportFolder=$DEVICEFARM_LOG_DIRargument allows us to download the execution report in Files/Customer Artifact of the AWS Device Farm Job.
- For more arguments, refer to Command Syntax.
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
targetfolder, you will see a .zip file named
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 4 steps to configure your Katalon test project on AWS Device Farm.
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.
In the Setup test framework section, click the dropdown button and select
Appium Java JUnit.
In the Selected File section, upload the
In the Choose your execution environment, choose Run your test in a custom environment, then click Next.
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.