Articles in this section

See more

QuerySurge Test Management Tool Connector CLI

Follow

Versions:3.6+

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

QuerySurge Test Management Tool Connector API

QuerySurge offers API Connectors for integration with the major Test Management Tools:

  • HP Quality Center/Application Lifecycle Management
  • Microsoft Team Foundation Server
  • IBM Rational Quality Manager

Each QuerySurge Connector allows you to:

  • Drive QuerySurge executions from the integrated management tool
  • See outcome responses (e.g. Pass/Fail) in the management tool for your QuerySurge tests
  • Link from the management tool to QuerySurge, so you can 'click-through' from the management tool result to your QuerySurge data

Note: Please note that QuerySurge Connectors for test management integration are licensed separately.

Where to Install

Install your QuerySurge Test Management tool Connector(s) at the same location as your Test Management tool execution agent. Check with your Test Management tool Administrator.

Note: QuerySurge Connectors need to read and write to their own files. Because of the different permission levels that users might have, it may be necessary to install the Connector in a directory where your login has full read/write permissions in order for the Connector to work. This may not be the Program Files directory on Windows, depending on user permissions.

  • For HP Quality Center/Application Lifecycle Management, install the QuerySurge Connector in the same location as the Test Run Scheduler (wexectrl.exe).

  • For Microsoft Team Foundation Server, install the QuerySurge Connector in the same location as the Visual Studio Test Agent.

  • For Microsoft Visual Studio Team Services, install the QuerySurge Connection in the same location as the Visual Studio Build Agent.
  • For Microsoft Azure DevOps, install the QuerySurge Connection in the same location as the Visual Studio Build Agent.
  • For IBM Rational Quality Manager, install the QuerySurge Connector in the same location as the Command-Line Adapter. If you need to install the Command-Line Adapter, instructions can be found at the following link:

Connector Installation

  1. Launch the QuerySurge Installer.
  2. Click the “Next” button.

  3. You must select the “I accept the agreement” radio button in order to continue with the installation of QuerySurge and then press the “Next” button.


  4. Specify the installation directory and press the “Next” button.


  5. Select the "Test Management Tool Connectors" option, and deselect the other options. Click “Next”


  6. Select “Next” to complete the installation


  7. Click the “Finish” button to close the installer

Connectors and Permissions

The QuerySurge Connector is called by a Test Management tool component:

  • For HP Quality Center/Application Lifecycle Management, the Run Scheduler calls the QuerySurge Connector.

  • For Microsoft TFS (VSTS), a Visual Studio Agent calls the QuerySurge Connector.

  • For IBM Rational Quality Manager, the Command-Line Adapter calls the QuerySurge Connector.

The QuerySurge Connector runs with the permission level of the calling component. The QuerySurge Connector may need a relatively high level of permissions to run properly. This means that the calling component must run under an account with sufficient permissions.

Following are options for executing with a QuerySurge Connector. Please remember that these are options for running your Test Management tool execution component (which calls the QuerySurge Connector):

  • Log into the deployment box as a local Administrator. Run your Test Management tool execution component as usual. It will run with local Administrator rights.

  • Log into the deployment box as a user who is part of the Administrator group. Run your Test Management tool execution component "as Administrator". It will run with local Administrator rights.

Log into the deployment box as a regular non-Administrator user. Copy the QuerySurge Connector from its install directory (\\..\<QuerySurge Install Dir>\QuerySurge\cli) to a directory that you have rights to (e.g. the My Documents directory on Windows). Modify the qscli.bat file (which is in the \cli directory) with any text editor by replacing the line that reads 'cd "C:\Program Files\QuerySurge\cli"' with 'cd <your new install dir>/cli'. Run your Test Management tool execution component as usual. It will run with the rights that your login has.

Connector Authentication

A QuerySurge Connector must authenticate with QuerySurge - otherwise, QuerySurge would not know which user executed each QueryPair.

Connector authentication is set up in the following manner:

 

  • The QuerySurge user name of the user that the Connector will run under is submitted in the command line after the --username switch.

  • The qsapi.properties file (which is in the \\..\<QuerySurge Install Dir>\QuerySurge\cli directory) contains the QuerySurge password in the form of a key-value pair. Using 'myusername' as the user name and 'mypassword' as the password, the authentication should be entered into the qsapi.properties file as follows as part of the setup prior to the first execution:

After the Connector executes the first time, these values will be encrypted in the properties file:

Note: Connector authentication can only be performed using the qsapi.properties file.

Outcome Status Mappings

QuerySurge has its own Outcome Statuses, and your Test Management Tool has default Outcome statuses as well, which you may have modified for your needs. Because of the need to map QuerySurge Outcomes to your Test Management Tool Outcomes, the QuerySurge Connector has a mapping mechanism.

The QuerySurge Outcome Statuses include the following values:

Passed

Failed

Warning

Exceptions

Killed

Not Run

Running

Invalid Scenario

