Start a stub by using the command line

You can start a stub by using the HCL OneTest™ API command line.

The syntax to start a stub by using the command line is as follows:

IntegrationTesterCmd [Options] start-stub

Here is an example syntax of synchronous mode (where there is only one stub in the environment, and it has only one version):

IntegrationTesterCmd --serverUrl "https://Hostname or IP address:5443/RTCP/" --domain <Domain name> --environment <Environment name> --name <Stub name> start-stub

Here is an example syntax of asynchronous mode, where component and operation are used to precisely identify a stub, a specific version is specified, and the user has locked the environment:

IntegrationTesterCmd --serverUrl "https://Hostname or IP address:5443/RTCP/" --domain <Domain name> --environment <Environment name> --component <Component name> --operation <Operation name> --name <Stub name> --version <Stub version number> --username <User name> --async start-stub

Managed stubs

Starting from version 10.0.0 or later, you can use the following command to start a managed stub instance:

IntegrationTesterCmd [Options] switch-on-stub

For more information about managed stubs, see Server-based stubs.

List of supported options for starting a stub lists the options that you can use with the IntegrationTesterCmd command for starting a stub and List of supported options for starting a managed stub lists the options that you can use for starting a managed stub.

Table 1. List of supported options for starting a stub
Options Action for the command option Usage criteria Default value
--serverUrl/-u Enter the URL of HCL® Quality Server.

For example, if you installed HCL® Quality Server on your local host, then the command option can be:

--serverUrl https://localhost:5443/RTCP or -u https://localhost:5443/RTCP

 Mandatory NA
--domain/-d Enter the name of the domain in which the stub was created in HCL OneTest™ API.

For example, if you created the stub in the domain called default, then the command option can be:

--domain default or -d default

 Mandatory NA
--environment/-e Enter the name of the environment in which the stub was created in HCL OneTest™ API.

For example, if you created the stub in the environment called local, then the command option can be:

--environment local or -e local

 Mandatory NA
--component/-c Enter the name of the service component in which the stub was created in HCL OneTest™ API.

For example, if you created the stub in the service component called MyServiceComp, then the command option can be:

--component MyServiceComp or -c MyServiceComp

 Optional NA
--operation/-o Enter the name of the operation in which the stub was created in HCL OneTest™ API.

For example, if you created the stub in the operation called StubOperation, then the command option can be:

--operation StubOperation or -o StubOperation

 Optional NA
--name/-n Enter the name of the stub that you want to start on HCL® Quality Server.

For example, if you created the stub with the name as Stub_1, then the command option can be:

--name Stub_1 or -o Stub_1

 Mandatory NA
--version/-v Enter the version of the stub that you want to start on HCL® Quality Server.
For example, if you published different stub versions from 1.0 to 1.5 and you want to start the stub with version 1.3, then the command option can be:--version 1.3 or -v 1.3
Note: If you are using HCL OneTest™ API 8.5.0.1 or later, and the HCL® Quality Server command line or Apache Ant tasks are used to start a stub, and if no stub version information is provided, it is the latest version of a stub that is run. If you are using 8.5.0 or earlier, and the HCL® Quality Server command line or Apache Ant tasks are used to start a stub, and if no stub version information is provided, it is the earliest version of a stub that is run.
 Optional The latest version of the stub is started if no version is entered.

For example, the stub with version 1.5 is started if no version is specified when you published different stub versions from 1.0 to 1.5.
--attributes/-t Enter the agent attributes in a comma-separated list. HCL® Quality Server identifies an agent with the specified attributes on which the stub must be run. Use this option when you want to run the stub on an agent.

For example, if you configured an agent with a particular attribute such as Windows 10, and you want this agent to be selected for running the stub, then the command option can be:

--attributes Windows10 or -t Windows10

 Optional NA
--async/-a Use this flag if you are running a stub that is in a scenario and you do not want to wait until all the stubs in the scenario are started. When this flag is used the stub that you want to start runs without waiting for the other stubs to start. If this flag is not used, the stub runs synchronously.
Note: The command-line tasks provide an option to wait for all of the stubs in a scenario to start before starting a stub. This is the default option but you can disable it by specifying the async option. When you start a stub in the synchronous mode, you are alerted when a scenario was started successfully.
 Conditional The stub runs synchronously.
--username/-l Enter your user name to authenticate with the HCL® Quality Server in the following conditions:
  • If you have configured HCL® Quality Server to use your user credentials for a connection.
  • If the environment is locked and the domain security is disabled.

For example, if you have set up Tester1 as a user on HCL® Quality Server, then the command option can be:

--username Tester1 or -l Tester1

 Conditional NA
--securityToken

Specify the security token generated for you to authenticate with HCL® Quality Server when the domain security is enabled. In the locked environment mode, the operation can be performed by the user who locked the environment.

For example, if the security token that is generated for you is X1akJHlq932i, then the command option can be:

--securityToken X1akJHlq932i

 Conditional NA
--disablePerformanceOptimisations Include this flag when you want to disable performance optimization. Optional Performance optimization is enabled.
--workerThreadCount Enter the number of worker threads that must be used to service requests to the stub. If no number is specified with this option, the number of worker threads defined in the stub is considered during the run.

For example, if the stub has 10 worker threads defined, and you want to use 12 worker threads for its run, then the command option can be:

