SCommand Reference

Document created by Chris Sommerstad Employee on Jul 22, 2017Last modified by Dave Murphy on Sep 26, 2017
Version 3Show Document
  • View in full screen mode

Introduction

 

The "CloudTest Command-Line Client" (also known as "scommand") is a command-line utility that you can download and install on your computer. This utility allows you to perform the following SOASTA operations from the Operating System command line on Windows, Unix, and Mac OS X systems:

  • Delete, import, or export SOASTA CloudTest items, such as Test Compositions, Test Clips, Scripts, Targets, and others.
  • Display lists of SOASTA CloudTest items.
  • Start and stop Test Compositions and Playlists playing.
  • Display the status of various SOASTA services.
  • Start and stop monitors.
  • Upload mobile apps for distrubution to your users.
  • Use SCommand from within various CI tools, including Jenkins/Hudson and Bamboo.

SCommand communicates with the SOASTA services through Web Service calls, thus the appropriate HTTP or HTTPS connection to those services must be available on the machine on which scommand is to be run. No other connections are required.

TIP: Use the scommand built-in help system via the scommand help command "scommand help" while in Terminal for a complete list of available commands. To see the built-in help for a given command, use the "help" parameter followed by the command name (e.g. "scommand help delete").

Installing the CloudTest Command Line Client (scommand)

 

  1. Log in to SOASTA Central and go to the "Resources" page.
  1. Under "Download", click "CloudTest Command-Line Client". When prompted, save the file "scommand.zip" somewhere on your disk.

  1. Unzip the file, which will create a directory named "scommand". Optionally, add scommand/bin to your path.

Common Uses for the Command-Line Client

 

    • SOASTA provides numerous options for automatied build integration; including using SCommand with its accompanying Ant Task, using the Jenkins Plugin in tandem with SCommand and the Jenkins CI tool, by using the Bamboo CI tool, or even by using Make. For an introduction to the various automated build options available to you, see How do I incorporate SOASTA CloudTest into an automated build?. If you already are a user of Jenkins/Hudson, or are a Bamboo user, refer to any of the following documents for extensive coverage:
    • Most Scheduling applications can execute Operating System commands, scripts, or "batch files". Therefore, if a copy of scommand is accessible to your Scheduling application you should be able to schedule any of the operations that scommand provides.

 

SCommand Syntax

 

To run SCommand on Windows, use the following syntax:

C:\> scommand\bin\scommand.bat [parameters]

To run SCommand on Mac OS X or Unix, use the following syntax:

$ scommand/bin/scommand [parameters]

SCommand is invoked by specifying the command type using the "cmd" parameter. A common mistake is forgetting to put "cmd=" before the command type. E.g.:

Incorrect: scommand delete
Correct: scommand cmd=delete

The "url", "username", and "password" parameters are always required. They should be set to the SOASTA CloudTest URL, your SOASTA CloudTest user name, and your SOASTA CloudTest password. For example:

 

scommand url=http://<CloudTest URL>/concerto username=bob password=secret

Here is a complete example, which will delete the Test Composition named "/My Comp":

 

scommand cmd=delete url=http://<CloudTest URL>/concerto username=bob password=secret type=composition name="/My Comp"

 

 

It is not necessary to place the text after an "=" unless the following text includes one or more spaces, in which case it should be entered in quotations as shown in the composition name above, where,: name="/My Comp".

SCommand Reference

 

The Command-Line Client provides access to a CloudTest instance and its repository via the following commands. Note that each command requires the following universal command parameters:

Available Commands

CommandDescription
deleteDeletes a Repository object.
drainSets the CloudTest services to "drain" mode.
exportExports a Repository object to XML format.
helpDisplays scommand help. Type 'scommand help <subcommand>' for help on a specific subcommand.
importImports Repository objects from a file (or list of files).
listDisplays a list of Repository objects.
playPlays a composition or playlist.
startStarts a monitor.
statusDisplays the current status of the CloudTest services.
stopStops a composition, playlist, or monitor.
start-gridStart the grid.
terminate-gridTerminates the grid.
start-rsdbStars results database.
terminate-rsdbTerminate results database.
start-envStarts the test environment.
terminate-envTerminates the test environment.

 

