Configuring a run of a virtual service

Edit online

When you have virtual service resources that are in the repositories added to your project on IBM® DevOps Test Hub (Test Hub), you must configure a run of the virtual service to start an instance of the virtual service in the Test Hub cluster, a remote Kubernetes cluster, or an API agent.

Before you begin

You must have completed the following tasks:

Ensured that you are assigned a role as a Project Creator in the team space. See Managing members and their roles in a team space.
Ensured that you are assigned a role as a Project Owner or Tester in the project. See Managing access to the server projects.
Created virtual services that use any of the supported transports for tests in Test Integrations and APIs, committed the test resources to the remote repository, and added the repository to your project.
Read about the virtual services that are supported on Test Hub. See Supported virtual services.
Completed the prerequisite tasks before you configure a run of the HTTP virtual services. See Prerequisites for running HTTP virtual services in a Kubernetes cluster.
Read and completed the tasks mentioned in Considerations for using a remote Kubernetes cluster, if you want to use a remote Kubernetes cluster as a location to run the test.
Read and completed the tasks mentioned in Considerations for running virtual services on remote API agents, if you want to use a remote API agent as the location to run the virtual services.

Procedure

Log in to Test Hub.
The Projects page of the initial team space is displayed.
Open the project that contains the virtual service resources in the test assets by clicking My Projects > project_name.

The Overview page is displayed.
Click Virtualization > Resources in the navigation pane.

The Resources page is displayed.
Select the branch of the repository that contains the virtual services that you want to run from the list in the Branch field.

All virtual services in the selected branch are displayed on the Resources page.
Identify the virtual service by completing any of the following steps:
- Search for the virtual service by entering the name or the path of the virtual service in the repository in the Search field box.
- Create a filter query by using the New filter option and complete the following steps:
  1. Create a rule with an appropriate operator.
  2. Select criteria such as Name, Path, Instance number, or Instance state. Select the condition and enter the value for the criteria. Apply the filter query.
    The virtual services that match the filter criteria are displayed.
  3. Save the filter query for retrieving it from the saved filters list.
- Retrieve a saved filter by using the Open filters icon by completing the following steps:
  Note: To open the filter query, you must have created and saved a filter query.
  1. Select the saved filter.
  2. Apply the filter.
    The virtual services that match the filter criteria in the filter that is applied are displayed.
You have identified the virtual service resources that you want to run.
Click the Open action menu icon in the row of the identified virtual service, and then click Execute icon .

The Execute virtual service dialog is displayed.
Select the version of the virtual service that is in the repository that you want to start by performing any of the following actions:
- Expand the list in the Version field, find the version of the test resources, and then select the version.
  Use the following details about the version of the test resources that are displayed to identify the version that you want:
  
  Commit message.
  
  Tags labeled for the version committed.
  
  The user who committed the version to the repository.
  
  Relative time of the commit. For example, 2 hours ago or 3 days ago.
  The list displays the versions of the test resources committed by all users to the branch in the repository. The versions are arranged with the latest version committed followed by the versions committed previously.
- Expand the list in the Version field, and then search for the version that you want to select by entering a partial or the complete commit message of that version.
  The version that matches the search criteria is displayed and it is selected for the test run.
Select the environment that was used to bind the physical and logical resource in the API project, in the ENVIRONMENT tab.

Important: The configuration that you set for the run in the Execute virtual service dialog is preserved when you run the same virtual service again. The configurations that you set are not available to other members when they want to run the virtual service. For example, if you selected an environment, the same environment is selected when you run the virtual service again.
Enter a label, if required.

A label that you enter for the test run that helps you to identify the virtual service instance on the Instances page. The label that you entered is displayed for the virtual service under the Labels column on the Instances page. After you have created a label, any member of the project can use that label.

Follow the instructions if you want to modify the configurations for the behavior of the virtual service:

Click the BEHAVIOR tab, if it is not already open.

Configure or change the settings for the following options:

