Command-Line Syntax in Katalon Runtime Engine

You can execute an automation test without launching Katalon Studio by using command-line mode execution.

Note:

• Katalon Studio only supports Chrome, Firefox, and Remote options for console mode execution using the Linux version.
• From version 7.9.0 onwards, you can upgrade the default JRE 8 to higher versions in console mode. You can refer to this document for further details: Run tests with another JRE in the command line.

Requirements

• Katalon Runtime Engine installed. You can download Katalon Runtime Engine here: Katalon products.
• A Katalon Runtime Engine License. To learn more about activating your license, you can refer to this document: Katalon license.

Execute Katalon Studio in console mode

Note:

• The Katalon launcher (katalon.exe) is replaced by katalonc.exe.

1. Open the command prompt and navigate to the folder of your Katalon Studio build: katalonc.exe (Windows), Applications folder (Mac OS), or katalonc (Linux) file.

2. Enter the following syntax to execute your test:

   Windows:

   katalonc {arg1} {arg2} ... {argN}

   macOS:

   cd /Applications/Katalon\ Studio\ Engine.app/Contents/MacOS 
   
   ./katalonc --args {arg1} {arg2} ... {argN}

   Linux:

   ./katalonc {arg1} {arg2} ... {argN}

   For example:

   On macOS:

   

   On Windows:
   
   

3. Press Enter to start execution.

4. Exit Code:

   Below is the list of exit codes after console mode execution:

   • 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: Invalid project.
   • 6: Out of quota.
   • 7: Unable to check quota.

Use plugins in console mode

You can also continue using your plugins of choice with console commands. See this guide: Use Plugins in Console Mode.

General arguments

Here's the list of options supported for the katalonc commands for Katalon Studio version 7.0.0 onwards.

Required arguments

-runMode=console

Enable console mode.

-projectPath=<path>

Specify the project location (include .prj file). The absolute path must be used in this case.

-testSuitePath=<path>

Specify the test suite file (without extension .ts). The relative path (root being project folder) must be used in this case.

-testSuiteCollectionPath=<path>

Specify the test suite file (without extension .tsc). The relative path (root being project folder) must be used in this case.

Note:

• If -testSuitePath is specified, -testSuiteCollectionPath is not required.

-browserType=<browser>

Specify the browser type used for test suite execution.

From version 7.6+, you can use this option in Test Suite Collection execution. The specified browser is used for all test suites in that collection.

The following browsers are supported in KRE:

• Firefox
• Chrome
• IE
• Edge
• Edge (Chromium)
• Safari
• Remote
• Android
• iOS
• Web Service

Note:

• Only Chrome, Firefox, and Remote are available for use in the Linux version.

  Web Service is used for Web Service test execution.

-apiKey=<Your_API_Key> or -apikey=<Your_API_Key>

API Keys are used to represent a user's credentials. See: API Keys.

Optional arguments

-statusDelay=<seconds>

System updates execution status of the test suite after the delay period (in seconds) specified.

-retry=<number of retry times>

Number of times running test cases in the test suite.

-retryStrategy=<allExecutions | failedExecutions | immediately>

This option is supported in version 7.6 onwards. Specify which execution to be retried (this parameter overrides setting in test suite file):

• allExecutions: Retry all executions when the Test Suite fails
• failedExecutions: Retry only failed executions when the Test Suite fails
• immediately: Retry a failed execution of a test case or test data immediately. (Only for Katalon Studio Enterprise users)

-maxFailedTests=<T>

• From version 8.1.0, you can terminate a test suite/ test suite collection execution based on the number of test failures.
• Set <T> as the maximum number of total test failures allowed in the execution. Reaching <T> terminates the test execution.
• A test failure is counted when any of these type of tests fails: test case, retried test case, test iteration, or retried test iteration.

-reportFolder=<path>

Specify the destination folder for saving report files. You can use an absolute path or relative path (root being project folder).

-reportFileName=<name>

Specify the name for report files (.html, .csv, .log). If not provided, the system uses the name "report" (report.html, report.csv, report.log). .

Note:

• -reportFileName is only interpreted if -reportFolder is specified.

