QuerySurge Base CLI Reference

Versions: 8.0+

Versions:7.0+

Reference for: QuerySurge Base API

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

This reference documents usage of the QuerySurge Base API only. QuerySurge's other API components (the QuerySurge DevOps API and the QuerySurge Test Management Tool Connector API) are documented and licensed separately.

Note: The QuerySurge Base API is part of the core QuerySurge release and requires no separate licensing. The QuerySurge DevOps API is licensed separately. The Test Management Tool Connector API is also licensed separately. To arrange for licensing, contact [e-mail] or your QuerySurge Business Development representative.

 Disclaimer: The QuerySurge API may change from version to version in response to changes in functionality and implementation.

API Setup, Authentication and Project Specification

For QuerySurge versions 7.2-, see this article for API setup and API authentication. For versions 8.0+, see this article for API setup, API authentication and Project specification.

Command	License Level
	Base API	Test Management Tool Connector API	DevOps API
getScenarioOutcome
modifyReusableQueryTextByName*
modifyReusableQueryTextById*
modifySnippetText
runTestSuiteById
runTestSuiteByName

Table 1: QuerySurge Base API vs. Test Management Tool Connector API and DevOps API

 Note: Methods marked with * are deprecated methods. Newer versions are available which should be used instead.

Asset Modification

modifyReusableQueryTextByName - Update an existing Snippets Text.

hostname	--hostname	hostname or IP of the QuerySurge App server
port	--port	HTTP port of the QuerySurge App server
username	--username	QuerySurge username for this API call; this signature relies on the qscli.properties file
password	--password	[Optional*:String] Password for QuerySurge userOptionally use the qsapi.properties file to omit the password on the command line
search value	--snippetName	[String] Search value for identifying Snippet. This will be the snippets Name.
text	--snippetText	[String] Snippet Text

Table 2: modifyReusableQueryTextByName

Sample call:

qscli.bat modifyReusableQueryTextByName --hostname localhost --port 8081 --username admin --password admin --snippetName demo --snippetText "x<3"

Sample response:

Snippet: demo updated on 2019-05-10 16:10:39*** This method call is being deprecated. Please change your script to use modifySnippetText ***.

Response Description: Name of Snippet updated and its date. Please not this command is deprecated.

modifyReusableQueryTextById – Update an existing Snippets Text.

hostname	--hostname	hostname or IP of the QuerySurge App server
port	--port	HTTP port of the QuerySurge App server
username	--username	QuerySurge username for this API call; this signature relies on the qscli.properties file
password	--password	[Optional*:String] Password for QuerySurge userOptionally use the qsapi.properties file to omit the password on the command line
search value	--snippetId	[String] Search value for identifying Snippet. This will be the snippets Id.
text	--snippetText	[String] Snippet Text

Table 3: modifyReusableQueryTextById

Sample call:

qscli.bat modifyReusableQueryTextById --hostname localhost --port 8081 --username admin --password admin --snippetId 14 --snippetText "x<3"

Sample response:

Snippet: 14 updated on 2019-05-10 16:10:39*** This method call is being deprecated. Please change your script to use modifySnippetText ***.

Response Description: Id of Snippet updated and its date. Please not this command is deprecated.

modifySnippetText – Update an existing Snippets text.

hostname	--hostname	hostname or IP of the QuerySurge App server
port	--port	HTTP port of the QuerySurge App server
username	--username	QuerySurge username for this API call; this signature relies on the qscli.properties file
password	--password	[Optional*:String] Password for QuerySurge userOptionally use the qsapi.properties file to omit the password on the command line
search value	--identifier	[String] Id or Name of the Snippet to update (e.g. 431 or "DateFilter") Names can be used for snippets as they are unique
search flag	--isName	[Boolean] Flag used to identify if properties provided is the Id or Name of a Snippet True = Name provided False = Id Provided
snippet text	--text	[String] New Snippet value

Table 4: modifySnippetText

Sample call:

qscli.bat modifySnippetText --hostname localhost --port 80 --username admin --password admin -–isName false -–identifier 3 --text "10-13-2017"

Sample response:

{

  "data" : {

    "type" : "Snippet",

    "id" : "3",

    "attributes" : {

      "Name" : "test",

      "GUID" : "cfeaaa8d-1747-48f9-94af-54e1939b9fc1"

    }

  },

  "meta" : {

    "apiruntime" : "01/30/2019 17:20:27 -05:00",

    "action" : "modify",

    "message" : "Snippet modify succeeded"

  }

}

