The QuerySurge REST API: Using the Sample Shells
Use of the QuerySurge REST API gives you the ability to control QuerySurge externally via an automation or scripting tool of your choice. Attached to this article and deployed with the QuerySurge installation are a set of sample shell scripts illustrating how to call into the REST API. The following is a description of how to set up the sample files on a Linux system.
Preparation
- Installation of the REST API is automatically part of a regular QuerySurge installation through the Installer. Samples scripts are automatically deployed when installing the QuerySurge application server component (In version 12.1 and higher). Additional information about the REST API can be found in this article.
- The sample files are attached to this article or are located in the samples directory (In version 12.1 and higher). of your QuerySurge installation; This is found at:
<QuerySurge Install Dir\QuerySurge\rest\samples
- Sample scripts make use of the opensource library jq. This library is a lightweight JSON parser which assists in reading responses from the QuerySurge API. Instructions on downloading/installation of jq can be found at https://jqlang.github.io/jq/download/
Configuration
The following steps focus on the REST-run_test_suites.sh sample file, however the basic setup steps for REST-run_test_suites_advanced.sh sample file are the same. The REST-run_test_suites.sh sample file, executes a test suite(s) without monitoring its outcome, while the REST-run_test_suites_advanced.sh sample file executes a test suite(s) and monitors the run until completion. Additionally, the advanced script outputs the final outcome of the test run such as if it passed, failed or errored out.
- Locate the REST-run_test_suites.sh file and open it in the text editor of your choice.
- 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’.
- username: account which will be used to log into QuerySurge for your test script; the default value for this is 'admin', update this value for a user which exists in your QuerySurge instance.
- password: password associated with the username provided in the previous step; the default value for this is 'admin', update this value as needed.
- hostname: IP/Hostname of the QuerySurge server which you would like to connect to; the default value is set to 127.0.0.1, which is the standard loopback address for most operating systems. We do recommend replacing this value with your QuerySurge's servers FQHN (Fully Qualified Host Name) or IP address as this will allow the script to be deployed to other machines if needed.
- port: The port in which the QuerySurge webserver was installed. By default, this is port 80, however this may be a different value in your instance. For example, if SSL was setup this is often port 443.
-
projectId: The numeric id associated with the QuerySurge project that contains the suite which you would like to execute; the default value for this is '1' or the default QuerySurge project created on installation. To determine the projectId needed for your script, log into Global Administration and select 'Manage Projects' from the tree as seen below.
- scenarioName: Name which will be given to the collection of suites to run for this specific scenario. This name will be shown within the QuerySurge UI; the default value for this is 'My New Scenario'
- suiteIdList: 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 below, the Suite indicated has an ID of 1).
Execution
Executing shell scripts in Linux can be done in a few ways. The approach recommended here is to execute the scripts via a terminal (Bash Shell). To execute the scripts open terminal and navigate to the sample directory listed above or the location in which your scripts are provided. Then execute:
./REST-run_test_suites.sh
or
./REST-run_test_suites_advanced.sh
Note: Executing scripts from the terminal may require elevated permissions.
Note: If you renamed your files you will need to modify the above command in order to execute them.
Resources