Internal (Core) APIs¶
Internal APIs that may be of interest to Avocado hackers.
Subpackages¶
- avocado.core.restclient package
- Subpackages
- Submodules
- avocado.core.restclient.connection module
- avocado.core.restclient.response module
- Module contents
Submodules¶
avocado.core.app module¶
The core Avocado application.
avocado.core.data_dir module¶
Library used to let avocado tests find important paths in the system.
The general reasoning to find paths is:
- When running in tree, don’t honor avocado.conf. Also, we get to run/display the example tests shipped in tree.
- When avocado.conf is in /etc/avocado, or ~/.config/avocado, then honor the values there as much as possible. If they point to a location where we can’t write to, use the next best location available.
- The next best location is the default system wide one.
- The next best location is the default user specific one.
-
avocado.core.data_dir.
clean_tmp_files
()¶ Try to clean the tmp directory by removing it.
This is a useful function for avocado entry points looking to clean after tests/jobs are done. If OSError is raised, silently ignore the error.
-
avocado.core.data_dir.
create_job_logs_dir
(logdir=None, unique_id=None)¶ Create a log directory for a job, or a stand alone execution of a test.
Parameters: - logdir – Base log directory, if None, use value from configuration.
- unique_id – The unique identification. If None, create one.
Return type: basestring
-
avocado.core.data_dir.
get_base_dir
()¶ Get the most appropriate base dir.
The base dir is the parent location for most of the avocado other important directories.
- Examples:
- Log directory
- Data directory
- Tests directory
-
avocado.core.data_dir.
get_data_dir
()¶ Get the most appropriate data dir location.
The data dir is the location where any data necessary to job and test operations are located.
- Examples:
- ISO files
- GPG files
- VM images
- Reference bitmaps
-
avocado.core.data_dir.
get_datafile_path
(*args)¶ Get a path relative to the data dir.
Parameters: args – Arguments passed to os.path.join. Ex (‘images’, ‘jeos.qcow2’)
-
avocado.core.data_dir.
get_logs_dir
()¶ Get the most appropriate log dir location.
The log dir is where we store job/test logs in general.
-
avocado.core.data_dir.
get_test_dir
()¶ Get the most appropriate test location.
The test location is where we store tests written with the avocado API.
The heuristics used to determine the test dir are: 1) If an explicit test dir is set in the configuration system, it is used. 2) If user is running Avocado out of the source tree, the example test dir is used 3) System wide test dir is used 4) User default test dir (~/avocado/tests) is used
-
avocado.core.data_dir.
get_tmp_dir
(basedir=None)¶ Get the most appropriate tmp dir location.
The tmp dir is where artifacts produced by the test are kept.
- Examples:
- Copies of a test suite source code
- Compiled test suite source code
avocado.core.decorators module¶
-
avocado.core.decorators.
fail_on
(exceptions=None)¶ Fail the test when decorated function produces exception of the specified type.
(For example, our method may raise IndexError on tested software failure. We can either try/catch it or use this decorator instead)
Parameters: exceptions – Tuple or single exception to be assumed as test fail [Exception] Note: self.error and self.skip behavior remains intact Note: To allow simple usage param “exceptions” must not be callable
-
avocado.core.decorators.
skip
(message=None)¶ Decorator to skip a test.
-
avocado.core.decorators.
skipIf
(condition, message=None)¶ Decorator to skip a test if a condition is True.
-
avocado.core.decorators.
skipUnless
(condition, message=None)¶ Decorator to skip a test if a condition is False.
avocado.core.dispatcher module¶
Extensions/plugins dispatchers.
-
class
avocado.core.dispatcher.
CLICmdDispatcher
¶ Bases:
avocado.core.dispatcher.Dispatcher
Calls extensions on configure/run
Automatically adds all the extension with entry points registered under ‘avocado.plugins.cli.cmd’
-
class
avocado.core.dispatcher.
CLIDispatcher
¶ Bases:
avocado.core.dispatcher.Dispatcher
Calls extensions on configure/run
Automatically adds all the extension with entry points registered under ‘avocado.plugins.cli’
-
class
avocado.core.dispatcher.
Dispatcher
(namespace, invoke_kwds={})¶ Bases:
stevedore.enabled.EnabledExtensionManager
Base dispatcher for various extension types
-
NAMESPACE_PREFIX
= 'avocado.plugins.'¶ Default namespace prefix for Avocado extensions
-
enabled
(extension)¶ Checks configuration for explicit mention of plugin in a disable list
If configuration section or key doesn’t exist, it means no plugin is disabled.
-
fully_qualified_name
(extension)¶ Returns the Avocado fully qualified plugin name
Parameters: extension ( stevedore.extension.Extension
) – an Stevedore Extension instance
-
names
()¶ Returns the names of the discovered extensions
This differs from
stevedore.extension.ExtensionManager.names()
in that it returns names in a predictable order, by using standardsorted()
.
-
plugin_type
()¶ Subset of entry points namespace for this dispatcher
Given an entry point avocado.plugins.foo, plugin type is foo. If entry point does not conform to the Avocado standard prefix, it’s returned unchanged.
-
settings_section
()¶ Returns the config section name for the plugin type handled by itself
-
static
store_load_failure
(manager, entrypoint, exception)¶
-
-
class
avocado.core.dispatcher.
JobPrePostDispatcher
¶ Bases:
avocado.core.dispatcher.Dispatcher
Calls extensions before Job execution
Automatically adds all the extension with entry points registered under ‘avocado.plugins.job.prepost’
-
map_method
(method_name, job)¶
-
-
class
avocado.core.dispatcher.
ResultDispatcher
¶ Bases:
avocado.core.dispatcher.Dispatcher
-
map_method
(method_name, result, job)¶
-
-
class
avocado.core.dispatcher.
ResultEventsDispatcher
(args)¶ Bases:
avocado.core.dispatcher.Dispatcher
-
map_method
(method_name, *args)¶
-
-
class
avocado.core.dispatcher.
VarianterDispatcher
¶ Bases:
avocado.core.dispatcher.Dispatcher
-
map_method
(method_name, *args, **kwargs)¶
-
map_method_copy
(method_name, *args)¶ The same as map_method, but use copy.deepcopy on each passed arg
-
avocado.core.exceptions module¶
Exception classes, useful for tests, and other parts of the framework code.
-
exception
avocado.core.exceptions.
JobBaseException
¶ Bases:
exceptions.Exception
The parent of all job exceptions.
You should be never raising this, but just in case, we’ll set its status’ as FAIL.
-
status
= 'FAIL'¶
-
-
exception
avocado.core.exceptions.
JobError
¶ Bases:
avocado.core.exceptions.JobBaseException
A generic error happened during a job execution.
-
status
= 'ERROR'¶
-
-
exception
avocado.core.exceptions.
OptionValidationError
¶ Bases:
exceptions.Exception
An invalid option was passed to the test runner
-
status
= 'ERROR'¶
-
-
exception
avocado.core.exceptions.
TestAbortError
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that the test was prematurely aborted.
-
status
= 'ERROR'¶
-
-
exception
avocado.core.exceptions.
TestBaseException
¶ Bases:
exceptions.Exception
The parent of all test exceptions.
You should be never raising this, but just in case, we’ll set its status’ as FAIL.
-
status
= 'FAIL'¶
-
-
exception
avocado.core.exceptions.
TestCancel
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that a test was canceled.
Should be thrown when the cancel() test method is used.
-
status
= 'CANCEL'¶
-
-
exception
avocado.core.exceptions.
TestError
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that the test was not fully executed and an error happened.
This is the sort of exception you raise if the test was partially executed and could not complete due to a setup, configuration, or another fatal condition.
-
status
= 'ERROR'¶
-
-
exception
avocado.core.exceptions.
TestFail
¶ Bases:
avocado.core.exceptions.TestBaseException
,exceptions.AssertionError
Indicates that the test failed.
TestFail inherits from AssertionError in order to keep compatibility with vanilla python unittests (they only consider failures the ones deriving from AssertionError).
-
status
= 'FAIL'¶
-
-
exception
avocado.core.exceptions.
TestInterruptedError
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that the test was interrupted by the user (Ctrl+C)
-
status
= 'INTERRUPTED'¶
-
-
exception
avocado.core.exceptions.
TestNotFoundError
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that the test was not found in the test directory.
-
status
= 'ERROR'¶
-
-
exception
avocado.core.exceptions.
TestSetupFail
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates an error during a setup or cleanup procedure.
-
status
= 'ERROR'¶
-
-
exception
avocado.core.exceptions.
TestSetupSkip
¶ Bases:
avocado.core.exceptions.TestBaseException
Indictates that the test is skipped in setUp().
Should be thrown when skip() is used in setUp().
-
status
= 'SKIP'¶
-
-
exception
avocado.core.exceptions.
TestSkipError
¶ Bases:
avocado.core.exceptions.TestBaseException
Indictates that the test is skipped.
Should be thrown when various conditions are such that the test is inappropriate. For example, inappropriate architecture, wrong OS version, program being tested does not have the expected capability (older version).
-
status
= 'SKIP'¶
-
-
exception
avocado.core.exceptions.
TestTimeoutInterrupted
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that the test did not finish before the timeout specified.
-
status
= 'INTERRUPTED'¶
-
-
exception
avocado.core.exceptions.
TestWarn
¶ Bases:
avocado.core.exceptions.TestBaseException
Indicates that bad things (may) have happened, but not an explicit failure.
-
status
= 'WARN'¶
-
avocado.core.exit_codes module¶
Avocado exit codes.
These codes are returned on the command line and may be used by applications that interface (that is, run) the Avocado command line application.
Besides main status about the execution of the command line application, these exit status may also give extra, although limited, information about test statuses.
-
avocado.core.exit_codes.
AVOCADO_ALL_OK
= 0¶ Both job and tests PASSed
-
avocado.core.exit_codes.
AVOCADO_FAIL
= 4¶ Something else went wrong and avocado failed (or crashed). Commonly used on command line validation errors.
-
avocado.core.exit_codes.
AVOCADO_GENERIC_CRASH
= -1¶ Avocado generic crash
-
avocado.core.exit_codes.
AVOCADO_JOB_FAIL
= 2¶ Something went wrong with an Avocado Job execution, usually by an explicit
avocado.core.exceptions.JobError
exception.
-
avocado.core.exit_codes.
AVOCADO_JOB_INTERRUPTED
= 8¶ The job was explicitly interrupted. Usually this means that a user hit CTRL+C while the job was still running.
-
avocado.core.exit_codes.
AVOCADO_TESTS_FAIL
= 1¶ Job went fine, but some tests FAILed or ERRORed
avocado.core.job module¶
Job module - describes a sequence of automated test operations.
-
class
avocado.core.job.
Job
(args=None)¶ Bases:
object
A Job is a set of operations performed on a test machine.
Most of the time, we are interested in simply running tests, along with setup operations and event recording.
Creates an instance of Job class.
Parameters: args – an instance of argparse.Namespace
.-
create_test_suite
()¶ Creates the test suite for this Job
This is a public Job API as part of the documented Job phases
-
logdir
= None¶ The log directory for this job, also known as the job results directory. If it’s set to None, it means that the job results directory has not yet been created.
-
post_tests
()¶ Run the post tests execution hooks
By default this runs the plugins that implement the
avocado.core.plugin_interfaces.JobPostTests
interface.
-
pre_tests
()¶ Run the pre tests execution hooks
By default this runs the plugins that implement the
avocado.core.plugin_interfaces.JobPreTests
interface.
-
run
()¶ Runs all job phases, returning the test execution results.
This method is supposed to be the simplified interface for jobs, that is, they run all phases of a job.
Returns: Integer with overall job status. See avocado.core.exit_codes
for more information.
-
run_tests
()¶
-
test_suite
= None¶ The list of discovered/resolved tests that will be attempted to be run by this job. If set to None, it means that test resolution has not been attempted. If set to an empty list, it means that no test was found during resolution.
-
time_elapsed
= None¶ The total amount of time the job took from start to finish, or -1 if it has not been started by means of the run() method
-
time_end
= None¶ The time at which the job has finished or -1 if it has not been started by means of the run() method.
-
time_start
= None¶ The time at which the job has started or -1 if it has not been started by means of the run() method.
-
-
class
avocado.core.job.
TestProgram
¶ Bases:
object
Convenience class to make avocado test modules executable.
-
parseArgs
(argv)¶
-
runTests
()¶
-
-
avocado.core.job.
main
¶ alias of
TestProgram
avocado.core.job_id module¶
-
avocado.core.job_id.
create_unique_job_id
()¶ Create a 40 digit hex number to be used as a job ID string. (similar to SHA1)
Returns: 40 digit hex number string Return type: str
avocado.core.jobdata module¶
Record/retrieve job information
-
avocado.core.jobdata.
get_id
(path, jobid)¶ Gets the full Job ID using the results directory path and a partial Job ID or the string ‘latest’.
-
avocado.core.jobdata.
get_resultsdir
(logdir, jobid)¶ Gets the job results directory using a Job ID.
-
avocado.core.jobdata.
record
(args, logdir, mux, references=None, cmdline=None)¶ Records all required job information.
-
avocado.core.jobdata.
retrieve_args
(resultsdir)¶ Retrieves the job args from the results directory.
-
avocado.core.jobdata.
retrieve_cmdline
(resultsdir)¶ Retrieves the job command line from the results directory.
-
avocado.core.jobdata.
retrieve_config
(resultsdir)¶ Retrieves the job settings from the results directory.
-
avocado.core.jobdata.
retrieve_pwd
(resultsdir)¶ Retrieves the job pwd from the results directory.
-
avocado.core.jobdata.
retrieve_references
(resultsdir)¶ Retrieves the job test references from the results directory.
-
avocado.core.jobdata.
retrieve_variants
(resultsdir)¶ Retrieves the job Mux object from the results directory.
avocado.core.loader module¶
Test loader module.
-
avocado.core.loader.
ALL
= True¶ All tests (including broken ones)
-
avocado.core.loader.
AVAILABLE
= None¶ Available tests (for listing purposes)
-
class
avocado.core.loader.
AccessDeniedPath
¶ Bases:
object
Dummy object to represent reference pointing to a inaccessible path
-
class
avocado.core.loader.
BrokenSymlink
¶ Bases:
object
Dummy object to represent reference pointing to a BrokenSymlink path
-
avocado.core.loader.
DEFAULT
= False¶ Show default tests (for execution)
-
class
avocado.core.loader.
DummyLoader
(args, extra_params)¶ Bases:
avocado.core.loader.TestLoader
Dummy-runner loader class
-
discover
(url, which_tests=False)¶
-
static
get_decorator_mapping
()¶
-
static
get_type_label_mapping
()¶
-
name
= 'dummy'¶
-
-
class
avocado.core.loader.
ExternalLoader
(args, extra_params)¶ Bases:
avocado.core.loader.TestLoader
External-runner loader class
-
discover
(reference, which_tests=False)¶ Parameters: - reference – arguments passed to the external_runner
- which_tests – Limit tests to be displayed (ALL, AVAILABLE or DEFAULT)
Returns: list of matching tests
-
static
get_decorator_mapping
()¶
-
static
get_type_label_mapping
()¶
-
name
= 'external'¶
-
-
class
avocado.core.loader.
FileLoader
(args, extra_params)¶ Bases:
avocado.core.loader.TestLoader
Test loader class.
-
discover
(reference, which_tests=False)¶ Discover (possible) tests from a directory.
Recursively walk in a directory and find tests params. The tests are returned in alphabetic order.
Afterwards when “allowed_test_types” is supplied it verifies if all found tests are of the allowed type. If not return None (even on partial match).
Parameters: - reference – the directory path to inspect.
- which_tests – Limit tests to be displayed (ALL, AVAILABLE or DEFAULT)
Returns: list of matching tests
-
static
get_decorator_mapping
()¶
-
static
get_type_label_mapping
()¶
-
name
= 'file'¶
-
-
exception
avocado.core.loader.
InvalidLoaderPlugin
¶ Bases:
avocado.core.loader.LoaderError
Invalid loader plugin
-
exception
avocado.core.loader.
LoaderError
¶ Bases:
exceptions.Exception
Loader exception
-
exception
avocado.core.loader.
LoaderUnhandledReferenceError
(unhandled_references, plugins)¶ Bases:
avocado.core.loader.LoaderError
Test References not handled by any resolver
-
class
avocado.core.loader.
MissingTest
¶ Bases:
object
Class representing reference which failed to be discovered
-
class
avocado.core.loader.
NotATest
¶ Bases:
object
Class representing something that is not a test
-
class
avocado.core.loader.
TestLoader
(args, extra_params)¶ Bases:
object
Base for test loader classes
-
discover
(reference, which_tests=False)¶ Discover (possible) tests from an reference.
Parameters: - reference (str) – the reference to be inspected.
- which_tests – Limit tests to be displayed (ALL, AVAILABLE or DEFAULT)
Returns: a list of test matching the reference as params.
-
static
get_decorator_mapping
()¶ Get label mapping for display in test listing.
Returns: Dict {TestClass: decorator function}
-
get_extra_listing
()¶
-
static
get_type_label_mapping
()¶ Get label mapping for display in test listing.
Returns: Dict {TestClass: ‘TEST_LABEL_STRING’}
-
name
= None¶
-
-
class
avocado.core.loader.
TestLoaderProxy
¶ Bases:
object
-
clear_plugins
()¶
-
discover
(references, which_tests=False, force=None)¶ Discover (possible) tests from test references.
Parameters: - references (builtin.list) – a list of tests references; if [] use plugin defaults
- which_tests – Limit tests to be displayed (ALL, AVAILABLE or DEFAULT)
- force – don’t raise an exception when some test references are not resolved to tests.
Returns: A list of test factories (tuples (TestClass, test_params))
-
get_base_keywords
()¶
-
get_decorator_mapping
()¶
-
get_extra_listing
()¶
-
get_type_label_mapping
()¶
-
load_plugins
(args)¶
-
load_test
(test_factory)¶ Load test from the test factory.
Parameters: test_factory (tuple) – a pair of test class and parameters. Returns: an instance of avocado.core.test.Test
.
-
register_plugin
(plugin)¶
-
-
avocado.core.loader.
add_loader_options
(parser)¶
Filter the existing (unfiltered) test suite based on tags
The filtering mechanism is agnostic to test type. It means that if users request filtering by tag and the specific test type does not populate the test tags, it will be considered to have empty tags.
Parameters: - test_suite (dict) – the unfiltered test suite
- filter_by_tags (list of comma separated tags (['foo,bar', 'fast'])) – the list of tag sets to use as filters
- include_empty (bool) – if true tests without tags will not be filtered out
avocado.core.mux module¶
This file contains mux-enabled implementations of parts useful for creating a custom Varianter plugin.
-
class
avocado.core.mux.
Control
(code, value=None)¶ Bases:
object
Container used to identify node vs. control sequence
-
class
avocado.core.mux.
MuxPlugin
¶ Bases:
object
Base implementation of Mux-like Varianter plugin. It should be used as a base class in conjunction with
avocado.core.plugin_interfaces.Varianter
.-
debug
= None¶
-
default_params
= None¶
-
initialize_mux
(root, mux_path, debug)¶ Initialize the basic values
Note: We can’t use __init__ as this object is intended to be used via dispatcher with no __init__ arguments.
-
mux_path
= None¶
-
root
= None¶
-
to_str
(summary, variants, **kwargs)¶
-
update_defaults
(defaults)¶ See
avocado.core.plugin_interfaces.Varianter.update_defaults()
-
variants
= None¶
-
-
class
avocado.core.mux.
MuxTree
(root)¶ Bases:
object
Object representing part of the tree from the root to leaves or another multiplex domain. Recursively it creates multiplexed variants of the full tree.
Parameters: root – Root of this tree slice -
iter_variants
()¶ Iterates through variants without verifying the internal filters
:yield all existing variants
-
-
class
avocado.core.mux.
MuxTreeNode
(name='', value=None, parent=None, children=None)¶ Bases:
avocado.core.tree.TreeNode
Class for bounding nodes into tree-structure with support for multiplexation
-
fingerprint
()¶
-
merge
(other)¶ Merges other node into this one without checking the name of the other node. New values are appended, existing values overwritten and unaffected ones are kept. Then all other node children are added as children (recursively they get either appended at the end or merged into existing node in the previous position.
-
-
class
avocado.core.mux.
MuxTreeNodeDebug
(name='', value=None, parent=None, children=None, srcyaml=None)¶ Bases:
avocado.core.mux.MuxTreeNode
,avocado.core.tree.TreeNodeDebug
Debug version of TreeNodeDebug :warning: Origin of the value is appended to all values thus it’s not suitable for running tests.
-
merge
(other)¶
-
-
avocado.core.mux.
apply_filters
(root, filter_only=None, filter_out=None)¶ Apply a set of filters to the tree.
The basic filtering is filter only, which includes nodes, and the filter out rules, that exclude nodes.
Note that filter_out is stronger than filter_only, so if you filter out something, you could not bypass some nodes by using a filter_only rule.
Parameters: - root – Root node of the multiplex tree.
- filter_only – the list of paths which will include nodes.
- filter_out – the list of paths which will exclude nodes.
Returns: the original tree minus the nodes filtered by the rules.
-
avocado.core.mux.
path_parent
(path)¶ From a given path, return its parent path.
Parameters: path – the node path as string. Returns: the parent path as string.
avocado.core.output module¶
Manages output and logging in avocado applications.
-
avocado.core.output.
BUILTIN_STREAMS
= {'test': 'test output', 'debug': 'tracebacks and other debugging info', 'app': 'application output', 'early': 'early logging of other streams, including test (very verbose)', 'remote': 'fabric/paramiko debug'}¶ Builtin special keywords to enable set of logging streams
-
avocado.core.output.
BUILTIN_STREAM_SETS
= {'all': 'all builtin streams', 'none': 'disables regular output (leaving only errors enabled)'}¶ Groups of builtin streams
-
class
avocado.core.output.
FilterInfoAndLess
(name='')¶ Bases:
logging.Filter
Initialize a filter.
Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.
-
filter
(record)¶
-
-
class
avocado.core.output.
FilterWarnAndMore
(name='')¶ Bases:
logging.Filter
Initialize a filter.
Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.
-
filter
(record)¶
-
-
avocado.core.output.
LOG_JOB
= <logging.Logger object>¶ Pre-defined Avocado job/test logger
-
avocado.core.output.
LOG_UI
= <logging.Logger object>¶ Pre-defined Avocado human UI logger
-
class
avocado.core.output.
LoggingFile
(prefix='', level=10, logger=[<logging.RootLogger object>])¶ Bases:
object
File-like object that will receive messages pass them to logging.
Constructor. Sets prefixes and which logger is going to be used.
:param prefix - The prefix for each line logged by this object.
-
add_logger
(logger)¶
-
flush
()¶
-
isatty
()¶
-
rm_logger
(logger)¶
-
write
(data)¶ ” Writes data only if it constitutes a whole line. If it’s not the case, store it in a buffer and wait until we have a complete line. :param data - Raw data (a string) that will be processed.
-
writelines
(lines)¶ ” Writes itertable of lines
Parameters: lines – An iterable of strings that will be processed.
-
-
class
avocado.core.output.
MemStreamHandler
(stream=None)¶ Bases:
logging.StreamHandler
Handler that stores all records in self.log (shared in all instances)
Initialize the handler.
If stream is not specified, sys.stderr is used.
-
emit
(record)¶
-
flush
()¶ This is in-mem object, it does not require flushing
-
log
= []¶
-
-
exception
avocado.core.output.
PagerNotFoundError
¶ Bases:
exceptions.Exception
-
class
avocado.core.output.
Paginator
¶ Bases:
object
Paginator that uses less to display contents on the terminal.
Contains cleanup handling for when user presses ‘q’ (to quit less).
-
close
()¶
-
flush
()¶
-
write
(msg)¶
-
-
class
avocado.core.output.
ProgressStreamHandler
(stream=None)¶ Bases:
logging.StreamHandler
Handler class that allows users to skip new lines on each emission.
Initialize the handler.
If stream is not specified, sys.stderr is used.
-
emit
(record)¶
-
-
avocado.core.output.
STD_OUTPUT
= <avocado.core.output.StdOutput object>¶ Allows modifying the sys.stdout/sys.stderr
-
class
avocado.core.output.
StdOutput
¶ Bases:
object
Class to modify sys.stdout/sys.stderr
-
close
()¶ Enable original sys.stdout/sys.stderr and cleanup
-
enable_outputs
()¶ Enable sys.stdout/sys.stderr (either with 2 streams or with paginator)
-
enable_paginator
()¶ Enable paginator
-
enable_stderr
()¶ Enable sys.stderr and disable sys.stdout
-
fake_outputs
()¶ Replace sys.stdout/sys.stderr with in-memory-objects
-
print_records
()¶ Prints all stored messages as they occurred into streams they were produced for.
-
records
= []¶ List of records of stored output when stdout/stderr is disabled
-
-
avocado.core.output.
TERM_SUPPORT
= <avocado.core.output.TermSupport object>¶ Transparently handles colored terminal, when one is used
-
class
avocado.core.output.
TermSupport
¶ Bases:
object
-
COLOR_BLUE
= '\x1b[94m'¶
-
COLOR_DARKGREY
= '\x1b[90m'¶
-
COLOR_GREEN
= '\x1b[92m'¶
-
COLOR_RED
= '\x1b[91m'¶
-
COLOR_YELLOW
= '\x1b[93m'¶
-
CONTROL_END
= '\x1b[0m'¶
-
ESCAPE_CODES
= ['\x1b[94m', '\x1b[92m', '\x1b[93m', '\x1b[91m', '\x1b[90m', '\x1b[0m', '\x1b[1D', '\x1b[1C']¶ Class to help applications to colorize their outputs for terminals.
This will probe the current terminal and colorize output only if the stdout is in a tty or the terminal type is recognized.
-
MOVE_BACK
= '\x1b[1D'¶
-
MOVE_FORWARD
= '\x1b[1C'¶
-
disable
()¶ Disable colors from the strings output by this class.
-
error_str
()¶ Print a error string (red colored).
If the output does not support colors, just return the original string.
-
fail_header_str
(msg)¶ Print a fail header string (red colored).
If the output does not support colors, just return the original string.
-
fail_str
()¶ Print a fail string (red colored).
If the output does not support colors, just return the original string.
-
header_str
(msg)¶ Print a header string (blue colored).
If the output does not support colors, just return the original string.
-
healthy_str
(msg)¶ Print a healthy string (green colored).
If the output does not support colors, just return the original string.
-
interrupt_str
()¶ Print an interrupt string (red colored).
If the output does not support colors, just return the original string.
-
partial_str
(msg)¶ Print a string that denotes partial progress (yellow colored).
If the output does not support colors, just return the original string.
-
pass_str
()¶ Print a pass string (green colored).
If the output does not support colors, just return the original string.
-
skip_str
()¶ Print a skip string (yellow colored).
If the output does not support colors, just return the original string.
-
warn_header_str
(msg)¶ Print a warning header string (yellow colored).
If the output does not support colors, just return the original string.
-
warn_str
()¶ Print an warning string (yellow colored).
If the output does not support colors, just return the original string.
-
-
class
avocado.core.output.
Throbber
¶ Bases:
object
Produces a spinner used to notify progress in the application UI.
-
MOVES
= ['', '', '', '']¶
-
STEPS
= ['-', '\\', '|', '/']¶
-
render
()¶
-
-
avocado.core.output.
add_log_handler
(logger, klass=<class 'logging.StreamHandler'>, stream=<open file '<stdout>', mode 'w'>, level=20, fmt='%(name)s: %(message)s')¶ Add handler to a logger.
Parameters: - logger_name – the name of a
logging.Logger
instance, that is, the parameter tologging.getLogger()
- klass – Handler class (defaults to
logging.StreamHandler
) - stream – Logging stream, to be passed as an argument to
klass
(defaults tosys.stdout
) - level – Log level (defaults to INFO`)
- fmt – Logging format (defaults to
%(name)s: %(message)s
)
- logger_name – the name of a
-
avocado.core.output.
disable_log_handler
(logger)¶
-
avocado.core.output.
early_start
()¶ Replace all outputs with in-memory handlers
-
avocado.core.output.
log_plugin_failures
(failures)¶ Log in the application UI failures to load a set of plugins
Parameters: failures – a list of load failures, usually coming from a avocado.core.dispatcher.Dispatcher
attribute load_failures
-
avocado.core.output.
reconfigure
(args)¶ Adjust logging handlers accordingly to app args and re-log messages.
avocado.core.parser module¶
Avocado application command line parsing.
-
class
avocado.core.parser.
ArgumentParser
(prog=None, usage=None, description=None, epilog=None, version=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)¶ Bases:
argparse.ArgumentParser
Class to override argparse functions
-
error
(message)¶
-
-
class
avocado.core.parser.
FileOrStdoutAction
(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶ Bases:
argparse.Action
Controls claiming the right to write to the application standard output
-
class
avocado.core.parser.
Parser
¶ Bases:
object
Class to Parse the command line arguments.
-
finish
()¶ Finish the process of parsing arguments.
Side effect: set the final value for attribute args.
-
start
()¶ Start to parsing arguments.
At the end of this method, the support for subparsers is activated. Side effect: update attribute args (the namespace).
-
avocado.core.plugin_interfaces module¶
-
class
avocado.core.plugin_interfaces.
CLI
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for adding options (non-commands) to the command line
Plugins that want to add extra options to the core command line application or to sub commands should use the ‘avocado.plugins.cli’ namespace.
-
configure
(parser)¶ Configures the command line parser with options specific to this plugin
-
run
(args)¶ Execute any action the plugin intends.
Example of action may include activating a special features upon finding that the requested command line options were set by the user.
Note: this plugin class is not intended for adding new commands, for that please use CLICmd.
-
-
class
avocado.core.plugin_interfaces.
CLICmd
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for adding new commands to the command line app
Plugins that want to add extensions to the run command should use the ‘avocado.plugins.cli.cmd’ namespace.
-
configure
(parser)¶ Lets the extension add command line options and do early configuration
By default it will register its name as the command name and give its description as the help message.
-
description
= None¶
-
name
= None¶
-
run
(args)¶ Entry point for actually running the command
-
-
class
avocado.core.plugin_interfaces.
JobPost
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for adding actions after a job runs
Plugins that want to add actions to be run after a job runs, should use the ‘avocado.plugins.job.prepost’ namespace and implement the defined interface.
-
post
(job)¶ Entry point for actually running the post job action
-
-
class
avocado.core.plugin_interfaces.
JobPostTests
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for adding actions after a job runs tests
Plugins using this interface will run at the a time equivalent to plugins using the
JobPost
interface, that is, atavocado.core.job.Job.post_tests()
. This is becauseJobPost
based plugins will eventually be modified to really run after the job has finished, and not after it has run tests.-
post_tests
(job)¶ Entry point for job running actions after the tests execution
-
-
class
avocado.core.plugin_interfaces.
JobPre
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for adding actions before a job runs
Plugins that want to add actions to be run before a job runs, should use the ‘avocado.plugins.job.prepost’ namespace and implement the defined interface.
-
pre
(job)¶ Entry point for actually running the pre job action
-
-
class
avocado.core.plugin_interfaces.
JobPreTests
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for adding actions before a job runs tests
This interface looks similar to
JobPre
, but it’s intended to be called at a very specific place, that is, betweenavocado.core.job.Job.create_test_suite()
andavocado.core.job.Job.run_tests()
.-
pre_tests
(job)¶ Entry point for job running actions before tests execution
-
-
class
avocado.core.plugin_interfaces.
Plugin
¶ Bases:
object
-
class
avocado.core.plugin_interfaces.
Result
¶ Bases:
avocado.core.plugin_interfaces.Plugin
-
render
(result, job)¶ Entry point with method that renders the result
This will usually be used to write the result to a file or directory.
Parameters: - result (
avocado.core.result.Result
) – the complete job result - job (
avocado.core.job.Job
) – the finished job for which a result will be written
- result (
-
-
class
avocado.core.plugin_interfaces.
ResultEvents
¶ Bases:
avocado.core.plugin_interfaces.JobPreTests
,avocado.core.plugin_interfaces.JobPostTests
Base plugin interface for event based (stream-able) results
Plugins that want to add actions to be run after a job runs, should use the ‘avocado.plugins.result_events’ namespace and implement the defined interface.
-
end_test
(result, state)¶ Event triggered when a test finishes running
-
start_test
(result, state)¶ Event triggered when a test starts running
-
test_progress
(progress=False)¶ Interface to notify progress (or not) of the running test
-
-
class
avocado.core.plugin_interfaces.
Varianter
¶ Bases:
avocado.core.plugin_interfaces.Plugin
Base plugin interface for producing test variants usually from cmd line options
-
to_str
(summary, variants, **kwargs)¶ Return human readable representation
The summary/variants accepts verbosity where 0 means silent and maximum is up to the plugin.
Parameters: - summary – How verbose summary to output (int)
- variants – How verbose list of variants to output (int)
- kwargs – Other free-form arguments
Return type: str
-
update_defaults
(defaults)¶ Add default values
Note: Those values should not be part of the variant_id
-
avocado.core.result module¶
Contains the Result class, used for result accounting.
-
class
avocado.core.result.
Result
(job)¶ Bases:
object
Result class, holder for job (and its tests) result information.
Creates an instance of Result.
Parameters: job – an instance of avocado.core.job.Job
.-
check_test
(state)¶ Called once for a test to check status and report.
Parameters: test – A dict with test internal state
-
end_test
(state)¶ Called when the given test has been run.
Parameters: state (dict) – result of avocado.core.test.Test.get_state
.
-
end_tests
()¶ Called once after all tests are executed.
-
start_test
(state)¶ Called when the given test is about to run.
Parameters: state (dict) – result of avocado.core.test.Test.get_state
.
-
avocado.core.runner module¶
Test runner module.
-
avocado.core.runner.
TIMEOUT_PROCESS_ALIVE
= 60¶ when test reported status but the process did not finish
-
avocado.core.runner.
TIMEOUT_PROCESS_DIED
= 10¶ when the process died but the status was not yet delivered
-
avocado.core.runner.
TIMEOUT_TEST_INTERRUPTED
= 1¶ when test was interrupted (ctrl+c/timeout)
-
class
avocado.core.runner.
TestRunner
(job, result)¶ Bases:
object
A test runner class that displays tests results.
Creates an instance of TestRunner class.
Parameters: - job – an instance of
avocado.core.job.Job
. - result – an instance of
avocado.core.result.Result
-
DEFAULT_TIMEOUT
= 86400¶
-
run_suite
(test_suite, variants, timeout=0, replay_map=None, execution_order=None)¶ Run one or more tests and report with test result.
Parameters: - test_suite – a list of tests to run.
- variants – A varianter iterator to produce test params.
- timeout – maximum amount of time (in seconds) to execute.
- replay_map – optional list to override test class based on test index.
- execution_order – Mode in which we should iterate through tests resp. variants.
Returns: a set with types of test failures.
-
run_test
(test_factory, queue, summary, job_deadline=0)¶ Run a test instance inside a subprocess.
Parameters: - test_factory (tuple of
avocado.core.test.Test
and dict.) – Test factory (test class and parameters). - queue (:class`multiprocessing.Queue` instance.) – Multiprocess queue.
- summary (set.) – Contains types of test failures.
- job_deadline (int.) – Maximum time to execute.
- test_factory (tuple of
- job – an instance of
-
class
avocado.core.runner.
TestStatus
(job, queue)¶ Bases:
object
Test status handler
Parameters: - job – Associated job
- queue – test message queue
-
early_status
¶ Get early status
-
finish
(proc, started, step, deadline, result_dispatcher)¶ Wait for the test process to finish and report status or error status if unable to obtain the status till deadline.
Parameters: - proc – The test’s process
- started – Time when the test started
- first – Delay before first check
- step – Step between checks for the status
- deadline – Test execution deadline
- result_dispatcher – Result dispatcher (for test_progress notifications)
-
wait_for_early_status
(proc, timeout)¶ Wait until early_status is obtained :param proc: test process :param timeout: timeout for early_state :raise exceptions.TestError: On timeout/error
-
avocado.core.runner.
add_runner_failure
(test_state, new_status, message)¶ Append runner failure to the overall test status.
Parameters: - test_state – Original test state (dict)
- new_status – New test status (PASS/FAIL/ERROR/INTERRUPTED/...)
- message – The error message
avocado.core.safeloader module¶
Safe (AST based) test loader module utilities
-
avocado.core.safeloader.
DOCSTRING_DIRECTIVE_RE_RAW
= '\\s*:avocado:[ \\t]+([a-zA-Z0-9]+?[a-zA-Z0-9_:,\\=]*)\\s*$'¶ Gets the docstring directive value from a string. Used to tweak test behavior in various ways
-
avocado.core.safeloader.
check_docstring_directive
(docstring, directive)¶ Checks if there’s a given directive in a given docstring
Return type: bool
-
avocado.core.safeloader.
find_class_and_methods
(path, method_pattern=None, base_class=None)¶ Attempts to find methods names from a given Python source file
Parameters: - path (str) – path to a Python source code file
- method_pattern – compiled regex to match against method name
- base_class (str or None) – only consider classes that inherit from a given base class (or classes that inherit from any class if None is given)
-
avocado.core.safeloader.
get_docstring_directives
(docstring)¶ Returns the values of the avocado docstring directives
Parameters: docstring (str) – the complete text used as documentation Return type: builtin.list
Returns the test categories based on a :avocado: tags=category docstring
Return type: set
-
avocado.core.safeloader.
modules_imported_as
(module)¶ Returns a mapping of imported module names whether using aliases or not
The goal of this utility function is to return the name of the import as used in the rest of the module, whether an aliased import was used or not.
For code such as:
>>> import foo as bar
This function should return {“foo”: “bar”}
And for code such as:
>>> import foo
It should return {“foo”: “foo”}
Please note that only global level imports are looked at. If there are imports defined, say, inside functions or class definitions, they will not be seen by this function.
Parameters: module ( _ast.Module
) – module, as parsed byast.parse()
Returns: a mapping of names {<realname>: <alias>} of modules imported Return type: dict
avocado.core.settings module¶
Reads the avocado settings from a .ini file (from python ConfigParser).
-
exception
avocado.core.settings.
ConfigFileNotFound
(path_list)¶ Bases:
avocado.core.settings.SettingsError
Error thrown when the main settings file could not be found.
-
class
avocado.core.settings.
Settings
(config_path=None)¶ Bases:
object
Simple wrapper around ConfigParser, with a key type conversion available.
Constructor. Tries to find the main settings file and load it.
Parameters: config_path – Path to a config file. Useful for unittesting. -
get_value
(section, key, key_type=<type 'str'>, default=<object object>, allow_blank=False)¶ Get value from key in a given config file section.
Parameters: - section (str) – Config file section.
- key (str) – Config file key, relative to section.
- key_type (either string based names representing types,
including str, int, float, bool,
list and path, or the types themselves
limited to
str
,int
,float
,bool
andlist
.) – Type of key. - default – Default value for the key, if none found.
- allow_blank – Whether an empty value for the key is allowed.
Returns: value, if one available in the config. default value, if one provided.
Raises: SettingsError, in case key is not set and no default was provided.
-
no_default
= <object object>¶
-
process_config_path
(pth)¶
-
-
exception
avocado.core.settings.
SettingsError
¶ Bases:
exceptions.Exception
Base settings error.
-
exception
avocado.core.settings.
SettingsValueError
¶ Bases:
avocado.core.settings.SettingsError
Error thrown when we could not convert successfully a key to a value.
-
avocado.core.settings.
convert_value_type
(value, value_type)¶ Convert a string value to a given value type.
Parameters: - value (str.) – Value we want to convert.
- value_type (str or type.) – Type of the value we want to convert.
Returns: Converted value type.
Return type: Dependent on value_type.
Raise: TypeError, in case it was not possible to convert values.
avocado.core.status module¶
Maps the different status strings in avocado to booleans.
This is used by methods and functions to return a cut and dry answer to whether a test or a job in avocado PASSed or FAILed.
avocado.core.sysinfo module¶
-
class
avocado.core.sysinfo.
Collectible
(logf)¶ Bases:
object
Abstract class for representing collectibles by sysinfo.
-
readline
(logdir)¶ Read one line of the collectible object.
Parameters: logdir – Path to a log directory.
-
-
class
avocado.core.sysinfo.
Command
(cmd, logf=None, compress_log=False)¶ Bases:
avocado.core.sysinfo.Collectible
Collectible command.
Parameters: - cmd – String with the command.
- logf – Basename of the file where output is logged (optional).
- compress_logf – Wether to compress the output of the command.
-
run
(logdir)¶ Execute the command as a subprocess and log its output in logdir.
Parameters: logdir – Path to a log directory.
-
class
avocado.core.sysinfo.
Daemon
(cmd, logf=None, compress_log=False)¶ Bases:
avocado.core.sysinfo.Command
Collectible daemon.
Parameters: - cmd – String with the daemon command.
- logf – Basename of the file where output is logged (optional).
- compress_logf – Wether to compress the output of the command.
-
run
(logdir)¶ Execute the daemon as a subprocess and log its output in logdir.
Parameters: logdir – Path to a log directory.
-
stop
()¶ Stop daemon execution.
-
class
avocado.core.sysinfo.
JournalctlWatcher
(logf=None)¶ Bases:
avocado.core.sysinfo.Collectible
Track the content of systemd journal into a compressed file.
Parameters: logf – Basename of the file where output is logged (optional). -
run
(logdir)¶
-
-
class
avocado.core.sysinfo.
LogWatcher
(path, logf=None)¶ Bases:
avocado.core.sysinfo.Collectible
Keep track of the contents of a log file in another compressed file.
This object is normally used to track contents of the system log (/var/log/messages), and the outputs are gzipped since they can be potentially large, helping to save space.
Parameters: - path – Path to the log file.
- logf – Basename of the file where output is logged (optional).
-
run
(logdir)¶ Log all of the new data present in the log file.
-
class
avocado.core.sysinfo.
Logfile
(path, logf=None)¶ Bases:
avocado.core.sysinfo.Collectible
Collectible system file.
Parameters: - path – Path to the log file.
- logf – Basename of the file where output is logged (optional).
-
run
(logdir)¶ Copy the log file to the appropriate log dir.
Parameters: logdir – Log directory which the file is going to be copied to.
-
class
avocado.core.sysinfo.
SysInfo
(basedir=None, log_packages=None, profiler=None)¶ Bases:
object
Log different system properties at some key control points:
- start_job
- start_test
- end_test
- end_job
Set sysinfo collectibles.
Parameters: - basedir – Base log dir where sysinfo files will be located.
- log_packages – Whether to log system packages (optional because logging packages is a costly operation). If not given explicitly, tries to look in the config files, and if not found, defaults to False.
- profiler – Wether to use the profiler. If not given explicitly, tries to look in the config files.
-
add_cmd
(cmd, hook)¶ Add a command collectible.
Parameters: - cmd – Command to log.
- hook – In which hook this cmd should be logged (start job, end job).
-
add_file
(filename, hook)¶ Add a system file collectible.
Parameters: - filename – Path to the file to be logged.
- hook – In which hook this file should be logged (start job, end job).
-
add_watcher
(filename, hook)¶ Add a system file watcher collectible.
Parameters: - filename – Path to the file to be logged.
- hook – In which hook this watcher should be logged (start job, end job).
-
end_job_hook
()¶ Logging hook called whenever a job finishes.
-
end_test_hook
()¶ Logging hook called after a test finishes.
-
start_job_hook
()¶ Logging hook called whenever a job starts.
-
start_test_hook
()¶ Logging hook called before a test starts.
-
avocado.core.sysinfo.
collect_sysinfo
(args)¶ Collect sysinfo to a base directory.
Parameters: args – argparse.Namespace
object with command line params.
avocado.core.test module¶
Contains the base test implementation, used as a base for the actual framework tests.
-
avocado.core.test.
COMMON_TMPDIR_NAME
= 'AVOCADO_TESTS_COMMON_TMPDIR'¶ Environment variable used to store the location of a temporary directory which is preserved across all tests execution (usually in one job)
-
class
avocado.core.test.
DryRunTest
(*args, **kwargs)¶ Bases:
avocado.core.test.MockingTest
Fake test which logs itself and reports as CANCEL
This class substitutes other classes. Let’s just ignore the remaining arguments and only set the ones supported by avocado.Test
-
setUp
()¶
-
-
class
avocado.core.test.
ExternalRunnerTest
(name, params=None, base_logdir=None, job=None, external_runner=None)¶ Bases:
avocado.core.test.SimpleTest
-
filename
¶
-
test
()¶
-
-
class
avocado.core.test.
MockingTest
(*args, **kwargs)¶ Bases:
avocado.core.test.Test
Class intended as generic substitute for avocado tests which will not be executed for some reason. This class is expected to be overridden by specific reason-oriented sub-classes.
This class substitutes other classes. Let’s just ignore the remaining arguments and only set the ones supported by avocado.Test
-
test
()¶
-
-
exception
avocado.core.test.
NameNotTestNameError
¶ Bases:
exceptions.Exception
The given test name is not a TestName instance
With the introduction of
avocado.core.test.TestName
, it’s not allowed to use other types as thename
parameter to a test instance. This exception is raised when this is attempted.
-
class
avocado.core.test.
ReplaySkipTest
(*args, **kwargs)¶ Bases:
avocado.core.test.MockingTest
Skip test due to job replay filter.
This test is skipped due to a job replay filter. It will never have a chance to execute.
This class substitutes other classes. Let’s just ignore the remaining arguments and only set the ones supported by avocado.Test
-
test
(*args, **kwargs)¶
-
-
class
avocado.core.test.
SimpleTest
(name, params=None, base_logdir=None, job=None)¶ Bases:
avocado.core.test.Test
Run an arbitrary command that returns either 0 (PASS) or !=0 (FAIL).
-
execute_cmd
()¶ Run the executable, and log its detailed execution.
-
filename
¶ Returns the name of the file (path) that holds the current test
-
re_avocado_log
= <_sre.SRE_Pattern object at 0x28bdbd0>¶
-
test
()¶ Run the test and postprocess the results
-
-
class
avocado.core.test.
Test
(methodName='test', name=None, params=None, base_logdir=None, job=None, runner_queue=None)¶ Bases:
unittest.case.TestCase
Base implementation for the test class.
You’ll inherit from this to write your own tests. Typically you’ll want to implement setUp(), test*() and tearDown() methods on your own tests.
Initializes the test.
Parameters: - methodName – Name of the main method to run. For the sake of compatibility with the original unittest class, you should not set this.
- name (
avocado.core.test.TestName
) – Pretty name of the test name. For normal tests, written with the avocado API, this should not be set. This is reserved for internal Avocado use, such as when running random executables as tests. - base_logdir – Directory where test logs should go. If None
provided, it’ll use
avocado.data_dir.create_job_logs_dir()
. - job – The job that this test is part of.
Raises: -
basedir
¶ The directory where this test (when backed by a file) is located at
-
cache_dirs
= None¶
-
cancel
(message=None)¶ Cancels the test.
This method is expected to be called from the test method, not anywhere else, since by definition, we can only cancel a test that is currently under execution. If you call this method outside the test method, avocado will mark your test status as ERROR, and instruct you to fix your test in the error message.
Parameters: message (str) – an optional message that will be recorded in the logs
-
datadir
¶ Returns the path to the directory that contains test data files
-
default_params
= {}¶ default_params will be deprecated by the end of 2017.
-
error
(message=None)¶ Errors the currently running test.
After calling this method a test will be terminated and have its status as ERROR.
Parameters: message (str) – an optional message that will be recorded in the logs
-
fail
(message=None)¶ Fails the currently running test.
After calling this method a test will be terminated and have its status as FAIL.
Parameters: message (str) – an optional message that will be recorded in the logs
-
fail_class
¶
-
fail_reason
¶
-
fetch_asset
(name, asset_hash=None, algorithm='sha1', locations=None, expire=None)¶ Method o call the utils.asset in order to fetch and asset file supporting hash check, caching and multiple locations.
Parameters: - name – the asset filename or URL
- asset_hash – asset hash (optional)
- algorithm – hash algorithm (optional, defaults to sha1)
- locations – list of URLs from where the asset can be fetched (optional)
- expire – time for the asset to expire
Raises: EnvironmentError – When it fails to fetch the asset
Returns: asset file local path
-
filename
¶ Returns the name of the file (path) that holds the current test
-
get_state
()¶ Serialize selected attributes representing the test state
Returns: a dictionary containing relevant test state data Return type: dict
-
job
¶ The job this test is associated with
-
log
¶ The enhanced test log
-
logdir
¶ Path to this test’s logging dir
-
logfile
¶ Path to this test’s main debug.log file
-
name
¶ The test name (TestName instance)
-
outputdir
¶ Directory available to test writers to attach files to the results
-
params
¶ Parameters of this test (AvocadoParam instance)
-
report_state
()¶ Send the current test state to the test runner process
-
run_avocado
()¶ Wraps the run method, for execution inside the avocado runner.
Result: Unused param, compatibility with unittest.TestCase
.
-
runner_queue
¶ The communication channel between test and test runner
-
running
¶ Whether this test is currently being executed
-
set_runner_queue
(runner_queue)¶ Override the runner_queue
-
skip
(message=None)¶ Skips the currently running test.
This method should only be called from a test’s setUp() method, not anywhere else, since by definition, if a test gets to be executed, it can’t be skipped anymore. If you call this method outside setUp(), avocado will mark your test status as ERROR, and instruct you to fix your test in the error message.
Parameters: message (str) – an optional message that will be recorded in the logs
-
srcdir
= None¶
-
status
¶ The result status of this test
-
teststmpdir
¶ Returns the path of the temporary directory that will stay the same for all tests in a given Job.
-
time_elapsed
= -1¶ duration of the test execution (always recalculated from time_end - time_start
-
time_end
= -1¶ (unix) time when the test finished (could be forced from test)
-
time_start
= -1¶ (unix) time when the test started (could be forced from test)
-
timeout
= None¶ Test timeout (the timeout from params takes precedence)
-
traceback
¶
-
whiteboard
= ''¶ Arbitrary string which will be stored in $logdir/whiteboard location when the test finishes.
-
workdir
= None¶
-
class
avocado.core.test.
TestError
(*args, **kwargs)¶ Bases:
avocado.core.test.Test
Generic test error.
-
test
()¶
-
-
class
avocado.core.test.
TestName
(uid, name, variant=None, no_digits=None)¶ Bases:
object
Test name representation
Test name according to avocado specification
Parameters: - uid – unique test id (within the job)
- name – test name (identifies the executed test)
- variant – variant id
- no_digits – number of digits of the test uid
-
str_filesystem
()¶ File-system friendly representation of the test name
-
class
avocado.core.test.
TimeOutSkipTest
(*args, **kwargs)¶ Bases:
avocado.core.test.MockingTest
Skip test due job timeout.
This test is skipped due a job timeout. It will never have a chance to execute.
This class substitutes other classes. Let’s just ignore the remaining arguments and only set the ones supported by avocado.Test
-
test
(*args, **kwargs)¶
-
avocado.core.tree module¶
Tree data structure with nodes.
This tree structure (Tree drawing code) was inspired in the base tree data structure of the ETE 2 project:
A library for analysis of phylogenetics trees.
Explicit permission has been given by the copyright owner of ETE 2 Jaime Huerta-Cepas <jhcepas@gmail.com> to take ideas/use snippets from his original base tree code and re-license under GPLv2+, given that GPLv3 and GPLv2 (used in some avocado files) are incompatible.
-
class
avocado.core.tree.
FilterSet
¶ Bases:
set
Set of filters in standardized form
-
add
(item)¶
-
update
(items)¶
-
-
class
avocado.core.tree.
OutputList
(values, nodes, yamls)¶ Bases:
list
List with some debug info
-
class
avocado.core.tree.
OutputValue
(value, node, srcyaml)¶ Bases:
object
Ordinary value with some debug info
-
class
avocado.core.tree.
TreeEnvironment
¶ Bases:
dict
TreeNode environment with values, origins and filters
-
copy
()¶
-
-
class
avocado.core.tree.
TreeNode
(name='', value=None, parent=None, children=None)¶ Bases:
object
Class for bounding nodes into tree-structure.
-
add_child
(node)¶ Append node as child. Nodes with the same name gets merged into the existing position.
-
detach
()¶ Detach this node from parent
-
environment
¶ Node environment (values + preceding envs)
-
fingerprint
()¶ Reports string which represents the value of this node.
-
get_environment
()¶ Get node environment (values + preceding envs)
-
get_leaves
()¶ Get list of leaf nodes
-
get_node
(path, create=False)¶ Parameters: - path – Path of the desired node (relative to this node)
- create – Create the node (and intermediary ones) when not present
Returns: the node associated with this path
Raises: ValueError – When path doesn’t exist and create not set
-
get_parents
()¶ Get list of parent nodes
-
get_path
(sep='/')¶ Get node path
-
get_root
()¶ Get root of this tree
-
is_leaf
¶ Is this a leaf node?
-
iter_children_preorder
()¶ Iterate through children
-
iter_leaves
()¶ Iterate through leaf nodes
-
iter_parents
()¶ Iterate through parent nodes to root
-
merge
(other)¶ Merges other node into this one without checking the name of the other node. New values are appended, existing values overwritten and unaffected ones are kept. Then all other node children are added as children (recursively they get either appended at the end or merged into existing node in the previous position.
-
parents
¶ List of parent nodes
-
path
¶ Node path
-
root
¶ Root of this tree
-
set_environment_dirty
()¶ Set the environment cache dirty. You should call this always when you query for the environment and then change the value or structure. Otherwise you’ll get the old environment instead.
-
-
class
avocado.core.tree.
TreeNodeDebug
(name='', value=None, parent=None, children=None, srcyaml=None)¶ Bases:
avocado.core.tree.TreeNode
Debug version of TreeNodeDebug :warning: Origin of the value is appended to all values thus it’s not suitable for running tests.
-
merge
(other)¶ Override origin with the one from other tree. Updated/Newly set values are going to use this location as origin.
-
-
class
avocado.core.tree.
TreeNodeEnvOnly
(path, environment=None)¶ Bases:
object
Minimal TreeNode-like class providing interface for AvocadoParams
Parameters: - path – Path of this node (must not end with ‘/’)
- environment – List of pair/key/value items
-
get_environment
()¶
-
get_path
()¶
-
class
avocado.core.tree.
ValueDict
(srcyaml, node, values)¶ Bases:
dict
Dict which stores the origin of the items
-
iteritems
()¶ Slower implementation with the use of __getitem__
-
-
avocado.core.tree.
get_named_tree_cls
(path, klass=<class 'avocado.core.tree.TreeNodeDebug'>)¶ Return TreeNodeDebug class with hardcoded yaml path
-
avocado.core.tree.
tree_view
(root, verbose=None, use_utf8=None)¶ Generate tree-view of the given node :param root: root node :param verbose: verbosity (0, 1, 2, 3) :param use_utf8: Use utf-8 encoding (None=autodetect) :return: string representing this node’s tree structure
avocado.core.varianter module¶
Multiplex and create variants.
-
class
avocado.core.varianter.
AvocadoParam
(leaves, name)¶ Bases:
object
This is a single slice params. It can contain multiple leaves and tries to find matching results.
Parameters: - leaves – this slice’s leaves
- name – this slice’s name (identifier used in exceptions)
-
get_or_die
(path, key)¶ Get a value or raise exception if not present :raise NoMatchError: When no matches :raise KeyError: When value is not certain (multiple matches)
-
iteritems
()¶ Very basic implementation which iterates through __ALL__ params, which generates lots of duplicate entries due to inherited values.
-
str_leaves_variant
¶ String with identifier and all params
-
class
avocado.core.varianter.
AvocadoParams
(leaves, test_id, mux_path, default_params)¶ Bases:
object
Params object used to retrieve params from given path. It supports absolute and relative paths. For relative paths one can define multiple paths to search for the value. It contains compatibility wrapper to act as the original avocado Params, but by special usage you can utilize the new API. See
get()
docstring for details.You can also iterate through all keys, but this can generate quite a lot of duplicate entries inherited from ancestor nodes. It shouldn’t produce false values, though.
In this version each new “get()” call is logged into avocado.LOG_JOB. This is subject of change (separate file, perhaps)
Parameters: - leaves – List of TreeNode leaves defining current variant
- test_id – test id
- mux_path – list of entry points
- default_params – dict of params used when no matches found
Note
default_params will be deprecated by the end of 2017.
-
get
(key, path=None, default=None)¶ Retrieve value associated with key from params :param key: Key you’re looking for :param path: namespace [‘*’] :param default: default value when not found :raise KeyError: In case of multiple different values (params clash)
-
iteritems
()¶ Iterate through all available params and yield origin, key and value of each unique value.
-
log
(key, path, default, value)¶ Predefined format for displaying params query
-
objects
(key, path=None)¶ Return the names of objects defined using a given key.
Parameters: key – The name of the key whose value lists the objects (e.g. ‘nics’).
-
class
avocado.core.varianter.
FakeVariantDispatcher
(state)¶ Bases:
object
This object can act instead of VarianterDispatcher to report loaded variants.
-
map_method
(method, *args, **kwargs)¶ Reports list containing one result of map_method on self
-
-
exception
avocado.core.varianter.
NoMatchError
¶ Bases:
exceptions.KeyError
-
class
avocado.core.varianter.
Varianter
(debug=False, state=None)¶ Bases:
object
This object takes care of producing test variants
Parameters: - debug – Store whether this instance should debug the mux
- state – Force-varianter state
Note: people need to check whether mux uses debug and reflect that in order to provide the right results.
-
add_default_param
(name, key, value, path=None)¶ Stores the path/key/value into default params
This allow injecting default arguments which are mainly intended for machine/os-related params. It should not affect the test results and by definition it should not affect the variant id.
Parameters: - name – Name of the component which injects this param
- key – Key to which we’d like to assign the value
- value – The key’s value
- path – Optional path to the node to which we assign the value, by default ‘/’.
-
dump
()¶ Dump the variants in loadable-state
This is lossy representation which takes all yielded variants and replaces the list of nodes with TreeNodeEnvOnly representations:
[{'mux_path': mux_path, 'variant_id': variant_id, 'variant': dump_tree_nodes(original_variant)}, {'mux_path': [str, str, ...], 'variant_id': str, 'variant': [(str, [(str, str, object), ...])], {'mux_path': ['/run/*'], 'variant_id': 'cat-26c0' 'variant': [('/pig/cat', [('/pig', 'ant', 'fox'), ('/pig/cat', 'dog', 'bee')])]} ...]
where dump_tree_nodes looks like:
[(node.path, environment_representation), (node.path, [(path1, key1, value1), (path2, key2, value2), ...]), ('/pig/cat', [('/pig', 'ant', 'fox')])
Returns: loadable Varianter representation
-
get_number_of_tests
(test_suite)¶ Returns: overall number of tests * number of variants
-
is_parsed
()¶ Reports whether the varianter was already parsed
-
itertests
()¶ Yields all variants of all plugins
- The variant is defined as dictionary with at least:
- variant_id - name of the current variant
- variant - AvocadoParams-compatible variant (usually a list of
- TreeNodes but dict or simply None are also possible values)
- mux_path - default path(s)
:yield variant
-
load
(state)¶ Load the variants state
Current implementation supports loading from a list of loadable variants. It replaces the VariantDispatcher with fake implementation which reports the loaded (and initialized) variants.
Parameters: state – loadable Varianter representation
-
parse
(args)¶ Apply options defined on the cmdline and initialize the plugins.
Parameters: args – Parsed cmdline arguments
-
to_str
(summary=0, variants=0, **kwargs)¶ Return human readable representation
The summary/variants accepts verbosity where 0 means do not display at all and maximum is up to the plugin.
Parameters: - summary – How verbose summary to output (int)
- variants – How verbose list of variants to output (int)
- kwargs – Other free-form arguments
Return type: str