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'})
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 –

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’

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

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()
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

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
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

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: 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: 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: 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: 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

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: 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: 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: 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: 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: 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: 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: 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

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: 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: 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: 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