Response Description: Asset being updated and date of update

Execution

runTestSuiteById – Execute a test suite with a given Id

hostname	--hostname	hostname or IP of the QuerySurge App server
port	--port	HTTP port of the QuerySurge App server
username	--username	QuerySurge username for this API call; this signature relies on the qscli.properties file
password	--password	[Optional*:String] Password for QuerySurge userOptionally use the qsapi.properties file to omit the password on the command line
agent	--agentName	[Optional:String] Name of agent to execute Test Suite run. An empty string "" can be provided which will have the Test Suite run use the first available agent
return JSON	--returnJson	[Optional:String] Return result as JSON Object
test suite id		[String] Id of the test suite to execute

Table 5: runTestSuiteById

Sample call:

qscli.bat runTestSuiteById --hostname localhost --port 80 --username admin --password admin 37

Sample response:

b1804716-a247-7gda-9341-d075c2bfd12c

Response Description: Returned record is a GUID to identify the run. This GUID can be used to retrieve results from the execution.

runTestSuiteByName – Execute a test suite with a given name

hostname	--hostname	hostname or IP of the QuerySurge App server
port	--port	HTTP port of the QuerySurge App server
username	--username	QuerySurge username for this API call; this signature relies on the qscli.properties file
password	--password	[Optional*:String] Password for QuerySurge userOptionally use the qsapi.properties file to omit the password on the command line
agent	--agentName	[Optional:String] Name of agent to execute Test Suite run. An empty string "" can be provided which will have the Test Suite run use the first available agent
return JSON	--returnJson	[Optional:String] Return result as JSON Object
test suite name		[String] Name of the test suite to execute

Table 6: runTestSuiteByName

Sample call:

qscli.bat runTestSuiteByName --hostname localhost --port 80 --username admin --password admin "CustomerVerifications"

Sample response:

b1804716-a247-7gda-9341-d075c2bfd12c

Response Description: Returned record is a GUID to identify the run. This GUID can be used to retrieve results from the execution.

Results

getScenarioOutcome – Retrieve high level outcome information from a scenario execution.

hostname	--hostname	hostname or IP of the QuerySurge App server
port	--port	HTTP port of the QuerySurge App server
username	--username	QuerySurge username for this API call; this signature relies on the qscli.properties file
password	--password	[Optional*:String] Password for QuerySurge userOptionally use the qsapi.properties file to omit the password on the command line
return JSON	--returnJson	[Optional:String] Return result as JSON Object
scenario Id		[String] Execution GUID for the design time run. This GUID is provided when execution "executeScenarioBySuiteId" or similar command

Table 7: getScenarioOutcome

Sample call:

qscli.bat getScenarioOutcome --hostname localhost --port 80 --username admin --password admin --returnJson true fa1b832d-33b9-48a6-812d-258d150be560

Sample response:

Not Run, N/A, Running, Passed, Failed or Error

Or

{

  "data" : {

    "type" : "Scenario",

    "id" : "4e0439e2-7f27-410c-a2fb-14f3d793d980",

    "attributes" : {

      "outcome" : "Failed"

    }

  },

  "meta" : {

    "apiruntime" : "02/27/2019 10:50:31 -05:00",

    "action" : "outcome"

  }

}

 

Appendix A: Glossary

Created By (CreatedBy): User who initially created asset

GUID/UUID: Globally/Universally Unique Identifier, guaranteed to be unique within a single QuerySurge instance

Outcome: Status of the test execution. The following list describes the acceptable outcomes

Outcome	Abbreviation
Not Run	N
Passed	P
Failed	F
Error	X
Killed	K

Query Destination (QueryDestination): Identifier to determine if query is a source (S) or target (T) query.

Type: All response objects returned by the QuerySurge API will contain a type object. This object describes the resources being returned. Objects with the same type will return the same common set of attributes.

Updated By (UpdatedBy): Last user who edited assets

UIID: A visible unique identifier used by QuerySurge

Appendix B: Permissions Guide

User Role	Permissions Level
Admin	1
Full	2
Participant	3

API Command	Highest Permission Level
modifyReusableQueryTextById	2
modifyReusableQueryTextByName	2
modifySnippetText	2
runTestSuiteById	2
runTestSuiteByName	2
getScenarioOutcome	3