Command-line syntax in Katalon Runtime Engine
This guide lists out the supported command-line syntax and arguments of Katalon Runtime Engine.
- To upgrade the default JRE 8 to higher versions,t refer to this document for further details: Run tests with another JRE in the command line.
Requirements
- Katalon Runtime Engine is installed. See: Get started with Katalon Runtime Engine.
- A Katalon Runtime Engine License. To learn more about activating your license, you can refer to this document: Katalon license.
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.
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 or 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"
.-appiumDirectory=<path>
The directory where Apppium is installed. For example, the path can be "/opt/homebrew/lib/node_modules/appium".
-remoteWebDriverType=<Selenium | Appium>
Remote web's driver type.
Note:remoteWebDriverType
is only interpreted ifremoteWebDriverUrl
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.
License retry mechanism (optional arguments)
-enableLicenseRetry
- Enable or disable the license retry mechanism when no license is available.
Default value in version 9.x:
false
Default value in version 10.x:
true
The input must be a valid boolean.
-licenseRetryMaxDuration
- Specify the maximum duration (in minutes) that KRE will retry license activation. After this time, KRE will stop retrying if activation is not successful.
Default value: 20 minutes.
The input must be a valid integer.
-licenseRetryInterval
- Specify how often (in minutes) KRE should retry the license activation attempt.
Default value: 5 minutes.
The input must be a valid integer.
This value should not exceed the
licenseRetryMaxDuration
.
-licenseRetryMaxJitter
- Specify the jitter factor (in minutes) to add randomness to the retry interval.
Default value: 2 minutes.
The input must be a valid integer.
The jitter factor is calculated as
licenseRetryMaxJitter
/licenseRetryInterval
.This value should not exceed the
licenseRetryInterval
.
When
-enableLicenseRetry
is set totrue
, KRE will attempt to reactivate the license whenever it encounters an issue where no license is available.You can control how long the retry process will last using
-licenseRetryMaxDuration
.The
-licenseRetryInterval
specifies how frequently KRE should retry, while the-licenseRetryMaxJitter
adds some randomness to avoid predictable retry intervals.
Example usage:
To configure KRE to retry license activation for up to 10 minutes, with retry attempts every 3 minutes and a jitter factor of 1 minute:
katalon.exe -noSplash -runMode=console -retry=2 -retryStrategy=failedExecutions -statusDelay=60 -projectPath="%projectPath%" -testSuitePath=%testSuite% -browserType="Firefox" -executionProfile="default" -apiKey="<your_api_key>" -orgID=<your_org_id> -testOpsProjectId=<your_project_id> --config -webui.autoUpdateDrivers=true -licenseRelease=true -reportFolder=./Reports/Your_Report_Folder -enableLicenseRetry=true -licenseRetryMaxDuration=10 -licenseRetryInterval=3 -licenseRetryMaxJitter=1
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
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
, orMANUAL_CONFIG
.-proxy.auth.server.type
The available server types are:
HTTP
,HTTPS
, orSOCKS
.-proxy.auth.server.address
Example: localhost, 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
-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.
-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
-testOpsProjectId
The ID of the TestOps Project that is associated with the test run.
Example -testOpsProjectId=123456.
-testOpsReleaseId
- The ID of the TestOps release that is associated with the test run.
--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: Version 8.0.0 - 8.0.1.
Staging and Production.
Note:If
-testOps.serverUrl
is not specified, the default URL ishttps://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).
--testcloudMobileDeviceId=<device name>
and-testcloudMobileId=<device name>
- When combined with
-browserType="TestCloud"
, these parameters set the execution environment to mobile browser on TestCloud. To generate the correct device name values, you should use Command Builder in Katalon Studio. See: Run tests on mobile browsers in Katalon Runtime Engine.
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.