Configuring an API Suite or an API test run

After you added the test resources that you created in the desktop client to the project, you can configure an API Suite or an API test to be run on IBM® Rational® Test Automation Server or a remote Kubernetes cluster.

Before you begin

You must have completed the following tasks:

Read and completed the tasks mentioned in Prerequisites to running tests if they apply to the test you want to configure for a run.
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.
Completed the following tasks if you are running API Suites or tests that use a transport and the transport requires third-party application Jar files for a successful run:
- Read Test run considerations for API Suites or API tests.
- Copied the third-party application Jar files to the third-party application folder on the computer where Rational® Test Automation Server is installed, if you are running the API Suite in Kubernetes. See Copying third-party application Jars to Kubernetes.
- Copied the third-party application Jar files to the third-party application folder on the computer where the remote Docker host is installed, if you are running the API Suite on a remote Docker host. See Copying third-party application Jars to a remote Docker host.
Ensured that you are assigned a role as a Member or 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 server projects.

Procedure

Log in to Rational® Test Automation Server.

The team space that contains your project is displayed.
Open the project that contains the test assets, and then click Execution.

Select the branch of the repository that contains the test assets.

The test assets that are contained in the selected branch of the repository are displayed in the following tabs on the Execution page:


Tab	Description
SUITES	Lists all suites, compound tests, JMeter tests, JUnit tests, Postman tests, Rate Schedules, or VU Schedules that are in the selected branch of the repository.
TESTS	Lists all API tests, functional tests, or performance tests that are in the selected branch of the repository.
ADVANCED	Lists all assets that are displayed when custom filters are applied for assets in the selected branch of the repository.

Select the tab based on the type of test assets that you want to run as indicated in the following table:


If...	Then...
You want to run AFT Suites, API Suites, Compound Tests, JMeter tests, JUnit tests, Postman tests, Rate Schedules, or VU Schedules,.	Click the SUITES tab.
You want to run API tests, functional tests, or performance tests.	Click the TESTS tab.
You want to find Suites and tests by using custom filters, and then run Suites and tests.	Click the ADVANCED tab.

The test assets in the selected tab are displayed.

Identify the test asset that you want to run by performing any of the following actions:

Scroll through the list.

Tip: You can hover over the icon in the Type column to know the type of the test asset.

Note: You can also identify the type of the asset from the icon that represents the test type as shown in the following table:


Icon	Represents	Listed in the SUITES tab	Listed in the TESTS tab	Listed in the ADVANCED tab
	API test
	Functional test
	Performance test
	AFT Suite
	API Suite
	Compound Test
	HCL AppScan CodeSweep
	JMeter Test
	JUnit Test
	Postman test
	Rate Schedule
	VU Schedule

Search for the test asset by entering any text contained in the test asset name in the Search field.
Click the Filter icon in the SUITES or TESTS tab to filter the displayed assets based on the asset type.
For example, select API Suite in the SUITES tab to display all API Suites or select Functional Test in the TESTS tab to display all functional tests that are in the selected branch of the repository.
Click the Filter icon in the ADVANCED tab, and then create a filter query by using the New filter option by performing the following steps:
1. Click New filter.
2. Enter a name for the filter.
3. Select an operator, and add a rule or a group of rules.
4. Add or enter the relevant parameters and either select or enter the condition and the criteria for the condition.
  You can select a parameter from the following list:
  - Type
  - Test Asset Name
  - Test Asset Path
  - Last Result
  - Next Run
  - Components
5. Save the filter query to save and apply the filter query to filter the assets based on the query.
  The test assets that match the filter criteria are displayed.
Retrieve and apply a saved filter query, if you have saved filter queries previously by performing the following steps:
Note: The filter query applied previously is selected and the assets based on that filter query are displayed. To apply a different filter query, you must have created and saved the filter query.
1. Click the Filter icon in the ADVANCED tab.
  The filter queries that you created and saved are displayed.
2. Click the filter that you want to apply.
  The test assets that match the filter criteria are displayed.

You have identified the test asset that you want to run.

Clicking the test name displays the Details panel. You can view the details of the test such as the description, the branch in the repository that contains the asset, the Git details, and the details of the commits to the repository. You can also view the history of the test runs for the specific test under the History tab of the Details panel.

