pysys.process.user module

class pysys.process.user.ProcessUser

Bases: object

Class providing basic operations over interacting with processes.

The ProcessUser class provides the minimum set of operations for managing and interacting with processes. The class is designed to be extended by the pysys.baserunner.BaseRunner and pysys.basetest.BaseTest classes so that they prescribe a common set of process operations that any child test can use. Process operations have associated potential outcomes in their execution, e.g. BLOCKED, TIMEDOUT, DUMPEDCORE etc. As such the class additionally acts as the container for storing the list of outcomes from all child test related actions.

Variables:

• input (string) – Location for input to any processes (defaults to current working directory)
• output (string) – Location for output from any processes (defaults to current working directory)

__init__()

Default constructor.

abort(outcome, outcomeReason, callRecord=None)

Raise an AbortException.

Parameters:

• outcome – The outcome, which will override any existing outcomes previously recorded.
• outcomeReason – A string summarizing the reason for the outcome

addCleanupFunction(fn)

Registers a zero-arg function that will be called as part of the cleanup of this object.

Cleanup functions are invoked in reverse order with the most recently added first (LIFO), and before the automatic termination of any remaining processes associated with this object.

e.g. self.addCleanupFunction(lambda: self.cleanlyShutdownProcessX(params))

addOutcome(outcome, outcomeReason='', printReason=True, abortOnError=None, callRecord=None)

Add a validation outcome (and optionally a reason string) to the validation list.

The method provides the ability to add a validation outcome to the internal data structure storing the list of validation outcomes. Multiple validations may be performed, the current supported validation outcomes of which are:

SKIPPED: An execution/validation step of the test was skipped (e.g. deliberately) BLOCKED: An execution/validation step of the test could not be run (e.g. a missing resource) DUMPEDCORE: A process started by the test produced a core file (unix only) TIMEDOUT: An execution/validation step of the test timed out (e.g. process deadlock) FAILED: A validation step of the test failed NOTVERIFIED: No validation steps were performed INSPECT: A validation step of the test requires manual inspection PASSED: A validation step of the test passed

The outcomes are considered to have a precedence order, as defined by the order of the outcomes listed above. Thus a BLOCKED outcome has a higher precedence than a PASSED outcome. The outcomes are defined in pysys.constants.

Parameters:

• outcome – The outcome to add
• outcomeReason – A string summarizing the reason for the outcome
• printReason – If True the specified outcomeReason will be printed
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting if not specified)
• callRecord – An array of strings indicating the call stack that lead to this outcome. This will be appended to the log output for better test triage.

allocateUniqueStdOutErr(processKey)

Allocate filenames of the form processKey[.n].out (similarly for .err).

Parameters:processKey – A user-defined identifier that will form the prefix onto which [.n].out is appended Returns:A STDOUTERR_TUPLE named tuple of (stdout, stderr) Return type:tuple

cleanup()

Cleanup function that frees resources managed by this object.

Should be called exactly once when this object is no longer needed. Instead of overriding this function, use addCleanupFunction.

getDefaultFileEncoding(file, **xargs)

Specifies what encoding should be used to read or write the specified text file.

This method is used to select the appropriate encoding whenever PySys needs to open a file, for example to wait for a signal, for a file-based assertion, or to write a file with replacements. Many methods allow the encoding to be overridden for just that call, but getDefaultFileEncoding exists to allow global defaults to be specified based on the filename.

For example, this method could be overridden to specify that utf-8 encoding is to be used for opening filenames ending in .xml, .json and .yaml.

A return value of None indicates default behaviour, which on Python 3 is to use the default encoding, as specified by python’s locale.getpreferredencoding(), and on Python 2 is to use binary “str” objects with no character encoding or decoding applied.

Parameters:

• file – The filename to be read or written. This may be an absolute path or a relative path.
• xargs – Ensure that an **xargs argument is specified so that additional information can be passed to this method in future releases.

Returns:

The encoding to use for this file, or None if default behaviour is to be used.

getExprFromFile(path, expr, groups=[1], returnAll=False, returnNoneIfMissing=False, encoding=None)

Searches for a regular expression in the specified file, and returns it.

If the regex contains groups, the specified group is returned. If the expression is not found, an exception is raised, unless getAll=True or returnNoneIfMissing=True. For example;

self.getExprFromFile(‘test.txt’, ‘myKey=”(.*)”’) on a file containing ‘myKey=”foobar”’ would return “foobar” self.getExprFromFile(‘test.txt’, ‘foo’) on a file containing ‘myKey=foobar’ would return “foo”

Parameters:

