Introduction

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

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

SCommand communicates with the 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.

📘

Note

Use the SCommand built-in help system via the command "scommand help" while in a 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. For example, "scommand help delete".

Installing the CloudTest command line client (SCommand)

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

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

Common uses for the Command-line client

• Akamai CloudTest provides numerous options for automated 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 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:

• TouchTest(TM) Jenkins CI for iOS Tutorial – This tutorial presents the necessary procedures for incorporating TouchTest using Xcode into continuous integration environments that utilize Jenkins/Hudson with iOS.

• TouchTest(TM) Jenkins CI for Android Tutorial – This tutorial presents the necessary procedures for incorporating TouchTest using Eclipse into continuous integration environments that utilize Jenkins/Hudso with Android.

• TouchTest(TM) Appcelerator Jenkins CI for iOS Tutorial - This tutorial presents the necessary procedures for incorporating TouchTest using Titanium Studio into continuous integration environments that utilize Jenkins/Hudson.

• TouchTest(TM) Bamboo CI for iOS Tutorial – This tutorial presents the necessary procedures for incorporating TouchTest using Xcode into continuous integration environments that utilize Bamboo CI with iOS.

• 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 CloudTest URL, your CloudTest user name, and your 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

More information on the CloudTest Jenkins Plugin.

Common parameters (used by all commands):

Delete command

The Delete command deletes a CloudTest repository object.

Usage: scommand cmd=delete

Delete Options

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 server offline. While using 'drain' existing connections are allowed to continue but new connections are refused.

Usage: scommand cmd=drain

Drain options

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 repository object such as a composition or a result to XML format.

Usage: scommand cmd=export

Export options

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

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:///concerto mobileappname="Test App 2"

List command

The List command displays a list of repository objects.

Usage: scommand cmd=list

List options

For example, to list all compositions in the Repository:

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

Masschangeowner command

The masschangeowner command reassigns ownership of all objects from one user to another user.

Usage: scommand cmd=masschangeowner

Masschangeowner options

For example, to reassign ownership of all of username "John"'s objects, to username "Sally":

scommand cmd=MassChangeOwner name=”John” newname=“Sally” username=bob password=secret url=http://mysbox/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

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

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

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

Stop options

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