Note: Click here for information on the CloudTest Jenkins Plugin.

 

Common parameters (used by all commands):

 

ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)

sockettimeout=TIMEOUT

Socket timeout (optional)

keystore=KEYSTORE

Path to client key store (optional)

keystorepass=PASSWORD

The password for the client key store (optional)

Delete Command

 

The Delete command deletes a SOASTA repository object.

Usage: scommand cmd=delete

Delete Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
type=TYPEThe type of repository object to delete. Valid types are: composition, messageclip, result, playlist, target,
'transition', monitor, monitordata, user, and tenant.
maxage=DAYSThe maximum age as an integer, in days, of the item to delete.
name=NAMEThe name of the repository object to delete.

 

For example, to delete the composition named "/Load Tests/Comp 1":

scommand cmd=delete type=composition name="/Load Tests/Comp 1" username=bob \
password=secret url=http://<CloudTest URL>/concerto

To delete all results older than 7 days:

scommand delete type=result maxage=7 username=bob \
password=secret url=http://<CloudTest URL>/concerto

 

Drain Command

The Drain command allows a server administrator to gracefully take a SOASTA server offline. While using 'drain' existing connections are allowed to continue but new connections are refused.

Usage: scommand cmd=drain

Drain Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
service=SERVICEThe name of the service to set to "drain" mode (i.e. 'repository', 'maestro', 'results', monitor, or 'all'). If service is omitted, then 'all' is assumed.

 

For example, to drain the service named "maestro" for the given CloudTest instance:

scommand cmd=drain service=maestro username=bob \
password=secret url=http://<CloudTest URL>/concerto

 

Export Command

The Export command exports a repositiory object such as a composition or a result to XML format.

Usage: scommand cmd=export

Export Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
type=TYPEThe type of the repository object to export. Valid types are:
composition, messageclip, result, playlist, target, transition, monitor, user, and tenant.
name=NAMEThe name of the result object to export.
id=IDThe id of the result object when a composition completes execution.
dependencies=[yes|no]Specifies whether to include objects upon which the object being exported depends.
start=STARTDATEThe start date for exporting monitor data (optional). Must be of form MM/dd/yyyy or MM/dd/yyyy HH:mm:ss.
end=ENDDATEThe end date for exporting monitor data (optional). Must be of form MM/dd/yyyy or MM/dd/yyyy HH:mm:ss.
file=FILEThe file to write the output format to (optional). If the 'file' option is omitted, then XML output will be written to the command line (standard out).
format=FORMATThe format to write is either XML (default) or CSV (for result). If the 'format' option is omitted, then the XML output will be written to the command line (standard out).
resultSource=SOURCE

Specify the result source whenever specifying a widget to export (to XML only). This corresponds to the widget data source (i.e.the Export box, Data Source field selections, such as Clip Details, Collection Details, etc.) to write. The resultSource can be one of the following:

 

resultBasic –  same as the Export box, Data Source selection, Basic Information
resultClipDetails –  same as the Export box, Data Source selection, Clip Details
resultClipElementAggregates –  same as the Export box, Data Source selection, Clip Element Aggregate 
resultClipElementDetails –  same as the Export box, Data Source selection, Clip Element Details
resultClipElementPropertyAggregates –  same as the Export box, Data Source selection, Clip Element Properties 
resultClipAggregates –  same as the Export box, Data Source selection, Clip Aggregate
resultCollectionAggregates –  same as the Export box, Data Source selection, Collection Aggregate
resultCollectionDetails –  same as the Export box, Data Source selection, Collection Details
resultCompositionElementPropertyAggregates –  same as the Export box, Data Source selection, Composition Element Properties
resultEvents –  same as the Export box, Data Source selection, Event Source
resultFundamentalSummary –  same as the Export box, Data Source selection, Fundamentals Summary
resultPageAverageDurations –  same as the Export box, Data Source selection, Page Average Durations
resultPageCompletions –  same as the Export box, Data Source selection, Page Completions
resultTimeAggregates –  same as the Export box, Data Source selection, Time Aggregate
resultTimeAggregatesErrorsOnly –  same as the Export box, Data Source selection, Error Aggregate
resultTrackAggregates –  same as the Export box, Data Source selection, Track Aggregate
resultTransactionAverageDurations –  same as the Export box, Data Source selection, Transaction Average Durations
resultTransactionCompletions –  same as the Export box, Data Source selection, Transaction Completions 
resultURLAggregates –  same as the Export box, Data Source selection, URL Aggregate

