Collection of utilities to deal with the management of the different test cases of the suite.
Compiles the given test case on all the hosts in the system.
The building details and the respect of the convention are enforced by the Makefile and not further explained here.
Executes the given test case on all client hosts (normally onle one).
Scans the basedir (or the test-cases directory defined in the settings) for directories and returns a choice based on different criteria:
- No directories are found; raise a RuntimeError
- The name is set; check if it was found and if so return it
- Only one directory is found; return the found directory
- Multiple directories are found; ask the user to pick one
- If no measure case exist yet, a RuntimeError is thrown;
- If only one measure case is found, its path is returned;
- If more than one measure cases are found, then the user is asked to choose one between them.
The list presented to the user when asked to choose a case will be something like the following:
Multiple test cases found: [0]: simple [1]: complex Select a test case: _
Settings support for the whole pas package.
This module contains methods to load and temporarily store setting directives for the current execution.
Various shortcuts to access the different settings in a usage-oriented way are also provided.
General test suite environment management functions.
Remote JobMgr management utilities.
The following functions provide some wrappers around remote shell commands to easily start, stop, restart or otherwise interact with a POP-C++ job manager.
Kills ALL running job managers (and the relative search nodes) on the hosts provided by the context or (by default) on all known hosts.
Stops and restarts a currently running JobMgr instance on one or more (depending on the current context) remote nodes in a unique command.
This function is intended to be used to restart a single node. To restart all nodes of a system, use the startall function, which introduces some delays to allow a correct registration of the slaves by the master.
Restarts all nodes in the system using the stopall and startall functions.
Due to the introduction of the delays, the stop and start calls will not happen in the same command as for the restart function.
Starts a JobMgr instance on one or more (depending on the current context) remote nodes.
This function is intended to be used to start a single node. To start all nodes of a system, use the startall function, which introduces some delays to allow a correct registration of the slaves by the master.
Starts all nodes of the system grouped by roles with the necessary delays to allow a proper registration to the parent JobMgr.
The delay between the invocations can be set in the settings.
Stops a currently running JobMgr instance on one or more (depending on the current context) remote nodes.
This function is intended to be used to stop a single node. To stop all nodes of a system, use the startall function, which introduces some delays to allow a correct registration of the slaves by the master.
Stops all nodes of the system grouped by roles with the necessary delays to allow a proper registration to the parent JobMgr.
The delay between the invocations can be set in the settings.
Note that in this case the delays are not as important as in the start function on could probably safely be omitted. The behavior is preserved to grant compatibility with future versions of the JobMgr which possibly wants to execute some cleanup code before terminating.
In the meanwhile it is possible to set the delay to 0 in the settings.
Measure management functions.
Moves the relevant files to the shared directory by asking to empty the destination directory if needed.
Decodes the simplified XML representation of the given measure by adding a “decoded” element to each packet containing a payload.
The decoding is done using an XSL transformation coupled with an xslt python extension function which provides the “decoded” element given a payload text string.
Assembles all the acquired resources (such as source code, measures and log files) and generates an html page suitable for human interaction and analysis.
Scans the basedir (or the shared-measures directory defined in the settings) for directories and returns a choice based on different criteria:
- No directories are found; raise a RuntimeError
- The name is set; check if it was found and if so return it
- Only one directory is found; return the found directory
- Multiple directories are found; ask the user to pick one
Simplifies all the measure files in pdxml format of the given measure, converting them using the simplify XSL stylesheet. Old simplifications will be overwritten.
If the prettyprint optional argument is True, the result will be formatted using the xmllint tool.
Start a new named measure session in background on all interested hosts.
The hosts are retrieved from the ROLES setting directive and a measure is started for each one.
Local and remote shell commands execution.
These functions are mainly wrappers around those found in the fabric library.
Returns a fabric context manager configured to silently ignore all warnings about running commands.
Returns a fabric context manager which sets the hosts list to the given list.
If the passed hosts argument is a single string, it is silently converted to a list before.
Executes a local command without capturing and returning the output.
Thin wraper around the fabric.operations.local function
Executes the given remote command on the hosts list set in the current context.
If user is given or sudo evaluates to True, then a fabric.operations.sudo call is made, otherwise a simple fabric.operations.run.
Context manager that keeps directory state when calling operations.
Any calls to run, sudo or local within the wrapped block will implicitly have a string similar to "cd <path> && " prefixed in order to give the sense that there is actually statefulness involved.
Because use of cd affects all such invocations, any code making use of run/sudo/local, such as much of the contrib section, will also be affected by use of cd. However, at this time, get and put do not honor cd; we expect this to be addressed in future releases.
Like the actual ‘cd’ shell builtin, cd may be called with relative paths (keep in mind that your default starting directory is your remote user’s $HOME) and may be nested as well.
Below is a “normal” attempt at using the shell ‘cd’, which doesn’t work due to how shell-less SSH connections are implemented – state is not kept between invocations of run or sudo:
run('cd /var/www')
run('ls')
The above snippet will list the contents of the remote user’s $HOME instead of /var/www. With cd, however, it will work as expected:
with cd('/var/www'):
run('ls') # Turns into "cd /var/www && ls"
Finally, a demonstration (see inline comments) of nesting:
with cd('/var/www'):
run('ls') # cd /var/www && ls
with cd('website1'):
run('ls') # cd /var/www/website1 && ls
Note
This context manager is currently implemented by appending to (and, as always, restoring afterwards) the current value of an environment variable, env.cwd. However, this implementation may change in the future, so we do not recommend manually altering env.cwd – only the behavior of cd will have any guarantee of backwards compatibility.
Prompt user with text and return the input (like raw_input).
A single space character will be appended for convenience, but nothing else. Thus, you may want to end your prompt text with a question mark or a colon, e.g. prompt("What hostname?").
If key is given, the user’s input will be stored as env.<key> in addition to being returned by prompt. If the key already existed in env, its value will be overwritten and a warning printed to the user.
If default is given, it is displayed in square brackets and used if the user enters nothing (i.e. presses Enter without entering any text). default defaults to the empty string. If non-empty, a space will be appended, so that a call such as prompt("What hostname?", default="foo") would result in a prompt of What hostname? [foo] (with a trailing space after the [foo].)
The optional keyword argument validate may be a callable or a string:
Either way, prompt will re-prompt until validation passes (or the user hits Ctrl-C).
Examples:
# Simplest form:
environment = prompt('Please specify target environment: ')
# With default, and storing as env.dish:
prompt('Specify favorite dish: ', 'dish', default='spam & eggs')
# With validation, i.e. requiring integer input:
prompt('Please specify process nice level: ', key='nice', validate=int)
# With validation against a regular expression:
release = prompt('Please supply a release name',
validate=r'^\w+-\d+(\.\d+)?$')
Ask user a yes/no question and return their response as True or False.
question should be a simple, grammatically complete question such as “Do you wish to continue?”, and will have a string similar to ” [Y/n] ” appended automatically. This function will not append a question mark for you.
By default, when the user presses Enter without typing anything, “yes” is assumed. This can be changed by specifying default=False.
Various utilities to deal with remote tshark operations with support for features such as background execution, stop on request, and advanced tshark interactions.
Note that all of the commands which operate on remote hosts, respect the current set context to retrieve the host lists. When this list is not set or is empty, the command will be run on all hosts. Refer to the documentation on pas.shell to obtain further information.
Most of the command below use the tshark command-line tool directly; refer to its man page for the details about the usage.
Kills ALL running measures on the hosts provided by the context or (by default) on all known hosts.
Converts the pcap input file to XML and writes the output to outfile while filtering using the given display filter.
Refer directly to the tshark man page for further informations about the display filter syntax.