Articles in this section

See more

Using the QuerySurge Base CLI (Versions: 8.0+)

Follow

API Overview

The command line API for QuerySurge is deprecated. We do recommend switching existing API calls to the REST API. Information on our REST API can be found here

The QuerySurge API breaks out into three areas:

  1. The QuerySurge Base API - a lightweight execution API, which allows users to drive QuerySurge execution from an external command line or scripting environment.
  2. The QuerySurge Test Management Tool Connector API - supports execution of QuerySurge from leading Test Management Tools (MicroFocus QualityCenter, Microsoft Azure DevOps and IBM Rational Quality Manager).
  3. The QuerySurge DevOps API - a full DevOps API supporting the majority of QuerySurge functions in an API context.

This article discusses the QuerySurge Base API, which provides command-line access mainly to QuerySurge execution functionality.

  Note: If you are setting up your QuerySurge API for the first time, see all of the following sections (API Authentication, API Project Specification, and API User Login). If you are upgrading, and have API scripts from QuerySurge versions prior to 8.0, see the API Project Specification section, to see how to modify your existing setup to make your API scripts project-aware.

API Authentication

The Base API functions generally have two signatures each: a signature supporting full authentication in the API call (i.e. both the user login and password are passed in the API call, and are stored in plaintext in your API script) and a secure method using the qsapi.properties file, in which the user login and password are entered into the file, and only the user login is passed in the API call (the authentication credentials entered into qsapi.properties are encrypted after the first call), so passwords are not stored in plaintext.

The following steps describe setup using the qsapi.properties file:

  1. The QuerySurge user login under which the API will run, is passed in the API call via the username switch.
  2. The specified user’s password needs to be made available for the API. This is done via the properties file; this file’s default location is:
    C:\Program Files\QuerySurge\cli\qsapi.properties
  3. For safety, make a copy of qsapi.properties before you modify it.

  4. Open the qsapi.properties file in a text editor, and go to the last line of the file. This line reads:
    # Client API
  5. Add a line to the file after this line. On the new line, enter your username and password separated by an equals sign ("=") as a 'key=value' pair.

    For the default admin user, the final lines of the file are:
    # Client API
    admin=admin

    If you had a QuerySurge Admin username 'admin002' with password 'querysurgeadmin101600', then final lines of the file would be:
    # Client API
    admin002=querysurgeadmin101600
  6. Save the file.

    Note: On the first execution of the API, the credentials are encrypted and stored in the qsapi.properties file in an encrypted format. The plaintext credentials should therefore only remain in the file until the first execution.

API Project Specification

Projects are specified for the API in one of two ways: a) using the --projectId switch on the API command line, or b) by using the qsapi.properties file. Note that using approach (b) the qsapi.properties file, sets the property for everything the Agent runs, so if you need project flexibility in your API scripting, approach (a) provides this flexibility. Note also that if a project is specified by both methods, the command line (a) takes precedence.

Project Specification on the API Command line

To specify the Project ID on the comand line, add the --projectId switch to each API call in your script. For full documentation, see the API documentation for your calls.

Project Specification in qsapi.properties

  1. For safety, make a copy of qsapi.properties before you modify it.

  2. Open the qsapi.properties file in a text editor, and go to the last line of the file (adding the project identifier at the end of the file is not required, but we recommend it for convenience).
  3. Add a line to the file. On the new line, enter the value name projectId, and the numeric ID of the Project ("=") as a 'key=value' pair.

    For the default Project, the lines are:
    # Project ID
    projectId=1
  4. Save the file.

  5. For additional Project ID numbers, log in the the QuerySurge Admin app, and, in the tree on the left, click on Projects. The ID values are in the leftmost column of the Projects grid.

API User Login

When you run the API, it executes with the login rights of the Operating System login user of the session that the API is running in. So, if a "regular" network user is logged in and is running an API script, the script will execute with that network user's rights.

If your user login does not have sufficient (read/write) access to the API install directory, errors may occur with logging or other features. In this case, you have two options:

  1. run the API batch file with elevated rights (e.g. Admin rights), or
  2. 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 execution file (qscli.bat/qscli.ps1/qscli.sh) for the new path you have selected for the /../cli directory. Also, you will need to modify your API script files  for the new path for to the execution file (the cli or cliPath variable).

