Get started with Katalon Runtime Engine

This guide shows you how to get started with Katalon Runtime Engine (KRE).

Requirements

Before setting up KRE, make sure to complete the following requirements:

• Verify that your computer meets the system requirements for KRE. See: System Requirements.

• A KRE license. See: KRE License.

• A Katalon API Key for authentication. See: Generate a Katalon API Key.

Download KRE

As KRE has a standalone installation package, no installation is required and you just need to download the executable. Follow these steps:

1. Log in to Katalon Website with your account.
2. Select the compatible version of Katalon Runtime Engine for your operating system and download.
   
3. Unzip the package and move to the preferred directory to execute automation tests.

   Depending on the OS, you might need to perform further configuration.

   • macOS: you have to enable the KRE application in System Preferences / Security & Privacy / General.

   • Linux: Be sure to install OpenJDK 17 on your Ubuntu (NOT Oracle JDK). You can find the installation steps in the OpenJDK documentation: Install OpenJDK. Once you finish the installation, you can verify with the java -version command.

     Troubleshoot: You may encounter the NoClassDefFoundError error since Oracle JDK is being used. Please uninstall Oracle JDK, and then install OpenJDK 17.

Execute tests with KRE

To execute tests with KRE, follow these steps:

1. Open the command-line interface of your OS and navigate to the folder of KRE that contains the executable (katalonc.exe for Windows or katalonc for macOS and Linux).
   Note:

   On macOS, the executable is stored in the Contents folder of the application package. For example, the executable path can be /Downloads/Katalon_Studio_Engine_MacOS-8.6.0/Katalon Studio Engine.app/Contents/MacOS/katalonc.

2. Enter the katalonc command line along with arguments.
   On Windows:

   katalonc -noSplash -runMode=console -projectPath="C:\Users\username\Desktop\Katalon Studio\Sample healthcare\test.prj" -retry=0 -testSuiteCollectionPath="Test Suites/healthcare-tests - TS_RegressionTestCollection" -browserType="Chrome" -executionProfile="default" -apiKey="" --config -proxy.auth.option=NO_PROXY -proxy.system.option=NO_PROXY -proxy.system.applyToDesiredCapabilities=true

   On macOS and Linux:

   ./katalonc -noSplash -runMode=console -projectPath="/Users/username/Katalon Studio/Sample healthcare/test.prj" -retry=0 -testSuiteCollectionPath="Test Suites/healthcare-tests - TS_RegressionTestCollection" -browserType="Chrome" -executionProfile="default" -apiKey="" --config -proxy.auth.option=NO_PROXY -proxy.system.option=NO_PROXY -proxy.system.applyToDesiredCapabilities=true

   Note:

   • To easily generate KRE commands, you can use Command Builder. See: Command Builder in Katalon Studio.

   • For the full list of supported arguments, see: Command-line syntax in Katalon Runtime Engine.

KRE exit codes

Below is the list of exit codes of KRE:

• 0: The execution passed with no failed or error test case.
• 1: The execution has failed test cases.
• 2: The execution has error test cases.
• 3: The execution has failed test cases and error test cases.
• 4: The execution cannot start because of invalid arguments.

Command Builder in Katalon Studio

Command Builder is a utility in Katalon Studio that allows you to generate KRE commands quickly and precisely.

To access Command Builder, from the Katalon Studio main toolbar, click on Build CMD.

The Generate Command for Console Mode dialog displays as below.

To generate a KRE command, you need to specify the following information:

Test Suite

The test suite or test suite collection to be executed.

Executive Platform

Run with: The environment for the execution. Click Edit and select an environment to run your test with.

Run Configuration: This option is available for TestCloud environments. Click Edit to specify the TestCloud execution environments.

Profile: The execution profile. See: Global variables and Execution profile.

The Override the execution profile and environment of all test suites option allows you to override profiles and browser types for all test suites in a test suite collection.

Katalon Organization: if you belong to more than one Organization subscribing to KRE licenses, you can choose which Organization validates your license usage.

Authentication

Katalon API Key: API key represents a user's credentials.

Execution Configurations

Update WebDriver automatically: This option allows automatic WebDriver updates.

Terminate the execution once the total number of test failures reaches this threshold: The desired maximum number of test failures. The input must be a natural number larger than 0.

Apply proxy configuration from application settings: Configure Proxy Preferences in Katalon Studio.

Update execution status of the test suite after {x} second(s): The delay period between execution status updates.

Retry options: The retry behavior of execution. See: Modify execution information.

Katalon TestOps

Project: Override the Project ID in TestOps.

Release: Link test runs to a release created on TestOps. To learn how to create a release, see: Create and edit releases in TestOps.

After completing the configuration, click Generate Command. In the Generate Command dialog, you can copy the command and paste to the command prompt/terminal for execution.

Use the console.properties file

Besides generating and copying KRE command text from Command Builder, you can also package your configuration in the console.properties file. This file contains key-value pairs of your KRE arguments.

1. In Command Builder, click Generate Property File and save the file to the preferred location.
   
   
   
2. You can open and update the arguments as needed.
   
   
   
3. To run KRE with the arguments in console.properties, use the following syntax.

   katalonc -propertiesFile="<absolute path to console.properties file>" -runMode=console -apiKey="<Your_API_Key>"