--workerThreadCount 12

 Optional The number of worker threads defined in the stub.
--dedicatedEngine

Use this flag when you want to run the stub that uses a dedicated engine. The dedicated engine is not used to run other stubs even if they are published from the same project. If you do not use this flag in the command the stub is not run on any dedicated engine.

If you want to run the stub on a dedicated engine, you can also specify the JVM options by using the dedicatedEngineJvmOptions parameter. You can then specify the values for the attributes such as the maximum memory, the initial memory, and the garbage collection policy that must be applied for the dedicated engine.

For example, if you want to specify the attributes for the JVM to have 2GB RAM and 256GB disk space, the command can be:

IntegrationTesterCmd --serverUrl https://localhost:5443/RTCP --domain default --environment local --name ReqRepStub --version "1.0" --dedicatedEngine --dedicatedEngineJvmOptions "-Xmx2g -Xms256m -Dmy.option=\"my\ value\"" start-stub

Note:
  • Use spaces to separate the JVM parameters.
  • The quotations and the space in the value must be escaped with a backslash as specified in the example.
 Optional The stub is not run on any dedicated engine.
  • --force
  • --forceIf
  • --forceUnless
Use the force flag or option to start the stub by ignoring any warnings or errors that might occur. You can use any of the following variants:
Option/Flag Action
force Use this flag to ignore all the problems that occur when you start the stub.
forceIf Specify this option along with a space-separated list of problem identifiers that must be ignored when you start a stub.
forceUnless Specify this option along with a space-separated list of problem identifiers that must not be ignored when you start a stub. If the parameter list is empty, the force setting is not considered and none of the errors are ignored.
You can use the following identifiers that must be either ignored or considered when the stub is started:
Parameter Description
agent-criteria-unsatisfied Indicates that there were not enough agents available to run the stub or the specified agents were not found.
reused-agent Indicates that the selected agent is already running that stub. Running multiple instances of that stub at the same time on the same agent does not provide any benefit over running it a single time on that agent.
engine-criteria-unsatisfied Indicates that none of the agents could satisfy the engine requirements to start the stub. This might occur if none of the agents support dedicated stub deployments.
Examples:
  • The command to ignore all the problems is as follows:

    IntegrationTesterCmd -u https://localhost:5443/RTCP -d MQ -e test --name stubReqRep --component SC --operation ReqRep --version "1.0" --force start-stub

  • The command to ignore a specific set of problems is as follows:

    IntegrationTesterCmd -u https://localhost:5443/RTCP -d MQ -e test --name stubReqRep --component SC --operation ReqRep --version "1.0" --forceIf "reused-agent agent-criteria-unsatisfied" start-stub

 Conditional NA
--secretsAuthorization

Enter the offline user token for authorizing the client to access HCL OneTest™ Server when the stub needs to access contents such as secrets.

For example, the command to start a stub using the --secretsAuthorization parameter follows:

IntegrationTesterCmd -u ${SERVER_URL} -d ${DOMAIN_NAME} -e ${ENV_NAME} -n ${STUB_NAME} --secretsAuthorization ${OFFLINE_USER_TOKEN} start-stub

For more information, see the related links.

 Conditional NA
Table 2. List of supported options for starting a managed stub
Options Action for the command option Usage criteria Default value
--serverUrl/-u Enter the URL of HCL® Quality Server.

For example, if you installed HCL® Quality Server on your local host, then the command option can be:

--serverUrl https://localhost:5443/RTCP or -u https://localhost:5443/RTCP

 Mandatory NA
--domain/-d Enter the name of the domain in which the stub was created in HCL OneTest™ API.

For example, if you created the stub in the domain called default, then the command option can be:

--domain default or -d default

 Mandatory NA
--environment/-e Enter the name of the environment in which the stub was created in HCL OneTest™ API.

For example, if you created the stub in the environment called local, then the command option can be:

--environment local or -e local

 Mandatory NA
--name/-n Enter the name of the managed stub that you want to start on HCL® Quality Server.

For example, if you created the managed stub with the name as Stub_1, then the command option can be:

--name Stub_1 or -n Stub_1

 Optional NA
--id/-i

Enter the ID of the target stub that you want to start.

For example, the command to start a stub using the --secretsAuthorization parameter follows:
IntegrationTesterCmd -u ${SERVER_URL} -d ${DOMAIN_NAME} -e ${ENV_NAME} -n ${STUB_NAME}
 --secretsAuthorization ${OFFLINE_USER_TOKEN} start-stub

For more information, see the related links.

 Optional NA
--securityToken

Specify the security token generated for you to authenticate with HCL® Quality Server when the domain security is enabled. In the locked environment mode, the operation can be performed by the user who locked the environment.

For example, if the security token that is generated for you is X1akJHlq932i, then the command option can be:

--securityToken X1akJHlq932i

 Conditional NA
Note: If you want to use the options that are supported for starting a stub to start a managed stub, you must use the REST APIs. For more information, see REST services.
Starting from 9.2.1 or later, stubs are automatically restarted if the original instance stops working for any of the following reasons:
  • HCL OneTest™ API Agent fails.
  • HCL® Quality Server fails.
  • A network outage.

Error codes

For details of any error codes, see Exit codes for Command-line client and Ant client.