-sendMail=<e-mail address>

Specify the e-mail address for receiving report files. If the e-mail address was not specified, the report files are not to be sent.

-remoteWebDriverUrl=<remote web server url>

Specify the remote web driver URL.

-serverUrl=<server url>

Specify the server URL that you use to activate a KRE license. From Katalon Studio version 8.3.5 onwards, you can use this parameter to activate a KRE license with Private Instance while executing in console mode. For example: -serverUrl="https://admin-tenant1.katalon-cloudops.com".

-remoteWebDriverType=<Selenium | Appium>

Remote web's driver type.

Note:

• remoteWebDriverType is only interpreted if remoteWebDriverUrl is specified.

-deviceId=<device Id for Android/device UUID for ios>

Specify the device's ID to execute test scripts using this device.

Note:

• -deviceId is only interpreted if -browserType is specified.

-executionProfile

Specify the execution profile that a test suite executes with

From version 7.6.0 onwards, you can use this option in Test Suite Collection execution. The specified execution profile is applied to all test suites in that collection.

-delayBetweenInstances=<value>

• From Katalon version 8.2.0 onwards, you can set a delay between each test suite execution in a Test Suite Collection.

• Value is a positive integer from 0-999 seconds.

• When a test suite is ready to start, KRE prints a message in Console Log: Test suite ${testSuiteID} is ready to start at ${currentTimeStamp}

-g_<variable_name>

Override Execution Profile variables.

Example:-g_userName="admin"

-testSuiteQuery=<search-query>

From version 7.8.0, you can override the search query of the dynamic test suite from the CLI.

<search-query> is the search condition that follows the query syntax of the installed query provider plugin. For detailed instruction, follow this guide: Pass the search query to the CLI for dynamic test suite execution.

Example:-testSuiteQuery="ids=(Test Cases/TC1_Verify Successful Login,Test Cases/TC2_Verify Successful Appointment)"

-testSuiteCollectionQuery

From version 8.0.0, you can enable or disable Test Suite(s) in Test Suite Collection.

Example:-testSuiteCollectionQuery="indexes=(1,3)"

-maxResponseSize

Override the maximum response size in project setting (available from version 7.6). Learn more about Web Service Settings.

Example:-maxResponseSize=400

-licenseRelease -orgID=<organization's id>

From version 8.0.0, you can release the previous execution session before checking the license.

Example:

-licenseRelease=true

-orgID=89151

--config -webui.autoUpdateDrivers=true

Allow WebDriver binaries to be updated automatically in console mode.

Windows-specific arguments

-consoleLog

Display log in the console. Only use this option when running Katalon Studio in Windows Command Prompt. Do not use this option in other OSes or CI tools, for example Jenkins.

-noExit

Keep the console open after the execution is completed. Only use this option when running Katalon Studio in Windows Command Prompt. Do not use this option in other OSes or CI tools, for example Jenkins.

Proxy arguments

Note:

• From version 7.5.0 onwards, there are two types of proxy configurations: authentication and system proxies. To learn more about configuring different proxy preferences, you can refer to this document: Proxy Preferences for further details.

• From version 7.2.0 onwards, you can exclude a list of hosts from proxy in the Manual proxy configuration. To learn more about manually excluding domains from proxy, you can refer to this document: Proxy settings.

• From version 7.0.0 onwards, you can pass proxy details via a request object in Web Service testing. To learn more about passing proxy details in script mode, you can refer to this document: Override proxy details in the test script.

These proxy options must be used with --config parameter, for example: --config -proxy.auth.option=MANUAL_CONFIG

katalonc -noSplash -runMode=console -projectPath="C:\Users\Katalon Studio\Project\YourProject.prj" -retry=0 -testSuitePath="Test Suites/download" -executionProfile="default" -browserType="Chrome" --config -proxy.auth.option=MANUAL_CONFIG -proxy.auth.server.type=HTTP -proxy.auth.server.address=192.168.1.16 -proxy.auth.server.port=16000 -proxy.system.option=MANUAL_CONFIG -proxy.system.server.type=HTTP -proxy.system.server.address=127.0.0.1 -proxy.system.server.port=12701 -proxy.system.username=katalon -proxy.system.password=T3stP@zZW0rol -proxy.system.applyToDesiredCapabilities=true