Click the Execute icon in the row of the identified test asset.
The Execute test asset dialog is displayed.
Notes:
- If you have configured some or all of the settings for the current test 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 test 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 version of the test resources that you want to run by completing any of the following actions:
Note: The test resources in the version can contain the test assets, datasets, AFT XML files, API environment tags, and other resources specific to projects created from any of the desktop clients.
- 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 by the user 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 that is committed, and then 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.
The default value for the version selected for the run is the latest version in the selected branch of the repository. If you do not select any version, then the latest version is selected for the test run.
Notes:
- If you selected a version but you do not want to use that version in the test run, you can remove the selected version by clicking the icon. As a result, the default version is selected for the test run.
- If you repeated a test or ran the test again from the Results page, then the version of the test resources that you chose for the earlier run is shown as selected. You can either retain this version or select any other version from the list. You can also remove the previous version by clicking the icon.
Select the time for scheduling the test run from the following options:
- No action is required if you want to initiate the test run immediately after you click Execute.
  
  Important: Click Execute only after you have configured the other settings in this dialog.
  
  Note: The default time for scheduling a run is Now.
- Select Later and configure the date and time to schedule a test run.
- Select Recurring and perform the following steps to configure recurring test runs:
  1. Click the Calendar icon under Start, and then select the date and time at which the test run must start.
  2. Set the frequency at which the test runs must run by entering the number in the Repeat every field, and then select the period from the list.
    For example, if you want the test run to be run every 2 hours, enter 120, and then select the Minute(s) option.
  3. Set the option to end the recurring test runs from the following options:
    
    Select the Never option, if you do not want the recurring test runs to end.
    
    Select the On option, and then click the Calendar icon . You can select the date and time after which the scheduled test runs do not run.
Enter a label for the test run that helps you to identify the test on the Results page.

After the test run completes, the label that you entered is displayed for the test under the Labels column on the Results page. After you have created a label, any member of the project can use that label.

The default value for the Label field is null or an empty field.

Important: The configuration that you set for the test run in the Execute test asset dialog is preserved when you run the same test again. Those changes are not visible when another user logs in to Rational® Test Automation Server. For example, if you created new variables on the server, those variables are available only for you when the same test is run again.

If you want to run the test immediately or at the scheduled time, click Execute, or continue with the next step.

Click Advanced to make the following advanced configurations:

Enter any JVM arguments that must be passed to the test run at run time in the JVM Arguments field, if applicable for the test.

For example, you can set a maximum Java heap size.

Enter program arguments that must be passed to the test run at run time in the Program Arguments, if applicable for the test.

Perform the following actions, if applicable for your test:

Configuring Jaeger tracing.

If the test that you want to configure supports the presentation of the test results data in different formats, then do the required tasks in the following scenarios:


If...	Then...
You want the test results data in different supported formats.	Enter `-history cisterna` in the Program Arguments field.
You want to obtain the test results as a Jaeger trace.	Enter `-history jaeger` in the Program Arguments field.
You want the report as a test log and as a Jaeger trace.	Enter `-history jaeger,testlog` in the Program Arguments field.
Jaeger is already set as a program argument and you want to remove the Jaeger trace for your test.	Delete the `-history jaeger` entry in the Program Arguments field.

Note: The default report format is the test log format for the test reports.

Overriding results database that is configured in the API Suite project.

Note: You can use any of the databases that are specified in the system requirements as supported databases in Rational® Integration Tester.

Enter the following arguments in the Program Arguments field, if you want to override the Results Database:


Program Arguments	Description
-resultDatabaseURL `<database_URL>`	Specifies the URL of the results database that overrides the results database that is configured for the project in Rational® Integration Tester.
-resultDatabaseDriver `<driver_name>`	Specifies the driver of the results database that overrides the results database that is configured for the project in Rational® Integration Tester. For example, the driver for a MySQL database is `com.mysql.cj.jdbc.Driver`.
-resultDatabaseUsername `<user_name>`	Specifies the user name that is authorized to access the results database that overrides the results database that is configured for the project in Rational® Integration Tester.
-resultDatabasePassword `<encrypted_password>`	Specifies the password that is to be used to authenticate the user to access the results database that overrides the results database that is configured for the project in Rational® Integration Tester. Note: You can encrypt the password by using the EncryptPassword application that is available in the installation directory of Rational® Integration Tester.

For example, if you want to override the results database that is configured in the Rational® Integration Tester project with a different results database that has the following details:

MySQL database as the results database with the URL as jdbc:mysql://localhost:3306/myresultsdb
com.mysql.cj.jdbc.Driver as the driver for the MySQL database
tester as the user name to access the MySQL database
#com.ghc.1!9a8521137E0A12994ACF4434E315A2B9 as the encrypted password to authenticate the user name tester

