Base API Sample Batch Files (Windows)

Versions: 8.0+

The QuerySurge Base API: Using the Sample Batch Files

Installation of the QuerySurge Base API gives you command-line access to the QuerySurge execution engine. The API can be used to drive QuerySurge executions from any external tool that can access a command line. Included in the Base API installation is a directory of sample files illustrating how to call into the API. Following is a description of how to set up the sample files on a Windows box.

There are two sample batch files included in the distribution:

• CLI-run_test_suites.bat
• CLI-run_test_suites_advanced.bat

Note: You will need to install the QuerySurge Base API in order to access the samples that this article discusses. Installation information is available here.

Preparation

1. First, please note that the Base API components should be installed in the location that the API will be called from. Typically, this is not the QuerySurge Application server (although there is no restriction on installing the components on the QuerySurge Application server) because this is not where the calling process resides. For example, if you want to call into the API from a scheduling tool, then the API should be installed on the scheduler itself or on a box where a scheduler agent is deployed. If you want to call into the API from your ETL tool, then the API components should be installed on the location where your ETL tool is installed.
   
   
2. Installation is done using the regular QuerySurge Installer, choosing only the Command Line API option (this is not one of the default options; you will have to de-select the default options and select this option).
   
   
3. The sample files are located in the samples directory; in the default install, this is found at:
   C:\Program Files\QuerySurge\cli\samples
   If you installed in a nondefault location, the generic path is:
   \\<QuerySurge Install Dir\QuerySurge\cli\samples

Setting Up the Sample Batch Files

1. This discussion focuses on the CLI-run_test_suites.bat The basic setup steps for CLI-run_test_suites_advanced.bat example are the same. Locate the CLI-run_test_suites.bat file and display it.
   
   
2. The Configuration Variables section of the file is the part of the file we need to modify. This section should be marked clearly in the sample file by ‘START OF CONFIGURATION VARIABLES’ and ‘END OF CONFIGURATION VARIABLES’.
   
   
3. There are six variables listed in this section; only five of them require modification under most circumstances. The four that require modification are:
   • cliPath
   • hostname
   • port
   • username
   • suiteIdList
     
     
4. The cliPath variable is set to the location of the main batch file, bat. This must be modified only if you have installed in a location other than the default location. If so, change the value to the location of the qscli.bat file.
   
   
5. The hostname variable is set to 0.0.1. This must be changed to either the server name of the QuerySurge Application server (the fully qualified name is recommended) or the IP address of the QuerySurge Application server.
   
   
6. The port variable is set to the default HTTP port 80. This should be changed to the HTTP port that you have installed your QuerySurge Application server on, if it is different. (Check a browser link to QuerySurge for the port; if no port number is showing, the default value of 80 should be used.)
   
   
7. The username variable is set to ‘admin’. This is the QuerySurge user login under which the API executions will run.
   
   
8. The suiteIdList variable is a comma-separated list of the ID numbers of the QuerySurge Suites that you want to execute. You can find these ID numbers in QuerySurge, in the Scheduling view, in the Test Suites panel. Each Suite has an ID (for example, in the figure, the first Suite has an ID of 2458). Create a comma-separated list of the ID’s of the Suites you want to execute via the API (no spaces) and uses this list as the value for suiteIdList.
   
   
   
   
9. The ‘advanced’ example (CLI-run_test_suites_advanced.bat) shows how to run Suites sequentially, meaning the script waits for each Suite to complete before calling the next Suite.

API Authentication and Project Specification

For QuerySurge versions 7.2-, see this article to set up API authentication. For versions 8.0+, see this article to set up API authentication and Project specification.

API Execution

1. In the samples directory, execute the sample batch file by entering the following command in a Windows Command Processor window:
   CLI-run_test_suites.bat
   
   or
   
   CLI-run_test_suites_advanced.bat
   
   Note: If your User login does not have sufficient (read/write) access to the Base API install directory, you have two options:
   (a) run the Base API batch file with Admin rights, or
   (b) you can move the cli directory to a location where your login does have sufficient access rights.
   

   If you choose option (b), then you'll need to modify some file paths. Carefully modify the file qscli.bat for the new path you have selected for the \..\cli directory. Also, you will need to modify your batch files (start with the Sample files that you are using) for the new path for qscli.bat (the cliPath variable).