Authentication proxy arguments

-proxy.auth.option

The available values for this option are: NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.auth.server.type

The available server types are: HTTP, HTTPS, or SOCKS.

-proxy.auth.server.address

Example: locahost, katalon.com.

-proxy.auth.server.port

Example: 80, 8080, 9999.

-proxy.auth.excludes

Exclude the specified server.

For example: 127.0.0.1, localhost, myserver.com.

-proxy.auth.username

Example: MyProxyUsername. This option is required if the specified proxy server requires authentication.

-proxy.auth.password

Example: MyProxyPassword. This option is required if the specified proxy server requires authentication.

System proxy arguments

For versions 7.5.0 onwards

-proxy.system.option

The available values for this options are: NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.system.server.type

HTTP, HTTPS, or SOCKS

-proxy.system.server.address

Example: locahost, katalon.com.

-proxy.system.server.port

Example: 80, 8080, 9999.

-proxy.system.excludes

Example: 127.0.0.1, localhost, myserver.com.

-proxy.system.username

Example: MyProxyUsername. This option must be specified if your proxy requires authentication.

-proxy.system.password

Example: MyProxyPassword. This option must be specified if you proxy requires authentication.

-proxy.system.applyToDesiredCapabilities

Example: true or false.

For versions below 7.5.0

-proxy.option

NO_PROXY, USE_SYSTEM, or MANUAL_CONFIG.

-proxy.server.type

HTTP, HTTPS, or SOCKS.

-proxy.server.address

Example: locahost, katalon.com.

-proxy.server.port

Example: 80, 8080, 9999.

-proxy.excludes

Example: 127.0.0.1, localhost, myserver.com.

-proxy.username

Example: MyProxyUsername. This option must be specified if your proxy requires authentication.

-proxy.password

Example: MyProxyPassword. This option must be specified if your proxy requires authentication.

Integration arguments

TestOps integration arguments

--info -buildLabel=<text> -buildURL=<text>

Pass the build's label and URL, which are displayed in Katalon TestOps.

Example:

--info -buildLabel="Build 1" -buildURL="http://192.168.35.52:8080/job/katalon-demo/job/master/179/"

-testOpsBuildId

From version 8.0.0, you can specify the build ID to update the Test Suite/Test Suite Collection report.

Example:-testOpsBuildId=24

-testOps.baselineCollectionId=<CollectionId>

From version 8.4.0 onwards, you can specify a baseline collection ID to which Katalon visual testing functionality compares newly captured images in your test runs. See: Use TestOps Visual Testing.

For example:

-testOps.baselineCollectionId=1234

-testOps.serverUrl=<URL>

From version 8.4.0 onwards, you can specify the URL for TestOps server for authentication and integration. You can use this argument to work with different offerings of TestOps, including:

• Public Cloud and On-premise.

• Private Instance. See: TestOps Private Instance integration in Katalon Studio.

• Staging and Production.

Note:

• If -testOps.serverUrl is not specified, the default URL is https://testops.katalon.io.

-testOps.customField=<key1:value1, key2:value2>

Assigns pre-existent custom fields to the test run. Multiple custom fields can be assigned, separated by a comma. The command also creates a custom field and assign it to the test run if the custom field was never created before. To understand more about custom field, see Custom Fields and Tags.

-testOps.tag=<tag1, tag2>

Assign pre-existent tags to the test run. Multiple tags can be assigned, separated by a comma. The command also creates a tag and assign it to the test run if the tag was never created before. To understand more about tag, see Custom Fields and Tags.

TestCloud integration arguments

-testcloudEnvironmentId=<ID>

The ID of the environment which corresponds to a combination of OS, browser type and browser version to execute (Available from 8.2.5 onwards).

Note:

• To get the TestCloud environment ID, open Katalon Studio and use the command builder. For detailed information, follow this guide: Generate Command with Command Builder.

• This parameter already contains the information about browser type. Therefore, the -browserType parameter is not generated in this integration.

