Start a stub by using the command line

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

Note: The command-line tasks provide an option to wait for all of the stubs in a scenario to start before returning. This is the default option but you can disable it by specifying the async option. When in synchronous mode, the commands also alert users whether a scenario was started successfully.
The syntax to use 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://Host name 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://Host name 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 available options for starting a stub lists the options that you can use with the IntegrationTesterCmd command for starting a stub and List of available options for starting a managed stub lists the options available for starting a managed stub.

Table 1. List of available options for starting a stub
Options Description
--serverUrl/-u URL of the HCL Quality Server.
--domain/-d Domain name
--environment/-e Environment name
--component/-c Component the stub exists within (optional).
--operation/-o The operation the stub exists within on the server (optional).
--name/-n The name of the target stub to start.
--version/-v Version of the target stub to start (optional).
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.
--attributes/-t Comma-separated list of agent attributes that identify the agent to run on (optional).
--async/-a Run asynchronously; defaults to synchronous (flag).
--username/-l Specify the user name to authenticate with the server if the environment is locked and the domain security is disabled.
--securityToken

Specify the security token generated for the user 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 more information, see Domain level security and Managing environments.
--disablePerformanceOptimisations Specify "true" value to disable performance optimization when you start the stub (optional).
--workerThreadCount The amount of worker threads that are used to service requests to the stub (optional).
--dedicatedEngine

Use this option to run the stub by using a dedicated engine that is not used to run other stubs even if they are published from the same project. You can specify the JVM options by using the dedicatedEngineJvmOptions parameter and specify the values such as the maximum memory, initial memory, and the garbage collection policy for the engine.

Syntax example: 
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.
  • --force
  • --forceIf
  • --forceUnless
Use the force option to start the stub by attempting to ignore any warnings or errors that might occur.
  • force: To ignore all the problems that occur when you start the stub.
  • forceIf: Specify a space-separated list of problem identifiers to ignore when you start a stub.
  • forceUnless: Specify a space-separated list of problem identifiers to not ignore 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 specify if a specific problem identifier must either be ignored or considered when the stub is started. The problem identifier parameters are:
  • 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 on. This might occur if none of the agents support dedicated stub deployments.
Examples:
  • The command to ignore all the problems:
    IntegrationTesterCmd -u https://localhost:5443/RTCP -d MQ -e test 
--name stubReqRep --component SC --operation ReqRep --version "1.0" 
--force start-stub
  • To ignore a specific set of problems: 
    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
--secretsAuthorization

Offline user token for authorizing the client to access HCL OneTest™ Server (Optional).

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 Accessing HCL OneTest Server from IntegrationTesterCmd, ANT CLI, Maven CLI, or in a REST API call.
Table 2. List of available options for starting a managed stub
Options Description
--serverUrl/-u URL of the HCL Quality Server.
--domain/-d Domain name
--environment/-e Environment name
--name/-n The name of the target stub to start.
--id/-i The ID of the target (Optional).
--securityToken

Specify the security token generated for the user 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 more information, see Domain level security and Managing environments.
Starting from V9.2.1 or later, stubs are automatically restarted if the original instance stops working for any of the following reasons:
  • HCL OneTest™ API Agent failing
  • HCL Quality Server failing
  • a network outage

Error codes

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