analytics=[true|false]

True to export monitor data rather than the repository object


Exporting repository objects such as the parts of a test requires the default XML format. Format is typically omitted unless exporting to CSV. When doing so, use format=CSV and then also specify resultSource (e.g. the widget whose data will be exported for the given result).

For example, to export the composition named "/Load Tests/Comp 1" to a file called cmp1.xml:

scommand cmd=export type=composition name="/Load Tests/Comp 1" file=cmp1.xml \
username=bob password=secret url=http://<CloudTest URL>/concerto

In another example, we will use scommand to retrieve composition results and export them in CSV format for spreadsheet display:

scommand cmd=export username=bob password=secret type=result 
file=myexport.csv name="/Directory/CompositionName/ResultNameDemo" 
format=csv resultSource=resultTimeAggregates

Import Command

The Import command Imports repository objects from a file containing the XML-formatted version of those objects.

Usage: scommand cmd=import

Import Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
file=FILEThe name or complete path of the file to import.
verbose=[yes|no]Specifies whether to display detail information about the import.
mode=MODEThe conflict resolution mode to use (i.e. 'error', 'skip', 'overwrite' or 'rename')
mobileappname=NAMEThe name of Mobile App Object if an App Binary is being imported (e.g. expressed as a path to the file to upload).

For example, to Import the file "myobjects.xml", skipping any objects that are already in the Repository:

scommand cmd=import file=myobjects.xml mode=skip username=bob \
password=secret url=http://<CloudTest URL>/concerto

Note: You can also add your mobile app to its corresponding repository object via the scommand utility using the mobileappname parameter:

cmd=import file="/Users/username/Desktop/apps/ios/stockfish/Stockfish.ipa" username=bob password=secret url=http://<CloudTest URL>/concerto mobileappname="Test App 2"

List Command

The List command displays a list of repository objects.

Usage: scommand cmd=list

List Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
type=TYPEThe type of repository object to list. Valid types are composition, messageclip, result, playlist, target, transition, monitor, monitordata, user, tenant and propertyset.

 

For example, to list all compositions in the Repository:

scommand cmd=list type=composition username=bob password=secret \
url=http://<CloudTest URL>/concerto

Play Command

The Play command initiates a composition or playlist. Users should pay close attention to the Play command output options, format and file, by which additional complexity can be achieved.

Usage: scommand cmd=play

