Command Line Execution

You use command line arguments to control the behavior of your test executable without opening Ranorex Studio. This allows you to integrate your tests into continuous integration (CI) environments, trigger specific test cases, or override project settings dynamically.

Execute your test

To run a test from the command line, navigate to the output folder of your project and enter the name of the executable followed by the desired arguments.

[ProjectName].exe [arguments]

If you don’t specify otherwise through arguments, this executes the test as it was configured (solution settings, run configuration, report settings, etc.) when you created the executable build.

Result:

The test is executed as if you had pressed the RUN button in Ranorex Studio. The terminal window shows the debug information.

ErrorLevel return value

When you run a test, the ErrorLevel return value indicates the test result:

0	Successful test run.
-1	Test run aborted due to error.
-2	Specified Ranorex Agent could not be found.
42	No valid license found.

Note: This is only relevant when executing tests in a continuous integration environment. The test automatically returns this value to the CI system.

Command syntax

Use the following syntax on this page to describe the available command line arguments.

/	Arguments are introduced with a forward slash, e.g. /help. Separate more than one argument with a space.
:	A colon introduces a parameter of an argument, e.g. /reportlevel:Debug.
|	The pipe denotes exclusive alternatives (one or the other, not both), e.g. /reportlevel:Debug|Info. Do not enter it in the command line interface.
||	The double pipe denotes inclusive alternatives (one or the other, or both), e.g. /reportfile:<path name>||<report name>. Do not enter it in the command line interface.
{ }	Braces denote optional arguments, e.g. /testrail {trrunid=<id>}. Do not enter braces in the command line interface.
<>	Angle brackets denote a placeholder, e.g. /reportlevel:<any integer value>. Do not enter angle brackets in the command line interface.

Sample syntax:

<test_project_name>.exe {/<argument1> /<argument2>:<parameter1>|<parameter2>} …

Almost all arguments are available in a short and a long form. You can use either as you wish and even mix them.

Note: All arguments are optional. They allow you to adjust the configuration at the time of build in certain ways.

In the following list, when something is designated as optional, it means you can omit it and the respective argument still works. Conversely, if something isn’t optional, it prevents the argument from working.

Display the help

/?|help

Lists all available command line arguments and their parameters in the command line interface.

Example:

RxDatabase.exe /?

Displays the available command line arguments for use with the test executable RxDatabase.exe.

Activate maintenance mode

/m|maintenancemode

Runs the test in maintenance mode.

Example:

RxDatabase.exe /m

Runs the test executable RxDatabase.exe in maintenance mode.

Reference: Maintenance mode is explained in the following article Maintenance mode

Reporting

Define report levels

/rl|reportlevel:None|Debug|Info|Warn|Error|Success|Failure|<any integer value>

• Sets the threshold for messages to be included in the report.
• None deactivates reporting entirely.
• The predefined report levels correspond to the following values: Debug=10, Info=20, Warn=30, Error=40, Success=110, Failure=120
• You can use either the name or the value of a report level to set it.

Examples:

RxDatabase.exe /rl:Error

Sets the report level to the threshold Error (corresponding to the value 40). The report only includes messages with a report level ≥ Error.

RxDatabase.exe /rl:110

Sets the report level to the threshold 110 (corresponding to Success) . The report only includes messages with a report level ≥ 110.

Custom report file name and path

/rf|reportfile:<path name>||<file name>

• sets a new report name.
• sets a new path where the report is saved. Requires a trailing backslash.
• You need to specify at least one of the parameters.
• If you only specify one of the parameters, the default value is used for the other.
• Setting a new path affects all report files, i.e. the .rxlog, .rxlog.data, .css, .xsl files, and RanorexReport.png.
• For, you can also use placeholders. These are explained below under Report name placeholders.

Examples:

RxDatabase.exe /rf:myReport_%Y

Saves the report files under the names “myReport_YYYY.rxlog” and “myReport_YYYY.rxlog.data”, e.g. “myReport_2019.rxlog”. The save path remains the default one.

RxDatabase.exe /rf:myReports\myReport_%Y-%M-%D