Each QuerySurge Connector deploys with a set of default mappings that link QuerySurge Outcomes to the default Test Management Tool Outcomes. These mappings are found in a properties file, called qsapi.properties, that deploys with your QuerySurge Connector. This file is found at:

\\<QuerySurge Install Dir>\QuerySurge\cli\qsapi.properties.

The mapping approach is simple, and is illustrated below using the QualityCenter mappings:

# QC Mappings

qc_passed = Passed

qc_failed = Failed

qc_warning = Failed

qc_exceptions = Blocked

qc_killed = N/A

qc_not_run = No Run

qc_running = Not Completed

qc_invalid_scenario = N/A

The mapping 'syntax' works as follows:

  1. Each mapping starts off with a Test Management Tool identifier, followed by an underscore. This indicates the tool to which the mapping applies. In the example above, the leading 'qc_' indicates that the mappings are for Quality Center.

  2. The Outcome Status following the underscore is the QuerySurge Outcome Status that is being mapped. So, '_exceptions' means that the mapping applies to the QuerySurge 'Exceptions' Outcome. The full 'qc_exceptions' means that the mapping takes the QuerySurge 'Exceptions' Outcome to the related Quality Center value.

  3. The Outcome after the equals sign is the Outcome Status in the Test Management Tool that is mapped. So, 'qc_exceptions = Blocked' means that the QuerySurge Outcome status of 'Exceptions' for Quality Center is mapped to the Quality Center of 'Blocked'.

You are welcome to modify the default mapping values in the qsapi.properties file. If you decide to do so, please note:

  • Keep a copy of the default qsapi.properties file in case you need to revert back to it. (If you don't have a copy of the default file, remove the copy you do have from the Connector directory and run the Connector - it will generate a clean default copy.)

  • The mapping keys are case sensitive. Please keep the cases of the key names to the left of the equals signs as they are.

  • The values to the right of the equal signs are up to you. But, they must match values that your Test Management Tool recognizes.

Script Examples for QuerySurge Connectors

When you install the QuerySurge Test Management tool Connectors, a set of sample scripts are provided showing how to script this API. These examples illustrate how to use each API Connector with its Test Management tool. Examples are found at the location(s) where you have installed a Connector. Details for each Connector are found below.

HP QC/ALM EXAMPLES

A "VAPI-XP-TEST" sample script is provided (VBScript). This example is a standalone script in which all input values are defined in the code.

The sample shows the basics of how to create a QuerySurge Scenario execution, with the Suites executed specified either by Suite ID or Suite Name. The QuerySurge Connector executes the specified Scenario, and returns an XML stream to the QC/ALM script, which the code parses into the Run Details showing the QueryPairs executed, the Outcome of each QueryPair, and links back to QuerySurge for the detailed results data for each QueryPair.

The sample script can be found on any box where you have installed a QuerySurge Connector, at:

\\..\<QuerySurge install dir>\QuerySurge\cli\samples

Samples:

ALM_QC_Script.vbs

MICROSOFT TFS EXAMPLES

Three C# "Unit Test" examples are provided. Two are standalone tests in which all input values are defined in the code. Of these two, one shows creating a Scenario via QuerySurge Suite IDs (TFS_ScenarioBySuiteId.cs) and the other shows creating a Scenario via QuerySurge Suite Names (TFS_ScenarioBySuiteName.cs). A third example illustrates how to use TFS Test Case Parameters with Test Manager execution to input values into the test (TFS_Connector_with_TestCase_Params.cs). All of these Unit Tests rely on a library class (TFS_QuerySurgeConnection.cs).

The examples show the basics of how to create a QuerySurge Scenario execution in each case. The QuerySurge Connector executes the specified Scenario, and returns an HTML stream which the code saves and attaches to the Test Result. The HTML attachment shows the QueryPairs executed, the Outcome of each QueryPair, and a link back to QuerySurge for the detailed results data for each QueryPair.

These sample scripts can be found on any box where you have installed a QuerySurge Connector, at:

\\..\<QuerySurge install dir>\QuerySurge\cli\samples

Samples:

TFS_ScenarioBySuiteId.cs

TFS_ScenarioBySuiteName.cs

TFS_Connector_with_TestCase_Params.cs

TFS_QuerySurgeConnection.cs (library file)

IBM RQM EXAMPLES

A sample batch file is provided (for Windows deployments of the RQM Adapter and the QuerySurge Connector), which shows the basics of how to create a QuerySurge Scenario execution and return a meaningful Outcome status to RQM.

The sample shows the basics of how to create a QuerySurge Scenario execution, with the Suites executed specified either by Suite ID or Suite Name. The QuerySurge Connector executes the specified Scenario, and returns a Scenario-level Outcome status. The Connector also attaches an HTML file to the Execution Result, which shows the QueryPairs executed, the Outcome of each QueryPair, and a link back to QuerySurge for the detailed results data for each QueryPair.

The sample script can be found on any box where you have installed a QuerySurge Connector, at:

\\..\<QuerySurge Install Dir>\QuerySurge\cli\samples

Samples:

RQM_Script.bat

Related articles

Comments

0 comments

Article is closed for comments.