Python STC ReST API Client: stcrestclient

The stcrestclient package provides the stchttp ReST API library module. This allows simple function calls, nearly identical to those provided by StcPython.py, to be used to access TestCenter server sessions via the STC ReST API.

The stcrestclient package also includes the command-line shell tccsh that lets you work interactively with remote STC sessions via the ReST API. This is useful for testing and debugging without having to write any code.

Basic ReST functionality is provided by the resthttp module, and may be used for writing ReST clients independent of STC. This module is built on top of the Requests package.

All code works with Python2.7 and Python3.x.

Topics

Quick Start

Get Python pip if not already installed (Download https://bootstrap.pypa.io/get-pip.py):

python get-pip.py
Install latest stcrestclient:

pip install -U stcrestclient
Interact with TestCenter server using the command-line shell:

tccsh
Get information about a TestCenter server (and check if it is running):

stcinfo server_addr

Write Python code to talk with TestCenter server:

python

>>> from stcrestclient import stchttp
>>> stc = stchttp.StcHttp('stcserver.somewhere.com', timeout=5)
>>> sid = stc.new_session('JoeUser', 'ExampleTest')
>>> stc.system_info()

Install client adapter for Python automation scripts to use ReST API, without any code change:

python -m stcrestclient.adapt
export STC_REST_API=1
export STC_SERVER_ADDRESS=10.107.119.174'

Display API documentation:

pydoc stcrestclient.stchttp

Installation

Install Using pip

Make sure Python pip is installed on you system. If you are using virtualenv, then pip is already installed into environments created by virtualenv, and using sudo is not needed. If you do not have pip installed, download this file: https://bootstrap.pypa.io/get-pip.py and run python get-pip.py. If installing into your system Python, you will need sufficient privileges for this, as wall as for the commands below.

To install or upgrade to the latest, use pip to install from pypi:

pip install -U stcrestclient

Or, install from the repository archive URL:

pip install -U https://github.com/Spirent/py-stcrestclient/archive/master.zip

Show information about stcrestclient:

If you want to check if the stcrestclient package is installed and see information about the installed package use the following command:

pip show stcrestclient

Install From Source

The stcrestclient package is installed from source using distutils in the usual way. Download the source distribution first. Unzip the zip archive and run the setup.py script to install the package site-wide. Here are to commands to do that:

wget https://github.com/Spirent/py-stcrestclient/archive/master.zip py-stcrestclient.zip
unzip py-stcrestclient.zip
cd py-stcrestclient-*
sudo python setup.py install

You can also clone the repository from GitHub. Instructions for this not included here.

Using the stchttp module

To use the STC ReST client library, import the stchttp.py module, create a new session or join an existing session, and then call the STC API automation functions provided by the module.

from stcrestclient import stchttp
stc = stchttp.StcHttp('stcserver.somewhere.com')

# Set seconds to wait for response.  A zero-value means no timeout.
stc.set_timeout(5)

# Create and join new session
sid = stc.new_session('JoeUser', 'ExampleTest')

# Join an already existing session.
stc.join('OtherTest - JoeUser')

# Get system information
stc.system_info()

# Create a Project
project = stc.create('project')

# Create Port under project
port_handle = stc.create('port', project)

# Connect to a chassis
stc.connect('172.16.23.54')

# Configure port location (params as kwargs or dictionary)
stc.config(port_handle, location='//172.16.23.54/1/1')
stc.config(port_handle, {'location': "//172.16.23.54/1/1"})

# Create StreamBlock under Port
sb_handle = stc.create('streamBlock', port_handle)

# Apply config
stc.apply()

# Run STAK command to archive log files
stc.perform('spirent.core.ArchiveDiagnosticLogsCommand')

# Wait for sequencer to finish
stc.wait_until_complete(timeout=30)

# Write a message to the log file
stc.log('INFO', 'Done with my test')

# Get a list of available files
files_list = stc.files()

# Download and save the diagnostics.tgz file
name, size = stc.download('diagnostics.tgz')

# ...Or, download all files
name_size_dict = stc.download_all()

# Upload config file
stc.upload(config.xml')

# Load STC config from file (params as kwargs or dictionary).
stc.perform('LoadFromXml', filename='config.xml')
stc.perform('LoadFromXml', {'filename': 'config.xml'})

# Detach from and delete the session
stc.end_session(end_tcsession=True)

For example usage, look in the examples directory for Python code examples. The examples, like the client lib, will run with either Python2.7 or Python3.x. The print out command line help for a specific function above, use pydoc. For example: pydoc stcrestclient.stchttp.StcHttp.new_session

Using the ReST API Command-line Shell: tccsh

This is an interactive command shell that provides Session Manager and Automation API functionality using a command-line interface. This command accesses a TestCenter Server over its HTTP interface, so no local BLL installation is needed. This utility is primarily useful for testing and debugging the ReST API. It should run on any platform with Python 2.7 or 3.x.

To start the shell, use the following command:

tccsh

python -m stcrestclient.tccsh

You will be prompted for the server address to connect to. You can also supply the server address on the command line: tccsh 10.8.232.105 To see command line options: tccsh --help

usage: tccsh server [options]
       python -m stcrestclient.tccsh server [options]

Command shell that provides STC Automation API functionality using an
interactive command line interface, or command file.

positional arguments:
  server                Address of TestCenter server to connect to.

optional arguments:
  -h, --help
      show this help message and exit

  -c COMMAND_STRING
      Command string. Multiple commands are separated by ";" (semicolon).

  --debug, -d
      Enable debug output.

  --file FILE_PATH, -f FILE_PATH
      Read commands from the specified file.

  --port PORT, -p PORT
      Server TCP port to connect to (default 80).

Commands can be entered from a file (--file) or from a command string (-c), as an alternative to the normal interactive mode.

Interactive tccsh

Once started and connected to a server, you will see a prompt that contains the address of the server you are connected to.

Type help to see help info on the available commands. This displays the help menu:

Documented commands (type help <topic>):
========================================
chassis       exit           recording_on    stc_disconnectall  
chassis_info  files          server          stc_get            
connections   help           set_timeout     stc_help           
debug_off     info           stc_apply       stc_log            
debug_on      is_connected   stc_config      stc_perform        
delete        join           stc_connect     system_info        
delete_all    kill           stc_connectall  upload             
download      ls             stc_create      wait_until_complete
download_all  new            stc_delete    
end           recording_off  stc_disconnect

To see help for a command, type help followed by the command name. For example, type help new to see help on the new command.

Use Tab for command auto-completion. Command auto-completion may not work on Windows.

The interactive shell has a recording feature that is enabled by the recording_on command. This records commands, entered interactively, to a file that can be played back later through tccsh. Executing the recorded commands is done by running tccsh and specifying the file containing the recorded commands, using the --file command line option.

Command-line tccsh

The tccsh shell can also be use on the command-line, by specifying a file containing tccsh commands, or by providing a command string.

A file is provided using the --file command line option. A command file contains commands that are executed in order, and each command is on a separate line. Comment lines (lines starting with "#") and blank lines are ignored.

A command string is provided using the -c command line option. A number of commands can be specified, each separated by a ";" semicolon. For example:

tccsh server -c 'new test1 user=joe; stc_create project; stc_create port project1'

The above will create a new test session, create a project, and create a port object under the project. The output looks like this:

Created and joined session: test1 - jdoe
created: project1
created: port1

Automation Client ReST API Adapter

This package includes a ReST API client adapter module. The ReST API client adapter is functionally identical to the legacy StcPython.py module, except that it communicates with the STC ReST API. Without requiring any code changes, this allows STC automation scripts to communicate over ReST, and not need a local STC installation. This ReST adapter enables ReST API access if the environment variable STC_REST_API is set to a non-empty value. If STC_REST_API is not set, then the non-rest STC client module is loaded if there is a local STC installation.

Installing Client Adapter module

To enable existing Python automation scripts to use the STC ReST API, run the adapt script:

python -m stcrestclient.adapt

This installs a new StcPython.py client module, that allows existing automation scripts to work using either the ReST API adapter or the legacy client module. When the above command is run from within the STC installation directory, StcPython.py is replaced with a new file that operates using ReST or legacy (non-ReST) mode, depending on whether the STC_REST_API environment variable is set.

Activate ReST adapter: export STC_REST_API=1; export STC_SERVER_ADDRESS=labserve_addr
Deactivate ReST adapter: unset STC_REST_API

Set STC_REST_API and STC_SERVER_ADDRESS in the login profile to avoid having to set these every login. This way automation scripts will use ReST by default.

Nothing about the Python automation clients needs to change. They can be run as normal, and can even connect to existing existing TestCenter server sessions.

Running Without STC Installation

Installing the ReST adapter and setting STC_REST_API and STC_SERVER_ADDRESS allows existing automation scripts to run on a system where there is no STC installation. All that is required on the system Python, the stcrestclient package, and the StcPython.py file that was replaced when the adapter was installed.

To run your Python automation scripts, have StcPython.py in the same directory as your scripts, or its location is in PYTHONPATH, set the STC_REST_API and STC_SERVER_ADDRESS environment variables, and then run your the automation scripts. The automation scripts should operate using ReST.

Existing STC Sessions

If a session, identified by the specified user and session name, already exists then the adapter raises an exception. If this is not the desired behavior, then this can be changed by setting the value of the EXISTING_SESSION environment variable, or passing the existing_session argument into the new_session() function. The value of existing_session determines the behavior, and the value may be one of the following: kill, join

kill: Terminate the existing session, and create a new one.
join: Continue using the existing session.

Any other value results in the default behavior, which is to raise an exception if the specified session already exists, and create a new session otherwise.

Environment Variables

STC_SERVER_ADDRESS specifies the STC server (Lab Server) addres.
STC_SESSION_NAME specifies the name label part of session ID.
EXISTING_SESSION specifies the behavior when the specified session already exists. Recognized values: "kill", "join"

TestCenter Server Information.

The stcrestclient package includes a command, systeminfo, to retrieve STC and API information from a system running a TestCenter server. This module is provided as a convenient command line tool to get information about a TestCenter server.

To get information about a TestCenter server use the following command:

stcinfo server_addr or python -m stcrestclient.systeminfo server_addr

Ending Sessions with stcrestclient

When using `stchttp` module

A session can be ended in three ways, depending on the value of the end_tcsession parameter of the StcHttp.end_session() method:

end_tcsession=None: Stop using session locally, do not contact the server.
end_tcsession=False: End client controller, but leave test session on server.
end_tcsession=True: End client controller and terminate test session (default).

Specifying end_tcsession=False ends the client controller. This means that it detaches the ReST API's STC controller from the test session. This is useful to do before attaching an STC GUI or legacy automation script, to prevent having multiple controllers that may interfere with each other. This requires that the server is running version 2.1.5 or later of the STC ReST API.

When using `tccsh` shell

When using the tccsh command shell, the equivalent commands for the above items are:

Invoke join with no argument: Stop using session locally
Invoke end and specify "no": End client controller only
Invoke end and specify "yes": End client controller and test session

Automation API to ReST API Quick Reference

Automation API	StcHttp API	ReST Equivalent
apply	`apply()`	PUT http://host.domain/stcapi/apply
config	`config(obj, ..)`	PUT http://host.domain/stcapi/objects/{object}
connect	`connect([chassis, ..])`	PUT http://host.domain/stcapi/connections/{chassis}
create	`create(obj_type, ..)`	POST http://host.domain/stcapi/objects/
delete	`delete(obj)`	DELETE http://host.domain/stcapi/objects/{object}
disconnect	`disconnect([chassis, ..])`	DELETE http://host.domain/stcapi/connections/{chassis}
get	`get(obj, ..)`	GET http://host.domain/stcapi/objects/{object}
help	`help(subject)`	GET http://host.domain/stcapi/help/{subject}
help list	`help('list', ..)`	GET http://host.domain/stcapi/help/list?{search_info}
log	`log(level, msg)`	POST http://host.domain/stcapi/system/log/
perform	`perform(command, ..)`	POST http://host.domain/stcapi/perform/{command}
release	`perform('releasePort', ..)`	See perform
reserve	`perform('reservePort', ..)`	See perform
sleep	N/A	NOT SUPPORTED -- client must implement
subscribe	`perform(` `'ResultsSubscribe', ..)`	See perform
unsubscribe	`perform(` `'ResultDataSetUnsubscribe', ..)`	See perform
waitUntilComplete	`wait_until_complete(timeout)`	Polls sequencer state

Note: The STC ReST API supports additional methods, not specified in this table, that perform common STC automation tasks. For example, the REST API provides methods for connecting or disconnecting all chassis using a POST request.

lizhengda/py-stcrestclient