• path – file to search (located in the output dir unless an absolute path is specified)
• expr – the regular expression, optionally containing the regex group operator (…)
• groups – which regex groups (as indicated by brackets in the regex) shoud be returned; default is [‘1’] meaning the first group. If more than one group is specified, the result will be a tuple of group values, otherwise the result will be the value of the group at the specified index.
• returnAll – returns all matching lines if True, the first matching line otherwise.
• returnNoneIfMissing – set this to return None instead of throwing an exception if the regex is not found in the file
• encoding – The encoding to use to open the file. The default value is None which indicates that the decision will be delegated to the getDefaultFileEncoding() method.

getInstanceCount(displayName)

Return the number of processes started within the testcase matching the supplied displayName.

The ProcessUser class maintains a reference count of processes started within the class instance via the startProcess() method. The reference count is maintained against a logical name for the process, which is the displayName used in the method call to startProcess(), or the basename of the command if no displayName was supplied. The method returns the number of processes started with the supplied logical name, or 0 if no processes have been started.

Deprecated:The recommended way to allocate unique names is now allocateUniqueStdOutErr Parameters:displayName – The process display name Returns:The number of processes started matching the command basename Return type:integer

getNextAvailableTCPPort()

Allocate a TCP port.

getOutcome()

Get the overall outcome based on the precedence order.

The method returns the overall outcome of the test based on the outcomes stored in the internal data structure. The precedence order of the possible outcomes is used to determined the overall outcome of the test, e.g. if PASSED, BLOCKED and FAILED were recorded during the execution of the test, the overall outcome would be BLOCKED.

The method returns the integer value of the outcome as defined in pysys.constants. To convert this to a string representation use the LOOKUP dictionary i.e. :py:obj:`LOOKUP`[test.getOutcome()]

Returns:The overall outcome Return type:integer

getOutcomeReason()

Get the reason string for the current overall outcome (if specified).

Returns:The overall test outcome reason or ‘’ if not specified Return type:string

logFileContents(path, includes=None, excludes=None, maxLines=20, tail=False, encoding=None)

Logs some or all of the lines in the specified file.

If the file does not exist or cannot be opened, does nothing. The method is useful for providing key diagnostic information (e.g. error messages from tools executed by the test) directly in run.log, or to make test failures easier to triage quickly.

Parameters:

• path – May be an absolute, or relative to the test output directory
• includes – Optional list of regex strings. If specified, only matches of these regexes will be logged
• excludes – Optional list of regex strings. If specified, no line containing these will be logged
• maxLines – Upper limit on the number of lines from the file that will be logged. Set to zero for unlimited
• tail – Prints the _last_ ‘maxLines’ in the file rather than the first ‘maxLines’
• encoding – The encoding to use to open the file. The default value is None which indicates that the decision will be delegated to the getDefaultFileEncoding() method.

Returns:

True if anything was logged, False if not

mkdir(path)

Create a directory, with recursive creation of any parent directories.

This function is a no-op (does not throw) if the directory already exists.

Parameters:path – The path to be created. This can be an absolute path or relative to the testcase output directory. Returns:the same path passed, to facilitate fluent-style method calling.

signalProcess(process, signal, abortOnError=None)

Send a signal to a running process (Unix only).

This method uses the pysys.process.helper module to send a signal to a running process. Should the request to send the signal to the running process fail, a BLOCKED outcome will be added to the outcome list.

Parameters:

• process – The process handle returned from the startProcess method
• signal – The integer value of the signal to send
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)

startProcess(command, arguments, environs=None, workingDir=None, state=11, timeout=600, stdout=None, stderr=None, displayName=None, abortOnError=None, ignoreExitStatus=None)

Start a process running in the foreground or background, and return the process handle.

The method allows spawning of new processes in a platform independent way. The command, arguments, environment and working directory to run the process in can all be specified in the arguments to the method, along with the filenames used for capturing the stdout and stderr of the process. Processes may be started in the FOREGROUND, in which case the method does not return until the process has completed or a time out occurs, or in the BACKGROUND in which case the method returns immediately to the caller returning a handle to the process to allow manipulation at a later stage. All processes started in the BACKGROUND and not explicitly killed using the returned process handle are automatically killed on completion of the test via the cleanup() destructor.

Parameters:

• command – The command to start the process (should include the full path)
• arguments – A list of arguments to pass to the command
• environs – A dictionary of the environment to run the process in (defaults to clean environment)
• workingDir – The working directory for the process to run in (defaults to the testcase output subdirectory)
• state – Run the process either in the FOREGROUND or BACKGROUND (defaults to FOREGROUND)
• timeout – The timeout period after which to termintate processes running in the FOREGROUND
• stdout – The filename used to capture the stdout of the process. Consider using allocateUniqueStdOutErr to get this.
• stderr – The filename user to capture the stderr of the process. Consider using allocateUniqueStdOutErr to get this.
• displayName – Logical name of the process used for display and reference counting (defaults to the basename of the command)
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)
• ignoreExitStatus – If False, non-zero exit codes are reported as an error outcome. None means the value will be taken from defaultIgnoreExitStatus, which can be configured in the project XML, or is set to True if not specified there.

