Command-Line Syntax in Katalon Runtime Engine
You can execute an automation test without launching Katalon Studio by using command-line mode execution.
- 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
- The Katalon launcher (
katalon.exe
) is replaced bykatalonc.exe
.
- Open the command prompt and navigate to the folder of your Katalon Studio build:
katalonc.exe
(Windows), Applications folder (Mac OS), orkatalonc
(Linux) file. -
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:
-
Press Enter to start execution.
-
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 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.
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: 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
-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
--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 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).
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.
-
Click on Build CMD from the main toolbar.
-
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>
).
- Katalon API Keys: API Keys are used to represent a user's credentials. The command-line options of API Key, including
- 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.
-
-
Click Generate Command after completing the configuration.
-
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.
-
Generate a console.properties file using our generator.
-
The console.properties file is generated at your preferred location. You can open and update the parameters manually as needed.
For example:
-
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:
-
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.