pyats.aereport package¶

Module:

AEReport

Authors:

Ahmad Barghout (abarghou), CSG Test - Ottawa Jean-Benoit Aubin (jeaubin), CSG Test - Ottawa

Description:

This module provide a mechanism to record logical test events, data, and results for storing and serialization into XML.

In Python ATS infrastructure, XML-RPC server infrastructure is used to allow multiple users, runs in parallel or testcase in parallel.

Notes:

class pyats.aereport.LoggingMode¶

Bases: object

Provide the available modes for logging.

FilePerTestcase = 1¶

SingleFile = 0¶

Subpackages¶

Submodules¶

`aerunner` – Aerunner¶

This module implements AERunner Class which intercepts easypy calls and invoke creation or setting of the corresponding AEReport elements/attributes.

class pyats.aereport.aerunner.AERunner(logsdir, logfilename, verbose=False, hostname='127.0.0.1', port=0)¶

Bases: object

This class receives calls from easypy, and other engines for starting and populating execution contexts (testsuite, testcase, subtest, etc) and their children. It determines the current context, validate the call, and invoke the corresponding API on the targeted element.

_aereport¶

The object containing all elements of the ResultsDetails.xml file

Type: AEReport

_clients¶

A tree structure to keep track of connected clients and their hierarchy

Type: ClientsTree

_error_msgs¶

A lookup containing messages for the commonly encountered errors

Type: dict

_hierarchy¶

An ordered list of the main execution contexts in the order of hierarchy (testsuite, testscript, testcase, etc)

Type: list

_log¶

Logger object

Type: logger

_logfilename¶

Name of the log file

Type: str

_logsdir¶

Full path to a directory where AERunner can create log files (and other files as needed)

Type: str

_port¶

Port number the server is using

Type: int or str

_strictness¶

Tolerance level of AERunner to invalid calls and operations. Can be Strict or Lenient

Type: Mode

_verbose¶

Verbosity of output

Type: bool

class Mode¶

Bases: object

Nested Enumeration of the different modes of execution in AERunner.

Strict mode: is a mode that does not tolerate invalid calls, and throws exceptions when they occur

Lenient mode: is a more tolerant mode that just logs warnings in case of invalid calls

Lenient = 0¶

Strict = 1¶

abort(kwargs)¶

Make sure the context contains runinfo, then add an abort

Parameters

condition (str) – condition of the abort
abortfile (str) – Abort file
pid (str int) – pid of the process

Example

>>> # Make sure current context contains runinfo
>>> aerunner.abort(abortfile='/path/to/abort/file1',
>>>                condition='acondition1')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

abort_testsuite(kwargs)¶

Make sure the context is testsuite, then add an abort if it doesnt already exists

Parameters

time – str Time/date of script abort
type – str Signal number received by signal handler
pid – str Process ID for the client child

Examples

>>> # Make sure current context contains runinfo
>>> aerunner.abort_testsuite(time='aTime',
>>>                          type='error')

Returns

Exception or None: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases

add_ats_packages(kwargs)¶

Make sure the context is Testsuite Add ats packages in tuple forms: (package,version)

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context contains testsuite
>>>  aerunner.add_ats_packages([('Csccon', '1.1'), ('aetest', '1.2')])

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

add_checkpoint(kwargs)¶

Make sure the current context is TestSection. If yes, add a checkpoint

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the checkpoint
result (str) – Result of the checkpoint

Example

# Make sure current context is testsection >>> aerunner.add_checkpoint(name=’aTestcaseaCheckpoint’, result=’Pass’)

add_testscript_aehandler(kwargs)¶

Adds an aehandler section in testscript.

Parameters

name (str) – handler proc name
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
condition (str) – Regexp condition for which the handler should be invoked such as fail, error, etc
type (str) – Default value = ‘testcase’. Possible values are: testcase (used for testcase/subtest) and section

Example

>>>  # Make sure current context is testscript
>>>  aerunner.add_testscript_aehandler('testscriptaehandler', 'acriteria', 'section')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

add_userdef(kwargs)¶

Make sure the context contains runinfo, then add an userdef

Parameters

name (str) – Name of the checkpoint
result (str) – Result of the checkpoint
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context contains runinfo
>>>  aerunner.add_userdef(name='aUserDefName',
>>>                       value='aSuperValue')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

disable_alignment(kwargs)¶

Disable alignment

Example

>>>  disable_alignment()

disable_count_common_result_summary(kwargs)¶

Disable common summary countEnable traceback

Example

>>>  disable_count_common_result_summary

disable_outofrange(kwargs)¶

Disable outofrange

Example

>>>  disable_outofrange()

disable_rerun(kwargs)¶

Disable rerun

Example

>>>  disable_rerun()

disable_sort(kwargs)¶

Disable sort

Example

>>>  disable_sort()

disable_traceback(kwargs)¶

Disable traceback

Example

>>>  disable_traceback()

disable_uniquesuites(kwargs)¶

Disable uniquesuites

Example

>>>  disable_uniquesuites()

disable_uniquetid(kwargs)¶

Disable uniquetid

Example

>>>  disable_uniquetid()

enable_alignment(kwargs)¶

Enable alignment

Example

>>>  enable_alignment()

enable_outofrange(kwargs)¶

Enable outofrange

Example

>>>  enable_outofrange()

enable_rerun(kwargs)¶

Enable rerun

Example

>>>  enable_rerun()

enable_sort(kwargs)¶

Enable sort

Example

>>>  enable_sort()

enable_traceback(kwargs)¶

Enable traceback

Example

>>>  enable_traceback()

enable_uniquesuites(kwargs)¶

Enable uniquesuites

Example

>>>  enable_uniquesuites()

enable_uniquetid(kwargs)¶

Enable uniquetid

Example

>>>  enable_uniquetid()

generate_diagnostics_report(kwargs)¶

Generates diagnostics report for easypy. Makes sure that cur_ctx is Testsuite, if yes generates a report.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.generate_diagnostics_report()

Returns

Dict of diags-report or None,
If there is data to create diagnostics report, it will return
a dictionary that has 2 key words (‘suite’, ‘jobexecution’.)
- Information related to suite level is under ‘suite’ key which – is also a dictionary.
- Information about the script and testcases is under – jobexecution list. Each element of this list represents a testscript.
{‘jobexecution’ ([{‘path’: PATH, ‘version’: VERSION, ‘testcases’: [{‘result’: ‘RESULT’, ‘tag’: ‘TAG’ ‘sections’: [{‘result’: ‘RESULT’, ‘pauses’: [], ‘diags’: [], ‘errors’: [], ‘name’: ‘NAME’, ‘comments’: []}], ‘swversion’: SWVERSION, ‘starttime’: ‘TIME’, ‘description’: ‘DESCRIPTION’, ‘hwversion’: HWVERSION, ‘name’: ‘NAME’, ‘fwversion’: FWVERSION, ‘stoptime’: ‘TIME’}], ‘name’: ‘NAME’, ‘pargs’: ‘ARGS’, ‘logfile’: ‘LOGFILE’}], ‘suite’: {‘image’: ‘IMAGE’, ‘release’: ‘RELEASE’, ‘params’: ‘PARAMS’, ‘testbed’: ‘TESTBED’, ‘name’: ‘NAME’}})
If there is a problem or there isn’t enough information it will
return None

