Get started with Katalon Test Execution Local

This guide shows you how to get started with Katalon Test Execution Local.

Requirements

• Verify that your computer meets the system requirements. See: System Requirements.
• A Test Execution Local license.
• A Katalon API Key for authentication. See: Generate a Katalon API Key.

Download installation package

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

1. Navigate to Katalon website.
2. Select the compatible version for your operating system and click download.

3. Unzip the package.

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

   • macOS: You need to enable the application in System Preferences / Security & Privacy / General.
   • Linux: Install OpenJDK 21 in Ubuntu (NOT Oracle JDK). You can find the installation steps in the OpenJDK documentation: Install OpenJDK. Once you finish, 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 21.

Execute tests

Once you unzip the package, follow these steps to execute tests:

Windows

1. Navigate to the unzipped folder of the package that contains the executable katalonc.exe.
2. Enter the following commands:

• For CMD:

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

• For PowerShell:

$katalonArgs = @("-noSplash", "-runMode=console", "-projectPath=Project Path", "-retry=0", "-testSuitePath=Test Suites/Demo", "-browserType=Chrome", "-executionProfile=default", "-apiKey=***", "-orgID=***", "--config", "-proxy.auth.option=NO_PROXY", "-proxy.system.option=NO_PROXY", "-proxy.system.applyToDesiredCapabilities=true", "-webui.autoUpdateDrivers=true", "-studioAssist.provider=katalon_ai")

.\katalonc.exe @katalonArgs

MacOS/Linux

1. Open terminal at the Contents folder, by one of two ways:

• Manual: Right-click the extracted Katalon Studio Engine file, and select "Show Package Contents" to see the Contents folder. Right-click on the folder, and select "New Terminal at Folder".

• Command: Copy the directory of the extracted Katalon Studio Engine file, then execute the following command in terminal:

  cd /path_to_Katalon_Studio_Engine/Contents

1. Execute the katalonc command along with arguments:

   ./MacOS/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 commands, you can use Command Builder. See: Command Builder in Katalon Studio.

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

Exit codes

Below is the list of exit codes of Katalon Test Execution Local:

• 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.
• 5: The project is invalid.
• 6: Test execution quota limit is reached.
• 7: Unable to check quota.

Command Builder in Katalon Studio

Command Builder is a utility in Katalon Studio that allows you to generate local execution 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 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 Execution - Local 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 command text from Command Builder, you can also package your configuration in the console.properties file. This file contains key-value pairs of your execution 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 execute the arguments in console.properties, use the following syntax.

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