VirtRunner Command Line

About VirtRunner

You use VirtRunner to run virtual APIs (virtual services) from a command line. You can find the file in the <ReadyAPI directory>\bin folder. The file name is virtrunner.bat on Windows, and virtrunner.sh on Linux and Mac.

Important

To use VirtRunner, you need the ReadyAPI Virtualization pro.png license.

General Syntax

The runner’s command line has the following format:

virtrunner.bat [optional-arguments] <test-project>

Running Multiple Virtual Services

If you are going to run multiple virtual services, make sure they have different ports or paths. You can specify a port and path for your virtual service in its properties. Also, use the -m command-line argument to specify the port and path your virtual service will use during the run.

Required arguments

test-project

The fully qualified path to the project that contains the virtual services to be run. If the file name or path includes spaces, enclose the entire argument in quotes.

Examples:

C:\Work\readyapi-project.xml
C:\Work\composite-project

Optional arguments

-b

Commands the runner to disable blocking. This is required if you are going to run VirtRunner with the nohup command on Linux or as a service on Windows.

--clientId, -ci<Client ID>

Specifies the Client ID for SLM On-premises license Server when configured for OIDC. Please see here for instructions on configuring SLM on-premises for OIDC and how to access the credentials.

Note

SLM on-premises 2.0 or later must be configured for the OIDC/Okta environment.

--clientSecret, -cs<Client Secret>

Specifies the Client Secret for SLM On-premises license Server when configured for OIDC. Please see here for instructions on configuring SLM on-premises for OIDC and how to access the credentials.

Note

SLM on-premises 2.0 or later must be configured for the OIDC/Okta environment.

-D<args>

Specifies a value of a system property for the test run. The specified value will override the variable’s value during the run.

Usage: -D<variable>=<value>. If the value includes spaces, enclose the entire argument in quotes. To override several variable values, specify the -D argument several times.

Example:

-Dtest.history.disabled=true

-f<directory>

Specifies the root directory, to which the runner will export results of the virtual service.

Example:

-fC:\Work\ReadyAPI-run-results

-G<args>

Specifies a value of a global property for the test run. The specified value will override the variable’s value during the run.

Usage: -G<variable>=<value>. If the value includes spaces, enclose the entire argument in quotes. To override several variable values, specify the -G argument several times.

Example:

-Gglobal.property=true

-g

Commands the runner to create coverage reports.

Important

Coverage reporting only works when you run a SOAP virtual service.

To use coverage reports in your tests, you need a ReadyAPI Virtualization license. Sign up for a free trial to try how it works.

-m<args>

Specify a virtual service for the run. Use the following syntax:

-m<virt-name>[:<port>][:<path>][,<virt-name>[:<port>][:<path>][,…]]

where –

  • virt-name – The name of the virtual service to start. Specify the name as it is shown in the virtual service editor. If the name includes spaces, enclose it in quotes (see an example below).

  • port – Optional. The port the virtual service will use during the run. This parameter overrides the port number specified in properties of the virtual service.

    • If your project contains several REST or SOAP virtual services using the same port, specify different paths for them.

    • If there is a JDBC or TCP virtual service sharing a port number with any virtual service, neither of them will start.

  • path – Optional. The “path” part of the service’s URL. This option overrides the path specified by the service’s properties. The path must start with a slash –/.

Example:

-m"Soap Service":8089:/soap-service

To run several virtual services, separate them with commas: -m<virt1:port1:path1>,<virt2:port2:path2>,… (see an example below).

If you do not use the -m argument, the runner will start all the virtual services from your project. The runner will use the ports and paths that properties of these virtual services specify.

-o

Commands the runner to open generated coverage reports in your default browser.

Important

This argument is significant only if you also use the -g argument.

-P<args>

Specifies a value of a project property for the test run. The specified value will override the property’s value during the run. Typically, it is used to override custom properties.

Usage: -P<variable>=<value>. If the value includes spaces, enclose the entire argument in quotes. To override several variable values, specify the -P argument several times.

Example:

-Pproject.property=true

-S

Commands the runner to save the project after the virtual service run is over. This may be useful if your service stores data to the project during the run.

-s<settings file>

Specifies the workspace settings to use during the virtual service run. By default, these settings are stored in the <User directory>/.readyapi/readyapi‑settings.xml file. This argument allows you to specify another settings file for the run. It may be useful to use different proxy, SSL, HTTP and other settings without changing them in ReadyAPI.

-v<password>

Specifies the password for your settings file.

-x<project password>

Specifies the project password if the project is encrypted.

Example

  • The following command runs all the virtual services in the specified project:

    virtrunner.bat "C:\Projects\Sample-REST-project.xml"

  • The following command runs two virtual services from the specified project:

    • The The First Service virtual service that uses the 8081 port and the /service-a path.

    • The SecondService virtual service that uses the 8082 port and the /service-b path.

    virtrunner.bat -m"The First Service":8081:/service-a,SecondService:8082:/service-b "C:\Projects\my-project.xml"

See Also

© 2025
Publication date: