REST API Sample PowerShell Scripts (Windows) (Versions: 7.0+)

Versions: 8.0+

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 PowerShell scripts illustrating how to call into the REST API. The following is a description of how to set up the sample files on a Windows system.

Preparation

1. 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.
   
   
2. 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:
   
   C:\Program Files\QuerySurge\rest\samples
   
   
3. Some sample scripts make use new PowerShell features such as JSON to Hashtable conversion with the 'AsHashtable' parameter. These features require installing the latest PowerShell version (7.x+) .

Configuration

The following steps focus on the REST-run_test_suites.ps1 sample file, however the basic setup steps for REST-run_test_suites_advanced.ps1 sample file are the same. The REST-run_test_suites.ps1 sample file, executes a test suite(s) without monitoring its outcome, while the REST-run_test_suites_advanced.ps1 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. 

1. Locate the REST-run_test_suites.ps1 file and open it in the text editor of your choice.

   

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’.
   
   
   
   • 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

1. Executing PowerShell scripts in Windows can be done in a few ways. The approach recommended here is to execute the scripts via a PowerShell window as an administrator. Once opened, navigate to the sample directory listed above or the location in which your scripts are provided. Then execute: 

   .\REST-run_test_suites.ps1
   or
   .\REST-run_test_suites_advanced.ps1

   Note: If you renamed your files you will need to modify the above command in order to execute them.

Resources