Base API Commands

The following commands are available:

  • getScenarioOutcome – Returns the outcome of a Scenario, specified by Scenario ID
  • modifyReusableQueryTextByName - modify a Reusable Query Snippet value, specified by the Snippet Name
  • modifyReusableQueryTextById - modify a Reusable Query Snippet value, specified by the Snippet ID
  • modifySnippetText - modify the text of an existing Reusable Snippet
  • runTestSuiteByName – Runs an available Test Suite in QuerySurge, specified by name.
  • runTestSuiteById – Runs an available Test Suite in QuerySurge, specified by Test Suite ID.
  • help – Prints the arguments for the specified command
  • <blank> – Prints the list of available commands

Starting Test Runs

The simplest use case that involves using the Base API is simply to run a Test Suite directly from the Windows Command Prompt or a Linux shell. Here, the appropriate command (either runTestSuiteByName or runTestSuiteById) is given with the desired arguments. When a Test Suite is run using the runTestSuiteByName or runTestSuiteById command, a new QuerySurge Scenario is created and is scheduled to run immediately. The GUID for this execution is returned to the command line, which can be used to check on the status of the run.

Figure 1

Figure 1 shows the command to run a Test Suite specified by name, which returns the Scenario Id (which in this example is "44ca0f07-7516-42d6-b5e1-e39346246b5a"). Using the Base API "manually" in this manner is useful in many situations, such as when running in a headless mode or via SSH.

Note: While all of the examples in this article are Windows-based, the Base API can be installed and run from supported Linux systems as well.

Basic Scripts for Starting Test Runs

Another common Scenario that can be easily implemented using the Base API is to start a test run from an external process or script. This allows you to easily run multiple commands, so that you can begin the execution of multiple Test Suites. One particularly useful instance in which a script can be used is when you’d like to schedule a Test Suite or multiple Test Suites to run on a repeating schedule. In Windows, this is possible using the Windows Scheduler to run a batch script of QuerySurge commands according to the schedule you choose. For example, you can set up regression tests to run every night after business hours. This can also be accomplished in Linux using cron jobs with shell scripts. Figure 2 is an example of a simple batch script that runs two different Test Suites, one specified by name ("Customers Suite"), and the other by ID (1). The script first outputs the message that it has been started, calls into the API to run the desired Test Suites, and then outputs the message that the run has completed.

Figure 2

Advanced Event Driven Scripts

Creating scripts to run Test Suites is useful, but these scripts can be made even more powerful with additional logic.

Figure 3 shows an example of a batch script that incorporates logic to determine when each Test Suite is ready to be run, based on whether the previous Test Suite has completed. It also incorporates kicking off multiple legs of an ETL process (two legs, in this illustration).

First, the script runs the initial ETL process. Once that is complete, it runs the Test Suite in QuerySurge that has been set up for that ETL leg. It then captures the Scenario Id that is returned (in a variable called %ScenarioId%) and uses that Id with the getScenarioOutcome command to check on the status of that run in QuerySurge. The script checks whether the Scenario has started, and once it has, it continues to check on the run status until the Scenario has completed. Once the first Scenario is completed, the second ETL process is run. Finally, the second Test Suite execution in QuerySurge is executed, which runs the tests prepared for the second ETL leg.

This example shows how the different commands can be used together to build a comprehensive run script that effectively is incorporated into an ETL process.

Figure 3

The Base API gives users significant flexibility, supporting QuerySurge integration into a wide range of execution workflows, from functional/regression data testing workflows owned by Data Warehouse project teams to daily monitoring workflows owned by Operations teams. QuerySurge of course keeps results organized with full access to past runs, data drilldown and export, and results reporting. Scenarios that are run from the Base API appear in the QuerySurge user interface the same as user-initiated runs appear, so all of the data access features are available for these executions. 

API Documentation

The QuerySurge Base API is further documented in the Knowledge Base, both from the perspective of standard API documentation as well as Use Case-based articles:

The QuerySurge Base API method calls are documented in this Knowledge Base article. 

For discussions and examples of how to use the Base API, from novice-level Use Cases to advanced-level Use Cases, see the following Knowledge Base articles:

 

 

Related articles

Comments

0 comments

Article is closed for comments.