Get started with Katalon Runtime Engine (KRE)

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:

Setting	Description
Test Suite	The test suite or test suite collection to be executed.
Execution Platform	Run with: The environment for the execution. Click Edit and select an environment to run your test with. Run Configuration: Available for TestCloud environments. Click Edit to specify the TestCloud execution environments. Profile: The execution profile. See Global variables and Execution profile. Override the execution profile and environment of all test suites: Allows overriding 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: Enables automatic WebDriver updates. Terminate the execution once the total number of test failures reaches this threshold: Sets the maximum number of test failures (must be a natural number > 0). Apply proxy configuration from application settings: See Configure Proxy Preferences in Katalon Studio. Update execution status of the test suite after {x} second(s): Sets the delay period between execution status updates. Retry options: Defines retry behavior. See Modify execution information in Test Suite execution.
Katalon TestOps	Project: Overrides the Project ID in TestOps. Release: Links test runs to a release created on TestOps. 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>"