Creates the folder \myReports\ in the output folder. The report files are stored there under the name “myReport_YYYY-MM-DD.rxlog” and “myReport_YYYY-MM-DD.rxlog.data” (e.g. “myReport_2019-11-23.rxlog”

Zipped report

/zr|zipreport {/zrf|zipreportfile:<path name>||<file name>}

• The first argument creates a zipped copy of the report with the file ending .rxzlog.
• The second argument is optional. It requires /zr and allows you to set a custom save path and file name in the same way as for the normal report (see above under Custom report file name and path).

Examples:

RxDatabase.exe /zr

Creates a zipped report file (.rxzlog) with the default name in the default report folder in the output folder.

RxDatabase.exe /zr /zrf:myZipReportsmyReport%Y

Creates the folder myZipReports in the output folder and stores the zipped report there under the file name “myReportYYYY.rxzlog”, e.g. “myReport2019.rxzlog”.

JUnit-compatible report

/ju/junit

• Creates a JUnit-compatible copy of the report in the default report folder.
• The file ending is .junit.xml

Examples:

RxDatabase.exe /ju

Creates a JUnit-compatible copy of the report with the ending .junit.xml in the default report folder in the output folder.

Report name placeholders

You can use the following placeholders in the parameters of the /rf and /zrf arguments.

Video reporting

/vr|videorecording:Off|KeepFailedTests|KeepAllTests

{/vrs|viderecordingsource:Auto|Screen1|Screen2|Screen3|Screen4}

• The first argument sets the recording mode. Off disables video reporting, KeepFailedTests saves videos of failed test cases only, KeepAllTests saves videos for all test cases.
• The second argument is optional. It sets the source screen from which the videos are recorded. The screen numbers correspond to the display settings in Windows. Auto uses the screen the mouse is on at the start of the test run. If you don’t specify it, the source that was set when the test was built is used.

Examples:

RxDatabase.exe /vr:KeepFailedTests

Activates video reporting, records from Screen 2, and saves only videos of failed test cases.

List all configurable settings

/lcp|listconfigparams

• Lists all configurable settings, including their current values.

Configure settings

/cfg|config:<setting name>=<value>

• Assigns the specified value to the specified setting.

Examples:

RxDatabase.exe /cfg:adapter.defaultsearchtimeout=1500ms

Runs the test executable with the value 1500ms assigned to the setting adapter.defaultsearchtimeout.

RxDatabase.exe /cfg:adapter.defaultsearchtimeout=1500ms /cfg:recorder.replay.generatereport=False

This example illustrates that you can configure several settings at once by separating the individual arguments with a space.

/testrail /truser=<user name> /trpass=<password> {/trrunid=<id>|/trrunname=<name>}

• /testrail synchronizes the test results to a new test run (default name) on TestRail. It requires /truser and /trpass to log into the specified TestRail account.
• /trrunid= is optional and synchronizes the test results to an existing test run on TestRail. is the test run’s ID on TestRail. Cannot be used with /trrunname.
• /trrunname= is optional and synchronizes the test results to a new test run on TestRail with a custom name, set by . Cannot be used with /trrunid.

Examples:

RxDatabase.exe /testrail /truser=johndoe /trpass1234 /trrunname=Nightly

Runs the test and synchronizes the results to a new test run with the name Nightly on TestRail. Uses johndoe as username and 1234 as password to log in to TestRail.

Reference: The TestRail integration is explained in Interfaces and connectivity > TestRail integration

/jit|jiratasks:on|off|createlink||autohandle

{/jiu|jirauser=<user name or email>} {/jip|jirapass=<password or API token>}

• These arguments only work if you’ve set up the Jira integration in Ranorex Studio beforehand and if the Jira.jsd file is included in the executable build of your test (which it is, by default).
• /jit|jiratasks enables manual and/or automatic issue handling for the test run and overrides the respective settings in the Jira.jsd file.
  on|off = Enables|Disables both manual and automatic handling.
  createlinks = Enables manual handling.
  autohandle = Enables automatic handling
• /jiu|jirauser and /jip|jirapass is optional if the machine the test is run on has Jira credentials for the respective Jira instance saved in the Windows Credentials Manager. Otherwise, they are required. If credentials exist and you use these arguments, the existing credentials are ignored.
  is the Jira user name (server) or email (cloud).
  is the password for the user name (server) or the API token (cloud).

Examples:

RxDatabase.exe /jit:createlink 

Runs the test and enables manual issue handling if credentials exist on the machine.

RxDatabase.exe /jit:autohandle /jiu=johndoe /jip=1234

Runs the test and enables automatic issue handling. Uses johndoe as user name and 1234 as password to log in to Jira. If other credentials already exist on this machine, ignore them.

Reference: The Jira integration is explained in Interfaces and connectivity > Jira integration

Run a test on an endpoint

/ep|endpoint{:<endpoint name>}

/ep:<WebDriver endpoint> {/epc|endpointconfig:<configuration name>}

/ep:<WebDriver endpoint> {/epcfp|endpointconfigfilepath:<file path>}

• /ep: sets the endpoint with the specified name as the automation root, meaning that the test is executed on this endpoint.
• If no name is specified, set localhost as the automation root, i.e. the current machine.
• The second argument is optional and requires a WebDriver endpoint as automation root. It sets an endpoint configuration by name. You need to have added the configuration in the endpoints pad in Ranorex Studio. Cannot be used with /epcfp.
• The third argument is optional and requires a WebDriver endpoint as automation root. It sets an endpoint configuration by filepath. The file must be in JSON format. Cannot be used with /epc.

Example:

RxDatabase.exe /ep:iPhone5

Runs the test on the endpoint with the name iPhone5.

RxDatabase.exe /ep:WebDriver2 /epc:Windows7Chrome

Runs the test on the WebDriver endpoint WebDriver2 with the endpoint configuration Windows7Chrome.

Reference: Endpoints are explained in Web and mobile testing > Endpoints

List global parameters

/lp|listglobalparams

• Lists all global parameters, including their current values.

Set global parameters

/pa|param:<parameter name>=<value>

• Sets a parameter () to a specified value ().
• Overrides (but does not replace) existing values.
• Separate more than one parameter with a space.

Example:

RxDatabase.exe /pa:Version=9 

Runs the test with the value of the global parameter Version set to 9, regardless of what the value was when the executable build was created.

Reference: Parameters are explained in Ranorex Studio advanced > Data-driven testing > Parameters

List local parameters

/ltcpa|listtestcaseparams:<test container>

• Lists all parameters and their values of a test container, i.e. a test case or smart folder.
• is the name or GUID of the test container.

Set local parameters

/tcpa|testcaseparam|testcontainerparam:<test container>:<parameter name>=<value>

• Sets a parameter () in a test container () to a specified value (). is the name or GUID of a test container.
• Overrides (but does not replace) existing values.
• Separate more than one parameter with a space.

Example:

RxDatabase.exe /tcpa:EnterName:Name=Jane

Runs the test with the value of the local parameter Name in the test container EnterName Version set to Jane.

Reference: Parameters are explained in Ranorex Studio advanced > Data-driven testing > Parameters

Select test suite to run

/ts|testsuite:<test suite path>

• Selects a specific test suite to execute.
• If the test suite file is located in a subfolder of the output folder, then you need to specify the path to it. Otherwise, the name of the file is sufficient.
• You can specify only one test suite to execute with this argument. If you specify more than one, only the last one is executed.

Examples:

RxDatabase.exe /ts:Introduction.rxtst

Runs the test executable and executes only the test suite Introduction. The test suite file is located directly in the output folder (bindebug), so the file name is sufficient.

RxDatabase.exe /ts:TestSuitesIntroduction.rxtst

Runs the test executable and executes only the test suite Introduction. The test suite file is located in the subfolder TestSuites in the output folder, so you need to specify this folder.

RxDatabase.exe /ts:RxDatabase.rxtst /ts:Introduction.rxtst

Runs the test executable and executes only the test suite Introduction. Ignores the specified test suite RxDatabase because only the last test suite is executed when more than one is specified.

Select test container to run

/tc|testcase|testcontainer:<test container name or GUID>

• Selects only a specific test container to execute. Also executes descendant test containers that were checked to be run when the executable build was created. The specified test container itself does not need to be checked.
• You can specify only one test container. If you specify more than one, only the last one is executed.
• If a test container has a non-unique name, you must use its GUID to specify it. You can find the GUID in the test container’s properties.
• If the test container is part of the test suite initially created as part of the project/solution, then you can omit the /ts argument. Otherwise, you need to specify the test suite with the argument /ts:, as explained under Select test suite to run.

Note: This only executes the specified test container and checked descendant test containers. It does not execute ancestor or sibling test containers, including setup or teardown regions. This can easily result in test failure.

Examples:

RxDatabase.exe /tc:Introduction

Executes the test container Introduction and all checked descendant test containers in the test suite initially created as part of the project/solution.

RxDatabase.exe /ts:ImageBased.rxtst /tc:Image_B

Executes the test container Image_B and all checked descendant test containers in the test suite ImageBased. The test suite ImageBased.rxtst was not initially created as part of the project, but added later, so it needs to be specified.

RxDatabase.exe /ts:ImageBased.rxtst /tc:Image_B /tc:Image_A

As above, but ignores Image_B and executes only Image_A because only the last test container is executed when more than one is specified.

Set a data range in a test container’s data source

/tcdr|testcasedatarange|testcontainerdatarange:<test container>=<rows>

• Executes a test container for only the specified rows from its data source.
• <test container>is the name or GUID of the test container, is the rows in the data source. See below for examples on how to specify rows.
• This argument only works if the respective test container is run, i.e. it had to be checked when you created the executable build, or you have to ensure it’s run through other arguments. You can do so with the /tc argument as explained under Select test container to run, or with the argument /rc as explained under Select run configuration.
• If the test container is part of the test suite initially created as part of the project/solution, then you can omit the /ts argument. Otherwise, you need to specify the test suite with the argument /ts:, as explained under Select test suite to run.

Examples:

RxDatabase.exe /ts:RxDatabase.rxtst /rc:Database /tcdr:Data-driven_DB_Test=3-5

Executes the test suite RxDatabase in the run configuration Database. Uses only the rows 3 to 5 (from 8 in total) from the data source of the test case Data-driven_DB_Test. The specified run configuration ensures that the referenced test container is run.

How to specify data ranges:

Data-driven_DB_Test=3

Uses only row 3.

Data-driven_DB_Test=3-5

Uses rows 3 to 5, i.e. 3, 4, and 5.

Data-driven_DB_Test=3,5

Uses rows 3 and 5.

Data-driven_DB_Test=3,5-8

Uses rows 3, 5, 6, 7, and 8.

Select run configuration

/rc|runconfig:<run configuration>

• Executes a test suite in the specified run configuration.
• If you only have one test suite, you don’t need to specify the test suite. If you have more than one test suite, you need to specify the test suite that contains the respective run configuration with the argument /ts: (see “Select a test suite to run”).
• You can specify only one run configuration. If you specify more than one, only the last one is used.

Examples:

RxDatabase.exe /rc:All

If you only have one test suite, execute it in the run configuration All. If you have multiple test suites, results in an error.

RxDatabase.exe /ts:ImageBased.rxtst /rc:All

Executes the test suite ImageBased in the run configuration All.

Select module to execute

/mo|module:<module name>

• Executes a recording or code module in a test container.
• You need to specify the respective test container with the argument /tc as explained under Select a test container to run.
• If the module is part of the test suite initially created as part of the project/solution, then you can omit the /ts argument. Otherwise, you need to specify the test suite with the argument /ts:, as explained above in “Select a test suite to run.”
• takes the name or GUID of the module.

Examples:

RxDatabase.exe /ts:ImageBased.rxtst /tc:Image_B /mo:TestDynamicImage

Executes the recording module TestDynamicImage in the test container Image_B in the test suite ImageBased.

Reference: Running test suites and run configurations are explained in Ranorex Studio fundamentals > Test suite > Execute a test suite

Run label

/rul|runlabel:<custom value>

• Sets a custom run label that displays in the report.
• The run label also replaces the placeholder %L in the report name (see Reporting further above).

Run ID

/runid:<custom value>

• Sets a custom run ID. Not displayed in the default report.

SUT version

/sutversion:<custom value>

• Sets a custom SUT version that displays in the report.

/a|agent:"<agent name>"|["agent tag"]|?

/a|agent:"<agent name>"|["agent tag"] /artifacts:<file pattern>

• Runs the test on the specified Ranorex Agent. Only one agent can be addressed.
• <agent name> takes the name of the Agent, or the name or IP of the machine it is installed on. Quote the value if it contains spaces.
• If the specified Agent can’t be found, automatically runs an Agent discovery and lists all available Agents in the current network.
• The parameter ? manually starts an Agent discovery.
• [“agent tag”] is any tag added to an agent. The test is run on an Agent that has all specified tags. If more Agents match the tag(s), the one with the fewest jobs is used. Separate tags with a trailing comma. Quote tag if it contains spaces.
• If the specified Agent is found, automatically zips the executable build, deploys it to the Agent machine, and starts the test run.
• /artifacts combines with the arguments to address an agent by name or tag. It instructs the Agent to collect and download all files that match the specified file pattern(s) after test execution. Separate more than one file pattern with semicolons. Default value is: .rxzlog;.junit.xml. This is the Ranorex Studio report in different formats. Files with this ending are always downloaded.

Example:

RxDatabase.exe /a:"QA Agent"

Executes the test on the Agent named QA Agent.

RxDatabase.exe /a:["Smoke Tests", Android]

Executes the test on an Agent that has the tags Smoke Tests and Android.

Reference: Configuring Ranorex Agents is explained in Ranorex Studio fundamentals > Ranorex Studio Overview > Ranorex Agents
Running tests on Agents is explained in Ranorex Studio fundamentals > Ranorex Studio Overview > Agent-based remote execution.