-testcloudTunnel

Allow the execution to be performed via a tunnel (Available from 8.2.5 onwards).

Kobiton integration arguments

--config -kobiton.authentication.username=<yourKobitonUsername> -kobiton.authentication.password=<yourPassword>

Passing Kobiton username and password.

--config -kobiton.authentication.serverUrl=<defaultKobitonServer> -kobiton.authentication.username=<yourKobitonUsername> -kobiton.authentication.apiKey=<yourKobitonAPIKey>

Passing Kobiton Server URL, username, and APIKey (Available in 7.8 and later).

-kobitonDeviceId=<yourKobitonDeviceId>

ID of the destination where the result is uploaded on it.

Azure DevOps integration arguments

-adoPlanId=<testplanID>

ID of the test plan used for submitting test run(s)(available from version 8.0.0).

-adoTestRunName=<testRunName>

From version 8.0.0, you can create test run(s) on ADO with the specified name.

--info -adoDefinitionID=<definitionID>

From version 8.0.0, you can get the latest completed Build ID of the specified Definition ID and pass it to Test Run properties on ADO.

Command Builder in Katalon Studio

You can use the Command Builder to generate commands quickly and precisely from Katalon Studio.

1. Click on Build CMD from the main toolbar.

   
   
   

2. The Generate Command for Console Mode displays. Configure your execution with the provided options:

   In Katalon Studio - Platform Edition:

   In Katalon Studio - Standalone Edition:
   
   

   • Test Suite: The Test Suite or Test Suite Collection to be executed.

   • Executive Platform:

     • Run with: Testing environment of the execution. Click on Edit and select an environment to run your test with.
       
       

     • Run Configuration: If you choose TestCloud as your execution environment, the Run Configuration option appears. From version 8.2.5 onwards, you can integrate and run your test with TestCloud - a cloud-based test execution environment of Katalon Platform. To learn more about the configuration and execution with TestCloud in console mode, see Run TestCloud with Katalon Runtime Engine.

     • Profile: Execution profile of the execution.

     • Override the execution profile and environment of all test suites: This option is available when you generate command for a test suite collection. Check this option if you want the specified -BrowserType and -ExecutionProfile in the command to override the browser type and execution profile of all test suites in the selected test suite collection (available from version 7.6.0 onwards).

       

   • Authentication:

     • Katalon API Keys: API Keys are used to represent a user's credentials. The command-line options of API Key, including -apiKey=<Your_API_Key> and -apikey=<Your_API_Key> are both accepted. To learn more about API keys, you can refer to this document: API key.
     • Katalon Organization: From version 7.7.0 onwards, if you belong to more than one Organization subscribing to Katalon Runtime Engine (KRE) licenses, you can choose which Organization validates your license usage. Katalon retrieves and displays the Organizations your Katalon account is bound to, as well as which Organizations have made KRE licenses available to you. Once selected, the Organization ID is passed to the generated command (-orgID=<Katalon_OrgID>).
   • Execution Configurations (For versions older than 7.7.0: Other Options).

     • Terminate the execution once the total number of test failures reaches the input threshold: From version 8.1.0 onwards, you can terminate execution after T test failures (T is the failure threshold value). See also: Terminate Execution Conditionally.
       
       

   • Katalon TestOps:

     • Project: Override the Project ID in Katalon TestOps (available for Katalon Studio - Standalone Edition version 7.8.0 onwards).

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

     
     
     

3. Click Generate Command after completing the configuration.

4. You can Copy to Clipboard and paste to the Command Prompt/Terminal for execution.

   

Use the console.properties file

Katalon support running console mode using the console.properties file where you can manually modify the content if needed.

1. Generate a console.properties file using our generator.

   
   
   

2. The console.properties file is generated at your preferred location. You can open and update the parameters manually as needed.

   For example:

   
   
   

3. Run the console.properties file in console mode with the following syntax.

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

   For example:

   
   
   

4. You can add additional katalonc command options if needed. Any option already defined in the console.properties file is overwritten by the one declared in the command line.

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

   In the example above, since we also declare browserType option in the command line, the automation test is executed using IE instead of Chrome.