Command Syntax (Command-line/Console Mode Execution)

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

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.

Notes:

  • 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.

Execute Katalon Studio in console mode

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 {option1} {option2} ... {optionN}
    

    macOS:

    cd /Applications/Katalon\ Studio\ Engine.app/Contents/MacOS 
    
    ./katalonc --args {option1} {option2} ... {optionN}
    

    Linux:

    ./katalonc {option1} {option2} ... {optionN}
    

    For example:

    Execute Katalon in console mode
  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.

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 Options

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

Katalonc Command-line Option Description Mandatory?
-runMode=console Enable console mode. Y
-statusDelay=<seconds> System updates execution status of the test suite after the delay period (in seconds) specified. N
-projectPath=<path> Specify the project location (include .prj file). The absolute path must be used in this case. Y
-testSuitePath=<path> Specify the test suite file (without extension .ts). The relative path (root being project folder) must be used in this case. Y
-testSuiteCollectionPath=<path>

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

Y (If -testSuitePath is not used. Otherwise it's optional)
-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 Katalon:

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

Y

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

Web Service is used for Web Service test execution.

-retry=<number of retry times> Number of times running test cases in the test suite. N
-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)
N
-reportFolder=<path> Specify the destination folder for saving report files. You can use an absolute path or relative path (root being project folder). N
-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.
-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). This option is only taken into account when being used with the "-reportFolder" option. N
-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. N
-remoteWebDriverUrl=<remote web server url> Specify the remote web driver URL. N
-remoteWebDriverType=<Selenium, Appium> Remote web's driver type. Y (If -remoteWebDriverUrl is used)
-deviceId=<device Id for Android/device UUID for ios> Specify the device's ID to execute test scripts using this device. Y (If -browserType=Android or -browserType=iOS is used)
-executionProfile

Specify the execution profile that a test suite executes with

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

N

-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}
     
N
-g_XXX

Override Execution Profile variables.

Example:

-g_userName="admin"

N
--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/"

N
-testOpsBuildId

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

Example:

-testOpsBuildId=24

N
-testSuiteCollectionQuery

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

Example:

-testSuiteCollectionQuery=”indexes=(1,3)”

N
-maxResponseSize

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

Example:

-maxResponseSize=400

N

-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

N

Windows-Only Options

Katalonc Command-line Option Description Mandatory?
-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. N
-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. N

Proxy Options

Notes:

  • 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

Authentication Proxy Option Description Mandatory?
-proxy.auth.option NO_PROXY, USE_SYSTEM, MANUAL_CONFIG Y
-proxy.auth.server.type  HTTP, HTTPS, or SOCKS Y
-proxy.auth.server.address Example: locahost, katalon.com Y
-proxy.auth.server.port Example: 80, 8080, 9999 Y
-proxy.auth.excludes Example: 127.0.0.1, localhost, myserver.com N
-proxy.auth.username Example: MyProxyUsername Optional (YES if your proxy server requires authentication)
-proxy.auth.password Example: MyProxyPassword Optional (YES if your proxy server requires authentication)

System Proxy

  • For Katalon version 7.5.0 onwards, do as follows:
System Proxy Option Description Mandatory?
-proxy.system.option NO_PROXY, USE_SYSTEM, MANUAL_CONFIG Y
-proxy.system.server.type  HTTP, HTTPS, or SOCKS Y
-proxy.system.server.address Example: locahost, katalon.com Y
-proxy.system.server.port Example: 80, 8080, 9999 Y
-proxy.system.excludes Example: 127.0.0.1, localhost, myserver.com N
-proxy.system.username Example: MyProxyUsername Optional (YES if your proxy server requires authentication)
-proxy.system.password Example: MyProxyPassword Optional (YES if your proxy server requires authentication)
-proxy.system.applyToDesiredCapabilities Example: true or false N
  • For versions older than 7.5.0, do as follows:
Option Description Mandatory?
-proxy.option NO_PROXY, USE_SYSTEM, MANUAL_CONFIG Y
-proxy.server.type  HTTP, HTTPS, or SOCKS Y
-proxy.server.address Example: locahost, katalon.com Y
-proxy.server.port Example: 80, 8080, 9999 Y
-proxy.excludes Example: 127.0.0.1, localhost, myserver.com N
-proxy.username Example: MyProxyUsername Optional (YES if your proxy server requires authentication)
-proxy.password Example: MyProxyPassword Optional (YES if your proxy server requires authentication)

Integration Options

Katalonc Command-line Option Description Mandatory?
--config -kobiton.authentication.username=[yourKobitonusername] -kobiton.authentication.password=xxxxx Passing Kobiton username and password N
--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) N
-kobitonDeviceId=[yourKobitonDeviceId] Passing Kobiton Device ID (Available in 7.8 and later) N
-qTestDestId=<destination's id> Id of the destination where the result is uploaded on it N
-qTestDestType=<destination's type> Type of the destination. There are 4 options for destination's type:"test-suite", "test-cycle",  "release", and "root". N
--info -qTestBuildNumber="text" --qTestBuildURL="text"

Introduced in version 7.8.5. Pass the build's number and URL to Test Run properties on qTest.

Example:

Example: --info -qTestBuildNumber="Build 1" -qTestBuildURL="http://192.168.35.52:8080/job/katalon-demo/job/master/179/"

N
-adoPlanId=<testplan id>

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

N
-adoTestRunName="text"

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

N
--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.

N

Automatically Updating WebDriver Option

Katalonc Command-line Option Description Mandatory?
--config -webui.autoUpdateDrivers=true Allow WebDriver binaries to be updated automatically in console mode. N

Command Builder

We recommend using the Command Builder to generate commands quickly and precisely. Please do as follows:

  1. Click on Build CMD from the main toolbar.

    Build CMD
  2. The Generate Command for Console Mode is displayed. Configure your execution with the provided options:

    Generate Command for Console Mode
  • Test Suite: The Test Suite or Test Suite Collection to be executed.

  • Executive Platform:

    • Run with and Profile: Testing environment and execution profile of the execution.

      select environment
    • Override the execution profile and environment of all test suites: Check 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 collection (available from version 7.6 onwards)

  • Authentication:

    • 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.
    • From version 7.7.0 onwards, if you belong to more than one Organization subscribing to Runtime Engine (RE) 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 RE licenses available to you. Once selected, the Organization ID is passed to the generated command (-orgID=<Katalon_OrgID>).
  • Execution Configurations (Or Other Options in versions older than 7.7.0).

    execution configurations

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

  • Katalon TestOps: Override the Project ID in Katalon TestOps (available from version 7.8 onwards).

    Katalon TestOps
  1. Click Generate Command after completing the configuration.

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

    generate command

Use the console.properties file

We 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.

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

    For example:

    console.properties
  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:

    console.properties
  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.

Feedback