generate_html_logs(kwargs)¶

generate_resultsdetails(pid)¶: Returns xml string for ResultsDetails.xml report

generate_resultsdetails_dom(pid)¶: Returns the dom for aereport

generate_resultssummary()¶: Returns xml string for ResultsSummary report

generate_script_report(kwargs)¶

generate_tims_report(kwargs={})¶

generates tims results file. By default, it writes the files to directory given by the user

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
tims (dict) – A dict that holds tims importer options. If this dict is present, then tims uploaded is attempted. If not, only the xml reports are generated. The keys of this dictionary are the arguments used for ats.tims.utils.call_importer method. They are: - filename (str): the prefix for the file name to be generated. (It will be appended with .results). If not provided, the default is ‘tims’, so generated file name is tims.results - dns (str): dns of the tims database (unique string) - Usually in form ‘tims/<id>’ e.g. ‘tims/Tvm1p’. If not provided, the default is taken from testsuite.tims.dnsname - tims_user (str): user submitting this job (optional). If not provided, the default is taken from testsuite.initinfo.submitter - config_id (str): TIMS global attribute config_id, maps to Configuration ID, Related Config or logical identifier. - ios_commands_file (str): path and file of ios commands (optional) - folder (str): folder name in the tims database (optional) - kwargs (str): other keyword arguments. All arguments in this dict will be converted to this format: -key <value> and fed as args to the importer - post if we should post the data or just create the file

Example

>>> # Make sure all execution is over,
>>> # and all contexts are closed/stopped
>>> # If calling from aerunner
>>> aerunner.generate_tims_report({tims={'filename': 'mytims',
>>>                           'dns': 'tims/Tvm1p',
>>>                           'user': 'abarghou'}})
>>> # If calling from aeclient
>>> clt.generate_tims_report(tims={'filename': 'mytims',
>>>                           'dns': 'tims/Tvm1p',
>>>                           'user': 'abarghou'})

Returns: upload_status – If tims upload is required, it returns True of False based on whether the upload was successful or not; Otherwise, None is returned
Return type: bool or None

generate_tims_results()¶

generate_xml_reports(kwargs)¶

Gets the xml strings for ResultsDetails report and ResultsSummary report, and dumps them into xml files.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>> # Make sure all execution is over,
>>> # and all contexts are closed/stopped
>>> # If calling from aerunner
>>> aerunner.generate_xml_reports({tims={'filename': 'mytims',
>>>                           'dns': 'tims/Tvm1p',
>>>                           'user': 'abarghou'}})
>>> # If calling from aeclient
>>> clt.generate_xml_reports(tims={'filename': 'mytims',
>>>                           'dns': 'tims/Tvm1p',
>>>                           'user': 'abarghou'})

Returns
Return type: None

generate_xunit(kwargs=None)¶

Generate xunit xml and report. NEW: generates for testscript, and container commonSetup/Cleanup only. Will generate only if self.xunit is set to True. All sorting is no longer required since they’re being displayed in order of execution.

Here is the format followed : Format : http://help.catchsoftware.com/display/ET/JUnit+Format

Parameters: None –
Returns
Return type: xml for xunit

get_rerun_info(kwargs)¶

get_results(kwargs)¶

Return a dictionary containing the results of all testcases and subtests in each testscript. A typical results dict looks like:

{Task-id1 :
        {'sample_abstract_testcase' : 'passed',
        'sample_testcase_with_subtests.subtest_one' : 'passed',
        sample_testcase_with_subtests.subtest_two : 'failed',
        ........},
 Task-id2 :
         {
         .......},
}

Returns: results – A dict the contains results of testcases and subtests for each testscript
Return type: dict

get_stack_size(kwargs)¶

get_subtc_result(kwargs)¶

Call this api to get the result of a specific subtest identified by its id (subtcid). If found, return its result; else, raise an exception

Parameters: subtcid (str) – The ID of the testcase whose result is requested.
Returns: The result of the testcase
Return type: str
Raises: SubTestNotFound – Raised if the subtest with the given ID could not be found within the container testscript

get_summary(kwargs)¶: Return dict of cur_ctx.summary

get_summary_detail(kwargs)¶: Return dict of cur_ctx.summary

get_summary_test(kwargs)¶: Return dict of test including important information

get_tc_result(kwargs)¶

Call this api to get the result of a specific testcase identified by its id (tcid). If found, return its result; else, raise an exception

Parameters: tcid (str) – The ID of the testcase whose result is requested.
Returns: The result of the testcase
Return type: str
Raises: TestcaseNotFound – Raised if the testcase with the given ID could not be found within the container testscript

get_testsuite_info(kwargs)¶: Call this api to query general information about the testsuite being executed.

get_tims_resultrecord(test)¶

property host¶

log_file_contains(kwargs)¶

Verify if log file contains a certain message

Returns: ret – Bool
Return type: str

pause(kwargs)¶

Make sure the current context is Runinfo, TestSection, TestScript,BaseTestResult. If yes, add pause

Parameters

condition (str) – Name of the condition
pausefile (str) – Pause file
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context contains runinfo
>>>  aerunner.pause(pausefile='/path/to/pause/file2',
>>>                 condition='acondition2')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

property pid¶

property port¶

print_client_tree(kwargs)¶: Print the client tree

register_client(clienthost, pid, parenthost, parentpid)¶

This is the first API that should be called by a client. It adds the client to the _clients tree.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
parenthost (str) – Name of the host machine the client parent process is running on
parentpid (str) – Process ID of the client’s parent process

Returns

clt – The created node (if created successfully)

Return type

ClientNode

Raises

UnknownParentClientError – Raised if the parent of this client is not found in the tree

run_server()¶: Starts a simple XMLRPC server on the localhost and registers the methods in AERunner class. It uses the current assigned port, or gets a new port if not assigned.

set_ancestor_initinfo(kwargs)¶

Sets various elements in initinfo section of ancestor contexts. Same as set_initinfo but only difference is, parent context is used instead of current context. If generations parameter is provided then instead of parent context, the ancestor context on the provided level will be used.

Parameters

level (Level of parent objects.) –
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  aerunner.set_parent_initinfo(generations = 1,
                                  script='aScript',
>>>                               pargs='pargs')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_ats(kwargs)¶