Note: The settings displayed are the settings that were configured for the virtual service when it was authored in Test Integrations and APIs.

Option

Description

Performance

The following settings are available for handling of requests by the virtual service:


Option	Description
Optimize performance	If enabled, attempts are made to reduce the amount of processing between the time the virtual service receives a request and the time it sends a response. Specific optimizations depend on the message contents, as in the following examples: When the virtual service receives requests, all validations are disabled, and for all XML payloads, the store and filter actions are converted to use XPath expressions. When the virtualization sends responses, any store actions set on a message are disabled, and any XML content is collapsed when the virtual service is compiled instead of being collapsed every time that a response is sent. The optimization is disabled as the default action for this setting and you can enable the performance optimization if you fully understand the implications of optimizing the performance.
Threads	The maximum number of threads used in processing requests received by the virtual service. The default number of threads is `10`.

Operation

Specifies an operation referenced by the virtual service.

Response time

Specifies the response time behavior for responses sent by the virtual service for the selected operation.

You can modify the value by selecting a value from the following options:

Option	Description
No delay	Select this option for a response with no delay.
Minimum delay	Select this option for a delay in the response by entering the required delay in milliseconds (ms).
Uniform distribution	Select this option for a uniformly distributed response time by specifying the minimum and maximum delay in milliseconds (ms).
Gaussian distribution	Select this option for a response time with Gaussian distribution by specifying the minimum and maximum delay in milliseconds (ms).

Passthrough

Specifies the pass through behavior for the selected operation when requests are not handled within the virtual service.

You can modify the value by selecting a value from the following options:

Discard	This option stops the system under test from receiving the intercepted message. This option can disrupt the calling system. For example, the system might time out while it waits for a reply.
Pass Through	This option passes the intercepted message to the system under test, with an optional delay.
Simulate Error	This option returns an error to the calling system. The message is not passed to the system under test.

Follow the instructions, if the virtual service references datasets.
- You can use the dataset referenced in the asset.
- You can choose to override the dataset with another data source. If alternative data sources are available, select from the set of overrides available.
Follow the instructions if the virtual service requires a variable that must be passed at run time.
1. Click the VARIABLES tab, if it is not already open.
2. Choose one of the following methods to add the variables:
  - To add new variables manually, click the Add Variable icon , enter the name, and value of the variable.
  - To add new variables from your local computer or from the Git repository that is associated with your server project, click the Upload icon and select the Upload from local system or Browse from server to select the variable file.
    Note: You must have created a file with the variables before you can select the file.

Click Advanced to make the following advanced configurations:

Enter any JVM arguments that must be passed at run time in the JVM Arguments field.

Note: Each JVM argument should be separated with white space.

For example, you can set a maximum Java heap size.
Enter the environment variables that must be passed at run time in the Environment Variables field, if applicable.

For example, enter the environment variables when the third-party libraries that are used in the run refer to the environment variables for configuration.

Select the stub logging level for the virtual service from the following options in the Logging list:


Option	Description
None	Specifies that the virtual service does not write log messages.
Normal	Specifies that the virtual service writes informational messages.
Debug	Specifies that the virtual service writes informational and debugging messages.

Enter other configuration options as parameters and their values in the Additional Configuration Parameters fields, if applicable.

You can refer to the additional parameters that you can use for virtual services from the topic in the related links.

For example, if you want to start the virtual service to run in a new container, you can specify the following parameter and its value:


Parameter name	Value
stub.dedicated.container	true

Note: Click Add to add additional parameters.

Note: You must separate the arguments or variables with a white space when you enter them in the same line or start each argument or variable on a new line.

The default value for the fields for the advanced settings is null or an empty field.

Notes:

If you have configured some or all of the settings for the current run, and you do not want to continue with those settings, you can reset the settings by clicking Reset.
If you want to repeat a run and do not want to use the saved settings from a previous run, you can reset all the saved settings to their default values by clicking Reset.

