Command Syntax (Command-line/Console Mode Execution)

Estimated reading time: 8 minutes

Starting from version 7.0.0, you need a Runtime Engine (RE) license to activate and run Katalon Studio (KS) or Katalon Studio Enterprise (KSE) from the command line.

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

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

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

Execute Katalon in CMD

Starting from Katalon Studio version 7.0.0, you need to download the Runtime Engine package from Katalon website. 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.

Katalon Studio Plugins in Console Mode

To be used in console mode, Katalon Studio Plugins must be installed using Katalon Store's API keys. Please follow instructions here.

General Options

Here's the list of options supported for the katalon commands in Katalon Studio prior to version 7.0.0, and the katalonc commands for Katalon Studio version 7.0.0 and later.

Katalonc Command Line Option Description Mandatory?
-runMode=console Enable console mode. Y
-summaryReport Send summary report for a batch run. N
-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.

Note: Available only in 4.4+

Y (If -testSuitePath is not used. Otherwise it's optional)
-browserType=<browser>

Specify the browser type used for test suite execution.

The following browsers are supported in Katalon:

  • Firefox
  • Chrome
  • IE
  • Safari
  • Remote
  • Android
  • iOS
  • Web Service

Y

Only Chrome, Firefox and Remote is available for use in 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 failed test cases fail in test suite ( override setting in test suite file ). There are 2 options for retry: true if you want run fail test case and otherwise false N
-reportFolder=<path> Specify the destination folder for saving report files. Can use absolute path or relative path (root being project folder). N
-reportFileName=<name> Specify the name for report files (.html, .csv, .log). If not provide, system uses the name "report" (report.html, report.csv, report.log). This option is only taken into account when being used with "-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 is 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)
-email Registered e-mail on Katalon Studio page N (If Katalon Studio is already activated)
-executionProfile

Starting from Katalon Studio version 5.4

Specify the execution profile to be executed with

N
-g_XXX

Starting from Katalon Studio version 5.9

Override Execution Profile variables.

Example:

-g_userName="admin"

N
--info -buildLabel="text" -buildURL="text"

Starting from Katalon Studio version 7.0

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

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

These proxy options below must be used with --config parameter e.g. --config -proxy.option=USE_SYSTEM. Example:

katalonc -noSplash  -runMode=console -consoleLog -noExit -projectPath= "C:\Users\Katalon Studio\Project\YourProject.prj" -retry= 0 -testSuitePath= "Test Suites/TS_RegressionTest" -browserType= "Chrome (headless)" --config -proxy.option=MANUAL_CONFIG -proxy.server.type=HTTP -proxy.server.address= "192.168.12.32" -proxy.server.port= "8888"
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, http://katalon.com Y
-proxy.excludes Example: 127.0.0.1, localhost, myserver.com N
-proxy.server.port Example: 80, 8080, 9999 Y
-proxy.username Example: MyProxyUsername Optional (YES if your proxy server requires authentication)
-proxy.password Example: MyProxyPassword Optional (YES if your proxy server requires authentication)

Starting from version 7.0.0, Katalon Studio supports an option to pass proxy details via a request object in Web Service testing. Refer to this document for further details.

The ability to exclude proxy in manual configuration is only available on version 7.2 and later.

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

Use the following steps to quickly generate commands to use in console mode:  

  1. Click on Build CMD from the main toolbar.

  2. The Generate Command for Console Mode is displayed. Configure your options as needed. where:

    SectionDescription
    Test SuiteThe Test Suite or Test Suite Collection to be executed
    Executed Platform

    The platform to execute the test on. Select an environment

     

    Other Options

  3. Click Generate Command after completing the configuration.

  4. You can Copy to Clipboard and paste to command prompt for execution.

Use console.properties file

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

  1. Generate 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.

User Contributed Notes