Make sure the context is Testsuite Sets ats information for the testsuite.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.set_ats(path= '/aPath/',
>>>                   version= '5.3.0',
>>>                   package={'name':'aPackage',
>>>                        'version':'1.0'})

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_attribute(kwargs)¶

This API is used to set various elements/attributes: that are not handled by set_initinfo, set_runinfo, and set_result of the current context

Parameters

mailAttachments (list) – Only in TestSuite context
archivefile (str) – Only in TestSuite context
xref (dict) – Only in TestSection and CommonSubSection contexts
id (dict) – Only in CommonSubSection context
description (str) – Only in CommonSubSection context
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  aerunner.set_attribute(mailattachments=['/aMail/Attachment/','/More/Mail'],
>>>                         archivefile='anArchiveFile')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_initinfo(kwargs)¶

Sets various elements in initinfo section

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context contains initinfo
>>>  aerunner.set_initinfo(script='aScript',
>>>                        pargs='pargs')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_max(kwargs)¶

Set max value for jobs and errors

Example

>>>  aerunner.set_max(errors=5, jobs=4)

Returns: None
Return type: None

set_mode(kwargs)¶

Set the strictness mode for AERunner. Strict : Will terminate as soon as an error happens Lenient : Will try its best to continue even if error

Example

>>>  aerunner = AERunner()
>>>  # Start testsuite from no context.
>>>  aerunner.set_mode(**{'mode': 'strict'})

Parameters: mode (str) – The valid values for mode are: ‘strict’ and ‘lenient’
Returns
Return type: None

set_result(kwargs)¶

If the current context has a result element, set it

It also automatically sets the result into summary is needed for the context.

Parameters

mode (str) – mode can be either auto or override
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
value (str) – values limited to pass, passx, fail, abort, skip, block, never_ran

Example

>>>  # Make sure current context contains result variable
>>>  aerunner.set_result(result={'mode':'override','value':'passed'})

Returns: None
Return type: None

set_runinfo(kwargs)¶

Sets various elements in a runinfo section

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context contains runinfo
>>>  aerunner.set_runinfo(comment='This runinfo must be in testsuite',
>>>                       pause={'pausefile':'/path/to/pause/file',
>>>                              'condition':'acondition'},
>>>                       diag='Testsuite comment',
>>>                       )

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_sectiontype(kwargs)¶: Let aereport knows that this testscript is of unittest type

set_summary(kwargs)¶

Make sure the current context is TestSuite or TestScript. If yes, set the number of passed, failed, aborted, blocked, skipped, errored, and unknown testcases.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
aborted (str or int) – Result is abort
passed (str) – Result is pass
failed (str or int) – Result is fail
blocked (str or int) – Result is block
skipped (str or int) – Result is skip
errored (str or int) – Result is error
unknown (str or int) – Result is unknown
never_ran (str or int) – test never executed

Example

>>>  # Make sure current context is testsuite or testscript
>>>  aerunner.set_summary(**summary_results)

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_tims(kwargs)¶

Make sure the current context is TestSuite . If yes, set the tims information

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.set_tims(dnsname='aDnsName',
>>>                    post={'status':'aStatus',
>>>                          'cmd':'aCmd'},
>>>                    bgPost=False,
>>>                    attributes=[{'name':'aName',
>>>                                 'value':'aSuperValue'},
>>>                                 {'name':'secondName',
>>>                                 'value':'superValue2'}],
>>>                    )

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

set_timsextra(kwargs)¶

Make sure that the current context is Testcase or Subtest. If yes, set tims custom attributes. It receives kwargs as free key/value pairs for these tims attributes which are converted to uppercase.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Returns

Return type

None

Raises

InvalidOperationError –

Example

>>> # Make sure current context is testcase or subtest
>>> aerunner.set_timsextra(input_a='a', input_b='b')

start_aehandler(kwargs)¶

Starts an aehandler section in basetestresult (testcase/subtest), or testsection.

Parameters

name (str) – handler proc name
condition (str) – Regexp condition for which the handler should be invoked such as fail, error, etc

Example

>>>  # Make sure current context is basetestresult
>>>  # or testsection
>>>  aerunner.start_aehandler('subtestaehandler', 'no condition')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_clean(kwargs)¶

Start clean. Only 1 clean is permitted by testsuite

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.start_clean()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_commoncleanup(kwargs)¶

Make sure the current context is a testscript (TestScript). If yes, add a section to the list commoncleanup And push this section to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Mandatory - Path to the log file for the testcase
name (str) – Name of the section

Example

>>>  # Make sure current context is testscript
>>>  aerunner.start_commoncleanup(logfilepath='/tmp/logfile.log',
>>>                             xref={'file':'/init/info/file',
>>>                                      'line':'30'})

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_commonmodify(kwargs)¶

Make sure the current context is a testscript (TestScript). If yes, add a section to the list commonverify And push this section to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Mandatory - Path to the log file for the testcase
name (str) – Name of the section

Example

>>>  # Make sure current context is testscript
>>>  aerunner.start_commonModify(logfilepath='/tmp/logfile.log',
>>>                             xref={'file':'/init/info/file',
>>>                                      'line':'30'})

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_commonsetup(kwargs)¶

Make sure the current context is a testscript (TestScript). If yes, add a section to the list commonsetup And push this section to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Mandatory - Path to the log file for the testcase
name (str) – Name of the section

Example

>>>  # Make sure current context is testscript
>>>  aerunner.start_commonsetup(logfilepath='/tmp/logfile.log',
>>>                             xref={'file':'/init/info/file',
>>>                                      'line':'30'})

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_commonsubsection(kwargs)¶

Make sure the current context is TestSection. Also make sure that the current context tag is commonsetup, commonverify, or commoncleanup. If conditions met, add a commonsubsection to the list of commonsubsections in that TestSection, and push this commonsubsection to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Optional - Path to the log file
variance (str) – Optional - Variance id is the same as TIMS config id. There cannot be a variance id at testcase level if it contains subtests. In such case the variance id will be part of subtest.
name (str) – Name of the commonsubsection
xref (dict) – Optional
id (dict) – Optional

Example

>>>  # Make sure current context is commonSetup, commonModify
>>>  # commonVerify or commonCleanup/
>>>  clt.start_commonsubsection(name='comsubsec1')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_commonverify(kwargs)¶

Make sure the current context is a testscript (TestScript). If yes, add a section to the list commonverify And push this section to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Mandatory - Path to the log file for the testcase
name (str) – Name of the section

Example

>>>  # Make sure current context is testscript
>>>  aerunner.start_commonverify(logfilepath='/tmp/logfile.log',
>>>                             xref={'file':'/init/info/file',
>>>                                      'line':'30'})

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_jobexecution(kwargs)¶