Returns:

The process handle of the process (pysys.process.helper.ProcessWrapper)

Return type:

handle

stopProcess(process, abortOnError=None)

Send a soft or hard kill to a running process to stop its execution.

This method uses the pysys.process.helper module to stop a running process. Should the request to stop the running process fail, a BLOCKED outcome will be added to the outcome list. Failures will result in an exception unless the project property defaultAbortOnError=False.

Parameters:

• process – The process handle returned from the startProcess method
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)

waitForFile(file, filedir=None, timeout=30, abortOnError=None)

Wait for a file to exist on disk.

This method blocks until a file is created on disk. This is useful for test timing where a component under test creates a file (e.g. for logging) indicating it has performed all initialisation actions and is ready for the test execution steps. If a file is not created on disk within the specified timeout interval, the method returns to the caller.

Parameters:

• file – The basename of the file used to wait to be created
• filedir – The dirname of the file (defaults to the testcase output subdirectory)
• timeout – The timeout in seconds to wait for the file to be created
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)

waitForSignal(file, filedir=None, expr='', condition='>=1', timeout=60, poll=0.25, process=None, errorExpr=[], abortOnError=None, encoding=None)

Wait for a particular regular expression to be seen on a set number of lines in a text file.

This method blocks until a particular regular expression is seen in a text file on a set number of lines. The number of lines which should match the regular expression is given by the condition argument in textual form i.e. for a match on more than 2 lines use condition =”>2”. If the regular expression is not seen in the file matching the supplied condition within the specified timeout interval, the method returns to the caller.

Parameters:

• file – The absolute or relative name of the file used to wait for the signal
• filedir – The dirname of the file (defaults to the testcase output subdirectory)
• expr – The regular expression to search for in the text file
• condition – The condition to be met for the number of lines matching the regular expression
• timeout – The timeout in seconds to wait for the regular expression and to check against the condition
• poll – The time in seconds to poll the file looking for the regular expression and to check against the condition
• process – If a handle to the process object producing output is specified, the wait will abort if the process dies before the expected signal appears.
• errorExpr – Optional list of regular expressions, which if found in the file will cause waiting for the main expression to be aborted with an error outcome. This is useful to avoid waiting a long time for the expected expression when an ERROR is logged that means it will never happen, and also provides much clearer test failure messages in this case.
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)
• encoding – The encoding to use to open the file. The default value is None which indicates that the decision will be delegated to the getDefaultFileEncoding() method.

waitForSocket(port, host='localhost', timeout=60, abortOnError=None, process=None)

Wait until it is possible to establish a socket connection to a server running on the specified port.

This method blocks until connection to a particular host:port pair can be established. This is useful for test timing where a component under test creates a socket for client server interaction - calling of this method ensures that on return of the method call the server process is running and a client is able to create connections to it. If a connection cannot be made within the specified timeout interval, the method returns to the caller, or aborts the test if abortOnError=True.

Parameters:

• port – The port value in the socket host:port pair
• host – The host value in the socket host:port pair
• timeout – The timeout in seconds to wait for connection to the socket
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)
• process – If a handle to a process is specified, the wait will abort if the process dies before the socket becomes available.

waitProcess(process, timeout, abortOnError=None)

Wait for a background process to terminate, return on termination or expiry of the timeout.

Timeouts will result in an exception unless the project property defaultAbortOnError=False.

Parameters:

• process – The process handle returned from the startProcess method
• timeout – The timeout value in seconds to wait before returning
• abortOnError – If true abort the test on any error outcome (defaults to the defaultAbortOnError project setting)

writeProcess(process, data, addNewLine=True)

Write binary data to the stdin of a process.

This method uses the pysys.process.helper module to write data to the stdin of a process. This wrapper around the write method of the process helper only adds checking of the process running status prior to the write being performed, and logging to the testcase run log to detail the write.

Parameters:

• process – The process handle returned from the startProcess() method
• data – The data to write to the process stdin. As only binary data can be written to a process stdin, if a character string rather than a byte object is passed as the data, it will be automatically converted to a bytes object using the encoding given by locale.getpreferredencoding().
• addNewLine – True if a new line character is to be added to the end of the data string

pysys.process.user.STDOUTERR_TUPLE

alias of pysys.process.user.stdouterr