Play Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
name=NAMEThe name of the object to play.
type=TYPEThe type of object to play. Valid types are composition or playlist. If the 'type' option is omitted, then composition is assumed.
wait=[yes|no]Specify whether to wait for the object to finish playing. If the 'wait' option is omitted, then 'no' is assumed.
format=FORMATThe display format to use (i.e. 'text', 'xml', or 'junitxml'). If the 'format' option is omitted, then 'text' is assumed. When the format is junitxml, users can also use the validation parameter to specify a transaction name, a transaction metric to use, and to set a threshold value to validate.
file=FILEThe file to write the output to (optional). If the 'file' option is omitted, then the output will be written to the command line (standard out).
seeddatakey[NAME]=passwordSpecify a password for the given encrypted seed data file.
systemproperty="PROPERTY PATH=VALUE"Specify a system property's path and its value (optional).
customproperty="PROPERTY PATH=VALUE"Specify a custom property's path and its value (optional).
failonerror=[yes|no]This parameter will fail the test on error in Continuous Integration (CI) environments. When this parameter is set to yes, if the composition playback fails on a validation or any clip-related error, then Jenkins or Bamboo will also fail the job and note the scommand return code as an error.
validation=/transactionname/transactionmetric/transactionthresholdThis parameter will validate the specified transaction by name, using one of the supported metrics (supported metrics are listed below) and a value in milliseconds.
loadonserver=SERVERNAMEName of the server where the composition will be loaded (optional).[Requires SOASTA build 8744.49 or later.]
resultsdatabase=RSDBNAMEName of the Results Database that will collect the results (optional). [Requires SOASTA build 8744.49 or later.]
resultname=RESULTNAMEName of the result to create.
errorretrycount=ERRORRETRYCOUNTIf an error is ecountered when playing a composition, then this is the amount of retries that will be attempted until it passes or hits that count.

 

For example, to play the composition named "/Load Tests/Comp 1":

scommand cmd=play name="/Load Tests/Comp 1" username=bob \
password=secret url=http://<CloudTest URL>/concerto

For example, to play the playlist named "/Load Tests/Complete Set of Tests":

scommand cmd=play type=playlist name="/Load Tests/Complete Set of Tests" \
username=bob password=secret url=http://<CloudTest URL>/concerto

For example, to play the composition named "/Load Tests/Comp 1" while specifying passwords for two encrypted seed data objects:

scommand cmd=play name="/Load Tests/Comp 1" username=bob password=secret url=http://<CloudTest URL>/concerto \
seeddatakey[/Data/List1]=password1 seeddatakey[/Data/List2]=password2

For example, to play the composition named "/Load Tests/Comp 1" while specifying the target "Load Test on Mobile" to use for the composition:

scommand cmd=play name="/Load Tests/Comp 1" username=bob \
password=secret url=http://<CloudTest URL>/concerto
systemproperty="Band 1/Track 1/Clip 1/Load Test on Mobile/DeviceAgent=iPad"

For example, to set a transaction threshold on a transaction named t1 in order to validate a given metric (i.e. AverageResponseTime) using a value specified in milliseconds:

scommand url=<CloudTest URL>/concerto/ username=soasta password=secret cmd=play wait format=junitxml name=/Demo/comp1 validation=t1/AverageResponseTime/100 \
password=secret url=http://<CloudTest URL>/concerto

Transaction Threshold Metrics


The following transaction threshold metrics are included in this release:

  • AverageResponseTime – The average amount of time spent establishing the connection, sending the request, and receiving and processing the response for objects in this transaction. Response time excludes any time spent waiting for a connection to be available from the internal connection pool
  • AverageDuration  –  The average time it takes to complete the transaction. This is the effective time of the transaction, which is the total amount of time in milliseconds when at least one or more clip elements were executing within the transaction or its children.
  • 90thPercentile – CloudTest calculates a 1-tailed confidence interval, meaning that the outliers removed to obtain the 90th percentile are the slow response times, but not the really fast ones.
  • MaxDuration - The longest effective duration for all of the transaction's iterations.
  • MinDuration - The shortest effective duration for all of the transaction's iterations.
  • MinResponseTime – The smallest value of the transaction¢s duration for all actions in it and any containers it contains that did complete a request.
  • MaxResponseTime – The largest value of the transaction¢s duration for all actions in this container and containers it contains that did complete a request.
  • TotalBytesSent – The sum of all of the Total Bytes Sent values for all actions in this transaction and containers it contains that did complete a request.
  • ErrorsPerTransaction – Non-zero if any items in this transaction or the containers it contains had errors. "Having errors," means an item that completed successfully but generated events of level "Error" during play, as well as items that failed during play.
  • MinimumTransactionCount – The smallest sum of the transaction's that completed a request.

Start Command

The Start command starts a monitor.

Usage: scommand cmd=start