The entry in the Program Arguments field must be as follows:

-resultDatabaseURL  jdbc:mysql://localhost:3306/myresultsdb
-resultDatabaseDriver com.mysql.cj.jdbc.Driver
-resultDatabaseUsername tester
-resultDatabasePassword #com.ghc.1!9a8521137E0A12994ACF4434E315A2B9

Note: You must separate entries in the field with white spaces or with a new-line character.

Follow the instructions if the API Suite has an environment or secrets configured:
1. Click the ENVIRONMENT tab, if it is not already open.
2. Select the API test environment from the list if there are multiple environments configured in the test asset.
3. Select the secrets collection that contains the secrets to be used for the test run.
Notes:
- The test asset that was created in the desktop client and added to the Git repository must have the environments defined as part of the API test project.
- If the test asset contained secrets, then you must create those secrets in secrets collections in the project.
The default value for the environment is the environment configured in the test asset. The default value for secrets is null or an empty field.

If you want to run the test immediately or at the scheduled time, click Execute, or continue with the next step.
Follow the instructions if you are running a test asset that contains datasets:
1. Click the DATA SOURCES tab, if it is not already open.
2. Consider the following information about datasets before you select a dataset:
  
  The default value for the datasets in the DATA SOURCES tab is null if the test asset did not have an associated dataset. If the asset had an associated dataset, the default value is the associated dataset.
  
  You can utilize the dataset stored as an Excel or CSV file to override the original dataset associated with the Suite, test, or schedule. For example, when you have associated a dataset in .xlsx, .xls, or .csv format with the test or schedule in desktop clients and if you have another set of data stored in an Excel or CSV file, then you can select that dataset from the Override list.
  Remember: You must have uploaded the dataset as an Excel or CSV file into the Git repository, and ensured that both the original dataset (from the test asset) and new datasets (added to the project) have the same column names.
3. Select the dataset that you want to use in the test run from any of the following options:
  - Select the dataset that is displayed as the default dataset when the test asset contains a single dataset.
    Note: If there is only one dataset in the test asset, then that dataset is displayed as the default dataset.
  - Select the dataset from the list.
    Note: If there are multiple datasets in the test asset, the datasets are listed in their increasing alphabetical order.
  - Select the dataset from the Override list to override the dataset that was associated with the test in the desktop client.
    Important: If the test contains an encrypted dataset, the Project Owner must classify it in the DATA SECURITY tab on the Project page before you can select it. You must have added datasets to your project from the Dataset page for the datasets to be displayed in the Override list.
If you want to run the test immediately or at the scheduled time, click Execute, or continue with the next step.
Follow the instructions if the test requires a variable that must be passed to the test at the test 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.
The default value for the variables is null or an empty field.

If you want to run the test immediately or at the scheduled time, click Execute, or continue with the next step.
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 test 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 following remote hosts to your project that are then displayed under the Override column:
  
  Docker hosts that are registered with Rational® Test Automation Server.
  
  Kubernetes clusters that are registered with a team space.
  Notes:
  
  If the remote Docker hosts or clusters are not added to your project, the option No override options is displayed as the default value and the test runs in the Kubernetes cluster of Rational® Test Automation Server.
  
  If remote Docker hosts or clusters are added to your project, the added Docker hosts or clusters are displayed along with their availability status and ownership information.
2. Select the location where you want to run the test asset from the following options:
  - Select the Default Cluster when no remote Docker hosts or clusters are available in your project.
  - Select the remote Docker host or cluster from the list when a remote Docker host or cluster is available in your project.
  - Select No override options, if you selected any remote Docker host or cluster and want to revert to the Default Cluster to run the test asset.
3. Click Execute.
  The test run is initiated.

Results

You have configured and either started or scheduled a test run of an API Suite.

What to do next

You can choose to perform any of the following tasks after you have initiated or scheduled a run:

Stop the test run at any point after the test run is initiated from the Execution page. See Stopping test runs.
Cancel a scheduled test run from the Execution page. See Canceling scheduled test runs.
View all the states of the test asset by clicking the Show in the Progress page icon for the test asset for which you started or scheduled the run. See Viewing the state of test assets.
View the progress of the test from the Progress page. See Viewing the progress of running test assets.
View the results, reports, and logs of the test from the Results page after the test completes the run. See Test results.