Command line execution

On this page, you’ll find out how to run an executable build from a command line interface. This page also contains all arguments and parameters available for this purpose, with examples of how to use them.

In this chapter

Execute your test through the command line

To run a test through a command line interface:

In the command line interface, switch to the output folder of the executable build, enter the name of the executable and press Enter.

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:

Command syntax

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

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.

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.

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 will only include messages with a report level ≥ Error.

RxDatabase.exe /rl:110

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

Custom report file name and path

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

• <report_name> sets a new report name.
• <path_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 will be 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 <report name>, 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 <file name> 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 will be 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 will be used.

Examples:

RxDatabase.exe /vr:KeepFailedTests

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

Configure settings

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 integration

/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=<id> is optional and synchronizes the test results to an existing test run on TestRail. <id> is the test run’s ID on TestRail. Cannot be used with /trrunname.

• /trrunname=<name> is optional and synchronizes the test results to a new test run on TestRail with a custom name, set by <name>. 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.

Jira integration

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

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

• These arguments will 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 are 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 will be ignored.
  <user name or email> is the Jira user name (server) or email (cloud).
  <password or API token> 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, ignores them.

Endpoints

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:<endpoint name> sets the endpoint with the specified name as the automation root, meaning that the test will be executed on this endpoint.
• If no name is specified, sets 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.

Configure global parameters for test suites

List global parameters

/lp|listglobalparams

• Lists all global parameters, including their current values.

Set global parameters

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

• Sets a parameter (<parameter name>) to a specified value (<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.

Configure local parameters for test containers

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.
• <test container> is the name or GUID of the test container.

Set local parameters

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

• Sets a parameter (<parameter name>) in a test container (<test container>) to a specified value (<value>). <test container> 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.

Selective test run

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 will be 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 will be 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:<test suite path>, as explained under Select test suite to run.

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, <rows> 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:<test suite path>, 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:<test suite> (see “Select a test suite to run”).
  
• You can specify only one run configuration. If you specify more than one, only the last one will be used.

Examples:

RxDatabase.exe /rc:All

If you only have one test suite, executes 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:<test suite path>, as explained above in “Select a test suite to run.”
• <module_name> 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.

Set run label, run ID, and SUT version

Run label

/rul|runlabel:<custom value>

• Sets a custom run label that will be displayed in the report.
  
• The run label will also replace 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 will be displayed in the report.

Ranorex Agent

/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 will be run on an Agent that has all specified tags. If there are more Agents that match the tag(s), the one with the fewest jobs will be 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.