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.

    Note icon

    Note

    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 icon

    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

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

    Note

    This illustrates that in principle, all arguments are optional. Running the test executable without any arguments will run it as it was configured at the time of the build. Arguments simply allow you to adjust this configuration in certain ways.

    In the following list, when something is designated as optional, it means you can omit it and the respective argument will still work. Conversely, if something isn’t optional, it will prevent 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

    Ranorex Studio advanced > ⇢ 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.

    %Y Current year (e.g. 2018)
    %M Current month (e.g. 11)
    %D Current day of the month (e.g. 28)
    %T Current time (e.g. 105214 for 10:52:14 am)
    %L Run label (see Set run label, run ID, and SUT version)
    %R Current run configuration

    %H

     

    Host name
    %S Test suite name
    %X Test suite result

    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.

    Reference

    Reporting is explained in

    Ranorex Studio fundamentals > ⇢ Reporting

    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.

    Reference

    Settings are explained in

    Ranorex Studio system details > ⇢ Settings and configuration

    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.

    Reference

    The TestRail integration is explained in

    Interfaces and connectivity > ⇢ TestRail integration

    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.

    Reference

    The Jira integration is explained in

    Interfaces and connectivity > ⇢ Jira integration

    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.

    Reference

    Endpoints are explained in

    Web and mobile testing > ⇢ Endpoints

    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.

    Reference

    Parameters are explained in

    Ranorex Studio advanced > Data-driven testing > ⇢ Parameters

    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.

    Reference

    Parameters are explained in

    Ranorex Studio advanced > Data-driven testing > ⇢ Parameters

    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.
    Note icon

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

    Reference

    Running test suites and run configurations are explained in

    Ranorex Studio fundamentals > Test suite > ⇢ Execute a test suite

    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.

    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