Select the step for the location to run the virtual services based on the following types of virtual services:
- If you want to run any of the following types of virtual services only in the default Kubernetes cluster or a remote Kubernetes cluster, then go to Step 15.
- If you want to run the virtual services on a remote API agent that you added to your project, then go to Step 16.
Follow the instructions if you want to change the location of a Kubernetes cluster for running the test:
1. Click the LOCATION tab, if it is not already open.
  The Default Cluster is the default location where the virtual service resource runs, and it is listed under the Host column. The information about the availability of the default location is displayed.
  Important: You must have added the registered remote Kubernetes clusters to your project that are then displayed under the Override column:
  Notes:
  
  If the remote clusters are not added to your project, the option No override options is displayed as the default value and the virtual service resource runs in the Kubernetes cluster of Test Hub.
  
  If remote clusters are added to your project, the added clusters are displayed along with their availability status and ownership information.
2. Select the location where you want to run the virtual service resource from the following options:
  - Select the Default Cluster when no remote clusters are available in your project.
  - Select the remote cluster from the list when a remote cluster is available in your project.
  - Select No override options, if you selected any remote cluster and want to revert to the Default Cluster to run the virtual service resource.
3. Click Execute.
  The run is initiated.

Follow the instructions if you want to run the virtual services on the remote API agent that is connected to the default Kubernetes cluster:

Click the LOCATION tab, if it is not already open.

The API agents from the list of registered API agents that match with the attributes or tags configured for the virtual service resources in the project are listed under the Host column. The information about the availability of the agent is displayed.
Note: You must have added the API agents to your project from the Agents and Intercepts page for the API agents to be displayed under the Override column.

The default value for the API agents is null or an empty field if no agents were configured in the project resources. If the project resources contains API agents that match with the agent tags, then the default API agent is the first item to be displayed on the list of API agents listed in the increasing alphabetical order.

Select the API agent where you want to run the virtual service in the following scenarios:


If...	Then...	Action
The API agent that is specified in the project resources is available and no other agents are added to the project.	The API agent that is specified in the project resources is displayed in the Override column.	Select the API agent in the Host that is also displayed in the Override column as the location to run the test.
The API agent that is specified in the project resources is not available and no other API agents are added to the project.	There is no API agent displayed for override in the Override column.	You cannot run the test on the API agent. You must wait until the API agent is available to run the test on the API agent.
The API agent that is specified in the project resources is available and other API agents added to the project.	API agents that have capabilities that match with the API agent capabilities specified in the project resources are listed in the Override column as follows: API agents with capabilities that best match the capabilities of the API agent in the project resources are at the top of the list. API agents with capabilities that do not match with the capabilities of the API agent in the project resources are listed subsequently. You can find details of both API agents for the matching capabilities when you hover over the agent in the Override column.	Perform any of the following actions: Select the API agent in the Host that is also displayed in the Override column as the location to run the test. Select an API agent in the Override column as the location to run the test.

Click Execute.

The test run is initiated.

Results

You have started a virtual service from the Resources page on Test Hub.

What to do next

After you start a run of a virtual service, you can view the status of the virtual service in any of the following ways:

On the Resources page, the virtual services are displayed with the state as Running along with the number of instances that are running in the Active instances column.
On the Resources page, you must click the Show in instances page icon in the row of the virtual service to view all the running instances of a particular virtual service on the Instances page.
Go to the Instances page by clicking Virtualization > Instances. You can view instances of all the virtual services that are running and are displayed with the state as Running under the State column. You can also view the requests that are received by the virtual service. The number of requests is displayed as number of hits when you hover the cursor over the text in the Activity column.

You can view the details, configuration settings, routing rules, usage statistics, or logs of a specific running instance of the virtual service. See Viewing configurations of running instances of virtual services.

You can modify the behavior or the logging level of a running instance of the virtual service that you started before running tests on them. See Modifying configurations of running instances of virtual services.

When you have completed testing the virtual service, you must stop the running virtual service. See Stopping virtual services.