Start Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
name=NAMEThe name of the monitor to start. For example, name="/My Monitor"
type=TYPEThe type of object for which to start a monitor. Valid types are composition or playlist. If the 'type' option is omitted, then composition is assumed.
wait=[yes|no]Specify whether to wait for the object to finish playing. If the 'wait' option is omitted, then 'no' is assumed.

 

For example, to start a Monitor from the command line, use the start command with the parameter type=monitor:

 

scommand cmd=start url=http://<CloudTestURL>/concerto username=bob password=secret type=monitor name="/My Monitor"

If the Monitor starts successfully, scommand will output an instance ID that will be used to stop the Monitor later on. For example:

 

The monitor '/My Monitor' was loaded successfully, with instance ID '7781-c1ea3960c1ee041b:5e03cfcf:11929ca1f8e:-7ff4'.
The monitor has started.

In this example, you would stop the Monitor use the following command:

 

scommand cmd=stop url=http://<CloudTestURL> username=bob password=secret type=monitor instanceid="7781-c1ea3960c1ee041b:5e03cfcf:11929ca1f8e:-7ff4"

 

Status Command

The Status command displays the current status of the CloudTest services.

Usage: scommand cmd=status

Status Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
format=FORMATthe display format to use ('text' or 'xml').
service=SERVICEThe name of the service for which to display status (i.e. 'repository', 'maestro', 'results', monitor, or 'all'). If the 'service' option is omitted, then the status for all services will be displayed.
file=FILESpecify the file to write the output to (optional). If the 'file' option is omitted, then the output will be written to the command line (standard out).

 

For example, to get an Instance ID for a playing composition you'd like to stop:

scommand cmd=status service=maestro username=Sbob password=secret url=http://<CloudTest URL>/concerto format="text" >repository.txt
password=secret url=http://<CloudTest URL>/concerto

Will get a return value with the following sections (the file length will depend on how busy your CloudTest instance is):

Maestro status: ===============  Running compositions: -------------------- Instance ID: 1-BEDA5E0F-2927-49A6-905C-2B707A12C3E6, composition: /Composition 1 created on June 24, 2013 12:25:58 PM PDT, played by: bob, status: Completed Instance ID: 1-CF6158F5-03B8-4F9B-A70D-BBB38C8F558F, composition: /Composition 2, played by: bob, status: Playing

To check the status of the Monitor Service from the command line, use the status command with the parameter service=monitor. For example:

scommand cmd=status service=monitor url=http://<CloudTest URL>/concerto username=bob password=secret

 

Stop Command

The Stop command stops a composition, playlist, or monitor. When stopping a composition or playlist, the instance ID must be used. When stopping a monitor, the name can be used. If the 'type' option is omitted, then composition is assumed.

To obtain the instance ID, use the "status" command.

 

Usage: scommand cmd=stop

Status Options
ParameterDescription
username=USERNAMESOASTA CloudTest user name
password=PASSWORDSOASTA CloudTest password
url=URLSOASTA CloudTest URL to connect
httpproxyhost=SERVERHTTP proxy server name (optional)
httpproxyport=PORTHTTP proxy port (optional)
type=TYPEThe type of object to stop (i.e. composition, playlist, monitor). If the 'type' option is omitted, then composition is assumed.
instanceid=INSTANCEIDThe ID of the composition instance to stop. Use scommand=status and the service=maestro parameter to get an Instance ID for all running compositions.
file=FILESpecify the file to write the output to (optional). If the 'file' option is omitted, then the output will be written to the command line (standard out).

 

For example, to stop the composition with the given composition ID:

scommand cmd=stop instanceid=1-BEDA5E0F-2927-49A6-905C-2B707A12C3E6 \
username=bob \
password=secret url=http://<CloudTest URL>/concerto

For example, to stop the monitor named "/Monitors/Web Farm CPU":

scommand cmd=stop type=monitor name="/Monitors/Web Farm CPU" \
username=bob \
password=secret url=http://<CloudTest URL>/concerto

Attachments

    Outcomes