Make sure the current context is TestSuite. If yes, start a JobExecution context, and add it to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>   # Be inside testsuite context
>>>   aerunner.start_jobexecution()

Returns
Return type: None

start_postrunhandler(kwargs)¶

Starts a postrunhandler section in testsuite

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.start_postrunhandler('firstpostrunhandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_posttestcasehandler(kwargs)¶

Starts a posttestcasehandler section in testresult(testcase)

Parameters

name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testresult
>>>  aerunner.start_posttestcasehandler('aposttestcasehandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_posttesthandler(kwargs)¶

Starts a posttesthandler section in testscript

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testsection
>>>  aerunner.start_posttesthandler('aposttesthandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_prerunhandler(kwargs)¶

Starts a prerunhandler section in testsuite

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.start_prerunhandler('firstprerunhandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_pretestcasehandler(kwargs)¶

Starts a pretestcasehandler section in testresult(testcase)

Parameters

name (str) – Name of the handler section
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testresult
>>>  aerunner.start_pretestcasehandler('apretestcasehandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_pretesthandler(kwargs)¶

Starts a pretesthandler section in testscript

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testscript
>>>  aerunner.start_pretesthandler('apretesthandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_reporthandler(kwargs)¶

Starts a postrunhandler section in testsuite

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testsection
>>>  aerunner.start_reporthandler('thereporthandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_server()¶

Start the xml rpc server. It verifies if a logsdir was given/exists Get a free port, then start a new process for the server itself. The new server process is expected to write a file giving the “ready” signal, so this method keeps polling for this file (20 attempts with 0.2 sec delay between each). Once the server is ready, it returns its info (pid, hostname, port). If the server could be started, it returns 0, 0, 0

Parameters

logsdir (str) – The path to the directory where the files should be located
logfilename (str) – The filename of the log of AEReport; Default is AEReport.log

Example

>>>  AERunner(logsdir='/bla/bla',
              logfilename='test').start_server()

Returns

pid (str) – The process ID of the server process. If server could not be started, pid = ‘0’
port (str) – The server port. If server could not be started, port = ‘0’
hostname (str) – The hostname of the machine the server runs on. If server could not be started, hostname = ‘0’

Raises

ServerNotStarted – Raised if the server could not be started.

start_setuphandler(kwargs)¶

Starts a setuphandler section in testsuite

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
name (str) – Name of the handler section
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.start_setuphandler('firstsetuphandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_subtest(kwargs)¶

Make sure the current context is a testcase (TestResult). If yes, add a subtest to the list of subtests in that testcase, and push this subtest to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
subtcid (str) – The id of the subtest to be created. This is set once and never overwritten
logfilepath (str) – Mandatory - Path to the log file for the testcase
variance (str) – Optional - Variance id is the same as TIMS config id. There cannot be a variance id at testcase level if it contains subtests. In such case the variance id will be part of subtest.
name (str) – Name of the testcase/subtest which is equivalent of the Title attribute in TIMS
xref (dict) –
id (dict) –

Example

>>>  # Be inside testcase
>>>  aerunner.start_subtest(subtcid='some_subtest_id',
>>>                         logfilepath='/tmp/logfile.log',
>>>                         variance='MyVariance',
>>>                         id={'name':'aName',
>>>                             'md5':'123123'},

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_testcase(kwargs)¶

Make sure the current context is TestScript. If yes, add a testcase (TestResult) to the list of testcases in that TestScript, and push this testcase to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
tcid (str) – Mandatory - The id of the testcase to be created. This is set once and never overwritten
logfilepath (str) – Mandatory - Path to the log file for the testcase
variance (str) – Optional - Variance id is the same as TIMS config id. There cannot be a variance id at testcase level if it contains subtests. In such case the variance id will be part of subtest.
name (str) – Name of the testcase/subtest which is equivalent of the Title attribute in TIMS
xref (dict) –
id (dict) –

Example

>>>  # Be inside testscript context
>>>  aerunner.start_testcase (tcid='some_tc_id',
>>>                           logfilepath='/tmp/logfile.log',
>>>                           comment='starting our testcase')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_testresulthandler(kwargs)¶

Starts a testresulthandler section in basetestresult (testcase/subtest)

Parameters

name (str) – Name of the handler section
clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
logfilepath (str) – Optional - path to the log file.

Example

>>>  # Make sure current context is basetestresult
>>>  aerunner.start_testresulthandler('atestresulthandler')

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

start_testscript(kwargs)¶

Make sure the current context is JobExecution. If yes, add a TestScript to the list of Job TestScripts, and add the newly created one to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Returns

Return type

None

Example

>>>  # Be inside jobexecution context
>>>  aerunner.start_testscript("/tmp/logfile.log",pid)

start_testsection(kwargs)¶

Make sure the current context is a testcase (TestResult), subtest (SubTestResult) or testscript (TestScript). If yes, add a section to the list of sections for testcase/subtest, and commonsetup/commonverify/commoncleanup in case of testscript. And push this subtest to the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
sectionid (str) – The id of the sectio to be created. This is set once and never overwritten
logfilepath (str) – Mandatory - Path to the log file for the testcase
name (str) – Name of the section

Example

>>>  # Be inside : testscript, testcase or subtest
>>>  aerunner.start_testsection(sectionid='aTestcaseSection',
>>>                             logfilepath='/tmp/logfile.log',
>>>                             xref={'file':'/init/info/file',
>>>                                      'line':'30'})

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases.
Return type: Exception or None

start_teststep(kwargs)¶

start_testsuite(kwargs)¶

Make sure there is no current context (since TestSuite is the top level). If yes, start a TestSuite context, and add it to the context stack.

Parameters

name (str) – Name of the testsuite executed
submitter (str) – Username of test submitter
user (str) – userid of the current process/person launching pyats run job
archivefile (str) – Pointer to the archive log file (if one was requested) for the job run. It should be relative to root of ATS tree.
pid (str) – Process ID of client
clienthost (str) – Hostname of client

Example

>>>  aerunner = AERunner()
>>>  # Start testsuite from no context.
>>>  aerunner.start_testsuite(name='job1',
>>>          submitter='aUser', archivefile='somedir/somefile.log')

stop_aehandler(kwargs)¶

Stops an aehandler section in a basetestresult (testcase/subtest) or a testsection. Make sure that the current context is an AEHandler. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is AEHandler
>>>  aerunner.start_aehandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_clean(kwargs)¶

Stop clean for testsuite.

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.stop_clean()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_client(clienthost, pid)¶

This method is used only in strict mode. It is called when an invalid request is received, and hence AERunner - being in strict mode - will stop the client that made that request, with all its descendants. It stops the client with the passed pid. It stops all its child processes as well. It grabs each child process, pops (and stops) each item in its stack, and then marks it as terminated in the Context Stack. It then does the same thing for the main client itself.

Parameters

pid (str) – Process ID of the client that needs to be terminated
clienthost (str) – clienthost machine where the client is running on

stop_commoncleanup(kwargs)¶

Wrapper for stop_testsection

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsection
>>>  aerunner.stop_commoncleanup()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_commonmodify(kwargs)¶

Wrapper for stop_testsection

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsection
>>>  aerunner.stop_commonmodify()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_commonsetup(kwargs)¶

Wrapper for stop_testsection

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsection
>>>  aerunner.stop_commonsetup()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_commonsubsection(kwargs)¶

Make sure the current context is a commonsubsection. If yes, stop it, and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is commonSubsection
>>>  aerunner.stop_commonsubsection()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_commonverify(kwargs)¶

Wrapper for stop_testsection

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsection
>>>  aerunner.stop_commonverify()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_jobexecution(kwargs)¶

Make sure the current context is JobExecution. If yes, stop it, and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Be inside job execution context
>>>  aerunner.stop_jobexecution

Returns
Return type: None

stop_open_contexts(kwargs)¶

In case of unexpected failures all of the child client contexts needs to be closed if there is any of them left open.

This function starts from the root level client, find its current context and brings all of child clients’ contexts to the same level by closing everything else.

stop_postrunhandler(kwargs)¶

Stops a postrunhandler section in a testsuite. Make sure that the current context is an InfraHandlerSection with tag = ‘postrunHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.stop_postrunhandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_posttestcasehandler(kwargs)¶

Stops a posttestcasehandler section in a testresult(testcase). Make sure that the current context is an InfraHandlerSection with tag = ‘posttestcaseHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is posttestcasehandler
>>>  aerunner.start_posttestcasehandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_posttesthandler(kwargs)¶

Stops a posttesthandler section in a testscript. Make sure that the current context is an InfraHandlerSection with tag = ‘posttestHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is infrahandlersection
>>>  aerunner.stop_posttesthandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_prerunhandler(kwargs)¶

Stops a prerunhandler section in a testsuite. Make sure that the current context is an InfraHandlerSection with tag = ‘prerunHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.stop_prerunhandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_pretestcasehandler(kwargs)¶

Stops a pretestcasehandler section in a testresult(testcase). Make sure that the current context is an InfraHandlerSection with tag = ‘pretestcaseHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testresult
>>>  aerunner.stop_pretestcasehandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_pretesthandler(kwargs)¶

Stops a pretesthandler section in a testscript. Make sure that the current context is an InfraHandlerSection with tag = ‘pretestHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is infrahandlersection
>>>  aerunner.stop_pretesthandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_reporthandler(kwargs)¶

Stops a postrunhandler section in a testsuite. Make sure that the current context is an InfraHandlerSection with tag = ‘postrunHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context contains reporthandler
>>>  aerunner.stop_reporthandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_setuphandler(kwargs)¶

Stops a setuphandler section in a testsuite. Make sure that the current context is an InfraHandlerSection with tag = ‘setupHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsuite
>>>  aerunner.stop_setuphandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_subtest(kwargs)¶

Make sure the current context is a subtest (SubTestResult). If yes, stop it, and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Be inside subtest context
>>>  aerunner.stop_subtest()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_testcase(kwargs)¶

Make sure the current context is a testcase (TestResult). If yes, stop it, and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Be inside testcase context
>>>  aerunner.stop_testcase()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_testresulthandler(kwargs)¶

Stops a testresulthandler section in a basetestresult (testcase/subtest). Make sure that the current context is an InfraHandlerSection with tag = ‘testresultHandler’. Stop the section and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is infrahandlersection
>>>  aerunner.stop_testresulthandler()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_testscript(kwargs)¶

Make sure the current context is TestScript. If yes, stop it, and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  aerunner.stop_testscript(kwargs['pid'])

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_testsection(kwargs)¶

Make sure the current context is a section (TestSection). If yes, stop it, and pop it from the context stack.

Parameters

clienthost (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Example

>>>  # Make sure current context is testsection
>>>  aerunner.stop_testsection()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

stop_teststep(kwargs)¶

stop_testsuite(kwargs)¶

Make sure the current context is TestSuite. If yes, stop it, and pop it from the context stack.

Parameters

pid (str) – Process ID of client
clienthost (str) – Hostname of client

Example

>>>  # Be inside testsuite context
>>>  aerunner.stop_testsuite()

terminate_server()¶

Try to send a request to the server to terminate itself. If this fails, just send a kill signal

Parameters: pid (str) – Process ID for the client child
Returns: Return 0 in all cases
Return type: int

test_connection()¶

If this function can be called, the connection with the server is working.

Returns: True

unpause(kwargs)¶

Make sure the current context is Runinfo, TestSection, TestScript,BaseTestResult. If yes, add pause

Parameters

condition (str) – Name of the condition
pausefile (str) – Pause file
pid (str) – pid of the process

Example

# Make sure current context contains runinfo

aerunner.unpause()

Returns: If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases
Return type: Exception or None

class pyats.aereport.aerunner.ClientNode(host, pid, parent=None)¶

Bases: object

Each client process is maintained in a ClientNode (in a tree structure). Each clientnode maintains its own ID (host + pid), a pointer to its parent node, and a list of children. In addition, it contains the client context stack, and a status indicator (terminated).

host¶

Name of the host machine the client is running on

Type: str

pid¶

Process ID of the client

Type: str

parent¶

Reference to the parent node

Type: ClientNode

ctx_stack¶

A container for the contexts executed by the client

Type: list

add_child(child)¶

Add a child to the current node.

Parameters: child (ClientNode) – The ClientNode to be added as a child of the caller
Returns
Return type: None
Raises: TypeError – Raised when the child is not of type ClientNode

add_ctx(ctx)¶

Add a context to this client’s ctx_stack. The operation is only executed if the client is not terminated (virtually).

Parameters: ctx (AEReportElement) –

cur_ctx()¶

Return the top item in the context stack. If the stack is empty, get the top item from the parent node, and so on. Keep bubbling up until reaching a context or None.

Returns: ctx
Return type: AEReportElement or None

pop_ctx()¶

Remove the top item in the stack and return it. If the stack is empty, return None

Returns: ctx
Return type: AEReportElement or None

set_parent(node)¶

Set the parent client node.

Parameters: node (ClientNode) – The ClientNode to be used as the parent for the caller
Raises: TypeError – Raised when the child is not of type ClientNode

terminate(_terminate_children=True)¶

This is a generator method. It calls itself recursively on each child (by default) of the current ClientNode (self) and processes it. Processing is done by emptying its context stack (pop all items) and yielding the client node and the popped context each time. Finally, it sets terminated flag to True. It repeats this (recursively) for every node (under the current one).

Parameters

_terminate_children (bool) – Default = True. A flag to indicate whether child nodes need to be terminated or not

Yields

clt (ClientNode) – The client node that contained the popped context in its stack
ctx (AEReportElement) – The popped context (testsuite, testscript, etc)

class pyats.aereport.aerunner.ClientsTree(verbose=False)¶

Bases: object

This is a tree structure to preserve all connecting clients and their parent/child relationships. Each client is a node (ClientNode) in the tree.

root¶

The root node in the tree

Type: ClientNode

size¶

The number of nodes in the clients tree

Type: int

num_contexts¶

The total number of context items in the whole tree

Type: int

verbose¶

Verbosity of output

Type: bool

add_client(host, pid, parenthost, parentpid)¶

Adds a ClientNode to the tree.

Parameters

host (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
parenthost (str) – Name of the host machine the client parent process is running on
parentpid (str) – Process ID of the client’s parent process

Returns

clt – The created node (if created successfully)

Return type

ClientNode

Raises

UnknownParentClientError – Raised if the parent of this client is not found in the tree

find_client(host, pid)¶

Finds and returns a node in the tree given its host and pid. It traverses the tree starting from the root element. If client is not found, returns None.

Parameters

host (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

get_client_ctx(host, pid)¶

Get the top item in the stack of the given client. Condition: The client should not be terminated.

Parameters

host (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client

Returns

ctx – The current context of the given client which could be an AEReportElement or None

Return type

AEReportElement or None

Raises

UnknownClientError – Raised if the client could not be found in the tree or is terminated

get_num_ctxs()¶

Get the total number of contexts in the tree.

Returns: num_ctxs – Total number of contexts in the tree
Return type: int

is_empty()¶

Tells whether the tree is empty or not.

Returns: True if the tree is empty; False otherwise
Return type: bool

pop_client_ctx(host, pid)¶

Pops one item from the stack of the client (host, pid). If the stack is empty, it returns None. If the client is not found (or is terminated), it raises an UnknownClientError exception

Parameters

host (str) – Name of the host machine the client connected from
pid (str) – Process ID of the client

Returns

ctx

Return type

AEReportElement or None

Raises

UnknownClientError – Raised when the client is not registered with the server

push_client_ctx(host, pid, ctx)¶

Adds an item/context to the top item in the stack of the given client. Condition: The client should not be terminated

Parameters

host (str) – Name of the host machine the client is running on
pid (str) – Process ID of the client
ctx (AEReportElement) – The context to be added

Raises

UnknownClientError – Raised if the client could not be found in the tree or is terminated

terminate_client(host, pid)¶

Finds the client, then calls its terminate method (with recursive option). This means that the context stack of this client and all its children are going to be popped until empty

Parameters

host (str) – Name of the host machine the client connected from
pid (str) – Process ID of the client

Returns

ctx

Return type

AEReportElement or None

Raises

UnknownClientError – Raised when the client is not registered with the server

class pyats.aereport.aerunner.OrphanFreeSimpleXMLRPCServer(*args, **kwargs)¶

Bases: xmlrpc.server.SimpleXMLRPCServer

This is a customized SimpleXMLRPCServer class to check for parent process which self exits RPC server if parent process is terminated already.

__last_orphan_check_time¶

The time of the previous orphan check

Type: time

__log¶

Logger object

Type: logger

Constructor. May be extended, do not override.

service_actions()¶

Technically, you want the server to exit the same time when the parent’s process has terminated. If the parent process terminates unexpectedly, AEReport server becomes a lingering process and re-parented to the ini(1) process. https://en.wikipedia.org/wiki/Orphan_process

checks whether parent process has been re-parented to init every 10 seconds. when orphan process is detected, log it and sys.exit(0)

class pyats.aereport.aerunner.RequestHandler(request, client_address, server)¶

Bases: xmlrpc.server.SimpleXMLRPCRequestHandler

This class is to keep track of the rpc_path

rpc_paths = ('/RPC2',)¶

pyats.aereport.aerunner.pad_number(number)¶: Pads number with N zeroes so that lexicographical sort works properly Accepts numbers, returns a string

`clean` – Clean¶

This module implement Clean section used by TestSuite.

class pyats.aereport.clean.Clean(tag='clean')¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Clean routine prior to job execution

Class based on the following schema definition
<xs:complexType name="cleanType">
        <xs:sequence>
                <xs:element name="starttime" type="xs:dateTime"/>
                <xs:element name="initinfo">...</xs:element>
                <xs:element name="runinfo" type="runinfoType"/>
                <xs:element ref="result"/>
                <xs:element name="stoptime" type="xs:dateTime"/>
                <xs:element name="runtime">...</xs:element>
        </xs:sequence>
</xs:complexType>

tag¶

Default value = ‘clean’. This is to ensure that all elements contain a tag attribute.

Type: str

starttime¶

Start time of clean

Type: datetime

stoptime¶

Stop time of clean

Type: datetime

runtime¶

stop time - start time

Type: str

initinfo¶

Type: CleanInit

result¶

result of the clean

Type: Result

runinfo¶

Information

Type: RunInfo

class pyats.aereport.clean.CleanInit(**kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Information for clean

Class based on the following schema definition
<xs:element name="initinfo">
        <xs:complexType>
                <xs:sequence>
                        <xs:element name="script" type="scriptType"/>
                        <xs:element name="pargs"/>
                </xs:sequence>
        </xs:complexType>
</xs:element>

tag¶

Default value = ‘initinfo’. This is to ensure that all elements contain a tag attribute.

Type: str

script¶

Script Class containing script information

Type: Script

pargs¶

Type: str

set_args(**kwargs)¶

Set clean initinfo attributes

Parameters

script (str) – clean script
pargs (str) – Args

Returns

Return type

None

`client` – Client¶

This module implements AEclient. It contains the direct APi the client can use to connect and to communicate to the xml-rpc server.

class pyats.aereport.client.AEClient(wrapped=None, port=None, servername=None, ppid=None, phost=None)¶

Bases: object

This is a wrapper for xmlrpc proxy. For python test code that needs to produce AEReport xmls, it should import and use AEClient as the tool for making RPCs to the server. AEClient embeds an xmlrpc proxy, maintains the client identifiers (hostname and pid), and provides them to server with every API invocation. Although python xmlrpc does not support keyword arguments, this class overrides the default __getattr__ and __call__ methods to support keywords arguments, and also to automatically add client identifier to every call.

_serverport¶

The port that should be used to connect to the server

Type: str

_servername¶

The hostname of the machine where the server runs

Type: str

xmlrpc¶

The proxy for making remote procedure calls

Type: xmlrpclib.ServerProxy

_pid¶

The process ID of this client. This is automatically populated by the init method

Type: str

_hostname¶

The hostname of the machine where this client runs. This is automatically populated by the init method

Type: str

_ppid¶

The process ID of the parent of this process. It could, however, be a process on a different physical machine. That’s why this value should be explicitly provided. If not provided, AEClient assumes that it is on the same physical machine, and tries to get it automatically

Type: str

_phostname¶

The hostname of the machine where the parent of the client runs. It could be a different physical machine. That’s why this value should be explicitly provided. If not provided, AEClient assumes that it is on the same physical machine, and tries to get it automatically

Type: str

Example

>>> # Start the server process (if not already done)
>>> svrpid, svrport, servername = AERunner.start_server(logsdir='/tmp/ttt/',
>>>                                         logfilename='logfile.log')
>>> # Create an AEClient instance
>>> clt = AEClient(port=svrport,servername=servername)
>>> # Connect to the server
>>> clt.connect()
>>> # Make RPCs
>>> clt.start_testsuite(**{'name':'job1',
>>>                        'submitter':'anUser'})
>>> clt.add_ats_packages(packages=[('Csccon', '1.1'), ('aetest', '1.2')])
>>> clt.stop_testsuite()
>>> # Generate your xml reports
>>> clt.generate_xml_reports(path='/tmp/')
>>> # Terminate the server
>>> AERunner.terminate_server()

connect()¶

Attempt to connect to the server using information received from __init__. It keeps trying to connect 50 times with a 0.5 sec delay in between. If connection succeeds, it registers the client (and its parent) info with the server, and then instantiate the xmlrpc member of this class. If not, it raises a NoConnectionError exception.

Example

>>>  client.connect()

Returns: If no issues with connecting
Return type: None
Raises: NoConnectionError – Raised if the method fails to connect to the server

classmethod create_from_cli()¶: Parse AEClient attributes from cli (using argparse lib), and return an instance of AEClient. If if the parent client hostname and pid are not provided, it assumes them to be on the same machine as the client, and gets them automatically.

disable_forked()¶

Disable forking behavior of this class instance. All forked child process will no longer be connected to server.

Multiple calls to this api does not generate exceptions.

enable_forked()¶

Enable forking behavior of this class instance. All forked child process will automatically reconnect to the parent server

Multiple calls to this api does not generate exceptions.

static forked(instance)¶: api to be called as soon as the process containing this instance object is forked. This api forces the instance to reconnect to the previous server and re-register the new pid so that it continues functioning

`easypy_sim` – A simulator of easypy client¶

This module implements a simulator of a client for AEReport. The simulated client is easypy.

`handlers` – Handlers¶

This module implements the two types of handlers used in AEReport: aehandler and infrahandlersection.

class pyats.aereport.handlers.AEHandler(tag=None)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on the following schema definition

<xs:annotation>
    <xs:documentation>aetest testcase or section handlers</xs:documentation>
</xs:annotation>
<xs:complexType>
    <xs:sequence>
        <xs:element name="starttime"/>
        <xs:element name="name">
            <xs:annotation>
                <xs:documentation>handler proc name</xs:documentation>
            </xs:annotation>
        </xs:element>
        <xs:element name="condition">
            <xs:annotation>
                <xs:documentation>Regexp condition for which the handler should be invoked such as fail, error, etc</xs:documentation>
            </xs:annotation>
        <xs:element name="runinfo" type="runinfoType"/>
        </xs:element>
        <xs:element name="stoptime"/>
        <xs:element name="runtime">
            <xs:annotation>
                <xs:documentation>The time elapsed between the stoptime and the starttime</xs:documentation>
            </xs:annotation>
        </xs:element>
    </xs:sequence>
</xs:complexType>

tag¶

Default value = ‘aehandler’

Type: str

starttime¶

Start time

Type: datetime

name¶

handler proc name

Type: str

condition¶

Regexp condition for which the handler should be invoked such as fail, error, etc

Type: str

runinfo¶

Optional - Available only for TestSection context

Type: RunInfo

stoptime¶

Stop time

Type: datetime

runtime¶

Runtime , stop - start

Type: timedelta

set_args(**kwargs)¶

Set name and condition of aehandler.

Parameters

name (str) – Optional - handler proc name
condition (str) – Optional - Regexp condition for which the handler should be invoked such as fail, error, etc

class pyats.aereport.handlers.InfraHandlerInitInfo(tag=None)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on the following schema definition
<xs:element name="initinfo">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="logfile" type="LogFileType">...</xs:element>
        </xs:sequence>
    </xs:complexType>
</xs:element>

tag¶

Default value = ‘initinfo’

Type: str

logfile¶

Logfile

Type: LogFile

class pyats.aereport.handlers.InfraHandlerSection(tag=None, name=None)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on the following schema definition

<xs:complexType name="InfraHandlerSectionType">
    <xs:annotation>
        <xs:documentation>...</xs:documentation>
    </xs:annotation>
    <xs:sequence>
        <xs:element name="name">...</xs:element>
        <xs:element name="starttime" type="xs:dateTime"/>
        <xs:element name="initinfo">...</xs:element>
        <xs:element name="runinfo" type="runinfoType"/>
        <xs:element name="error" minOccurs="0"/>
        <xs:element name="stoptime" type="xs:dateTime"/>
        <xs:element name="runtime">...</xs:element>
    </xs:sequence>
</xs:complexType>

tag¶

Default value = ‘infrahandler’

Type: str

name¶

Name

Type: str

starttime¶

Start time

Type: datetime

error¶

Optional

Type: str

stoptime¶

Stop time

Type: datetime

runtime¶

runtime

Type: timedelta

runinfo¶

runinfo

Type: RunInfo

initinfo¶

initinfo

Type: InfraHandlerInitInfo

`infra` – Infra Elements¶

This module contains AEReport elements that are the leaves of the xml tree. These elements do not reference any others.

class pyats.aereport.infra.Checkpoint(**kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on this schema definition

<xs:complexType name="CheckpointType">
    <xs:annotation>
        <xs:documentation>XML results for checkpoints in aetest sections</xs:documentation>
    </xs:annotation>
    <xs:sequence>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="result" type="xs:string"/>
    </xs:sequence>
</xs:complexType>

tag¶

Constant value = ‘checkpoint’ to be used as xml tag.

Type: str

name¶

Name

Type: str

result¶

Result

Type: str

set_args(**kwargs)¶

Set image name and directory

Parameters

name (str) – Name
result (str) – Result

class pyats.aereport.infra.ErrorType(**kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on this schema definition

<xs:complexType name="ErrorType">
    <xs:choice>
        <xs:element name="script" type="LogFileType">
            <xs:annotation>
                <xs:documentation>tcl error occuring during execution</xs:documentation>
            </xs:annotation>
        </xs:element>
        <xs:element name="device" type="LogFileType">
            <xs:annotation>
                <xs:documentation>Errors found in device logs parsed using ERROR and IGNORE config variables</xs:documentation>
            </xs:annotation>
        </xs:element>
        <xs:element name="info" type="LogFileType">
            <xs:annotation>
                <xs:documentation>Error messages provided by user in the script via ats_results -error_info</xs:documentation>
            </xs:annotation>
        </xs:element>
    </xs:choice>
</xs:complexType>

tag¶

Constant value = ‘error’ to be used as xml tag.

Type: str

cause¶

Restricted string. Valid values are: script: tcl error occuring during execution device: Errors found in device logs parsed using ERROR and IGNORE config variables info: Error messages provided by user in the script via ats_results -error_info

Type: str

logfile¶

Path to the log file

Type: LogFile

generate_dom(parent)¶

Override the default behavior of AEReportElement.generate_dom

Parameters: parent (AEReportElement) – The xml element that should be used as a parent for this userdef

set_args(**kwargs)¶

Set image name and directory

Parameters

name (str) – Name of the image
directory (str) – Path to the image

class pyats.aereport.infra.Image(**kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on this schema definition

<xs:element name="image">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="name"/>
            <xs:element name="directory"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

tag¶

Constant value = ‘image’.

Type: str

name¶

Name of the image

Type: str

directory¶

Path to the image

Type: str

set_args(**kwargs)¶

Set image name and directory

Parameters

name (str) – Name of the image
directory (str) – Path to the image

class pyats.aereport.infra.LogFile(tag='logfile', **kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on this schema definition

<xs:complexType name="LogFileType">
    <xs:annotation>
        <xs:documentation>Log file name, including the offset (chars) in the
            log file where the corresponding logs begin.</xs:documentation>
    </xs:annotation>
    <xs:simpleContent>
        <xs:extension base="xs:string">
            <xs:attribute name="begin" type="xs:int" use="required">
                <xs:annotation>
                    <xs:documentation>This is the number of bytes offset within the log
                        file where the associated logs begin. The tcl cmd [file size
                        $logfile] will be used to get this value.</xs:documentation>
                </xs:annotation>
            </xs:attribute>
            <xs:attribute name="size" type="xs:int" use="required">
                <xs:annotation>
                    <xs:documentation>This is the number of bytes offset within the log
                        file where the associated logs begin. This value is the difference
                        between the begin and end points for section of file of interest.
                        (For reading files by bytes, the starting byte and the number of
                        bytes to read are typically provided).</xs:documentation>
                </xs:annotation>
            </xs:attribute>
        </xs:extension>
    </xs:simpleContent>
</xs:complexType>

tag¶

Default value = ‘logfile’ to be used as xml tag.

Type: str

attrs¶

Dictionary with the mandatory keys: beginThis is the number of bytes offset within the log: file where the associated logs begin. The tcl cmd [file size $logfile] will be used to get this value.
sizeThis is the number of bytes offset within the log: file where the associated logs begin. This value is the difference between the begin and end points for section of file of interest. (For reading files by bytes, the starting byte and the number of bytes to read are typically provided).

Type: dict

filepath¶

Path to the log file

Type: str

Set filepath, begin and size

Parameters

begin (str) – This is the number of bytes offset within the log file where the associated logs begin. The tcl cmd [file size $logfile] will be used to get this value.
size (This is the number of bytes offset within the log) – file where the associated logs begin. This value is the difference between the begin and end points for section of file of interest. (For reading files by bytes, the starting byte and the number of bytes to read are typically provided).
filepath (str) – Path to the log file

Returns

Return type

None

generate_dom(parent)¶

Override the default behavior of AEReportElement.generate_dom

Parameters: parent (AEReportElement) – The xml element that should be used as a parent for this userdef

get_logging_mode()¶: Return the mode of logging used for this execution

set_args(**kwargs)¶

Set log file attributes

Parameters

begin (str) – This is the number of bytes offset within the log file where the associated logs begin. The tcl cmd [file size $logfile] will be used to get this value.
size (This is the number of bytes offset within the log) – file where the associated logs begin. This value is the difference between the begin and end points for section of file of interest. (For reading files by bytes, the starting byte and the number of bytes to read are typically provided).
filepath (str) – Path to the log file

class pyats.aereport.infra.Pause(**kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on this schema definition
<xs:complexType>
    <xs:sequence>
        <xs:element name="starttime"/>
        <xs:element name="condition"/>
        <xs:element name="pausefile"/>
        <xs:element name="stoptime"/>
        <xs:element name="runtime"/>
    </xs:sequence>
</xs:complexType>

tag¶

Constant value = ‘pause’ to be used as xml tag.

Type: str

starttime¶

starttime

Type: datetime

condition¶

Condition

Type: str

pausefile¶

Pausefile

Type: str

stoptime¶

stoptime

Type: datetime

runtime¶

runtime, stoptime - startime

Type: timedelta

_isstarted¶

started

Type: 0 if pause is not started, and 1 if it is

set_args(**kwargs)¶

Set condition and pausefile

Parameters

condition (str) – Condition
pausefile (str) – pausefile

class pyats.aereport.infra.XRef(tag='xref', **kwargs)¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

Class based on this schema definition

<xs:complexType name="xrefType">
    <xs:sequence>
        <xs:element name="file" />
        <xs:element name="line" />
    </xs:sequence>
</xs:complexType>

tag¶

Default value = ‘xref’ to be used as xml tag.

Type: str

file¶

Type: str

line¶

Type: int

set_args(**kwargs)¶

Set file and line

Parameters

file (str) –
line (str) –

`aereportelement` – AEReportElement Base Class¶

This module contains the base class for all schema elements.

class pyats.aereport.template.SampleClass¶

Bases: pyats.aereport.toplevel.aereportelement.AEReportElement

AEReportElement is the base class for all schema elements. It implements a default functionality for generating xml. It also defines common attributes and default values.

Class based on the following schema definition
<some xml>

Examples

>>> aer = AEReport()
>>> ts1 = TestSuite()

tag¶

Constant value = ‘report’ to be used as xml tag.

Type: str

attrs¶

Default value is None. This is to ensure that all elements contain an attrs dictionary. attrs is expanded as attributes in the xml start tag.

Type: dict

some_method()¶

Get the tag of the calling instance

Parameters

par1 (int) – description
par2 (str) – description

Returns

xml_str – tag of the element. Default = ‘notag’

Return type

str

pyats.aereport package¶

Subpackages¶

Submodules¶

aerunner – Aerunner¶

clean – Clean¶

client – Client¶

easypy_sim – A simulator of easypy client¶

handlers – Handlers¶

infra – Infra Elements¶

aereportelement – AEReportElement Base Class¶

`aerunner` – Aerunner¶

`clean` – Clean¶

`client` – Client¶

`easypy_sim` – A simulator of easypy client¶

`handlers` – Handlers¶

`infra` – Infra Elements¶

`aereportelement` – AEReportElement Base Class¶