Command Syntax (Command-line/Console Mode Execution)

From version 7.0.0, you need a Runtime Engine (RE) license to activate and run Katalon Studio (KS) or Katalon Studio Enterprise (KSE) in console mode.

Katalon Studio only supports Chrome, Firefox, and Remote options for console mode execution using the Linux version.

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

Execute Katalon Studio in console mode

From Katalon Studio version 7.0.0, you need to download the Katalon Runtime Engine package. 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 automation 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:

  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

API Keys are required to use Katalon Studio Plugins in console mode. Learn more.

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
-retryFailedTestCases=<true,false> Retry executing failed test cases in test suite (this parameter overrides setting in test suite file ). There are 2 options: true if you want to run failed test case; otherwise, false. N
-retryFailedTestCasesTestData=<true,false> Retry failed test data execution in test suite (this parameter overrides setting in test suite file). There are 2 options: true if you want to run failed test data execution; otherwise, false (available from version 7.5 and only for Katalon Studio Enterprise users). 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
-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
-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
-maxResponseSize

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

Example:

-maxResponseSize=400

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 e.g., 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 e.g., Jenkins. N

Proxy Options

In version 7.5+, there are two types of proxy configurations: Authentication and System proxies. Refer to this document for further details.

In version 7.2+, you can exclude proxy in manual configuration.

In version 7.0+, you can pass proxy details via a request object in Web Service testing. Refer to this document for further details.

These proxy options must be used with --config parameter e.g. --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

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

Proxy Configurations prior to 7.5.0

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

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.

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

    where:

  • Test Suite: The Test Suite or Test Suite Collection to be executed
  • Executive Platform: Testing environment and execution profile of the execution
  • 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)
  • Other Options:
  1. Click Generate Command after completing the configuration.

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

Use 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:

  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.

Feedback