Internal (Core) APIs

Internal APIs that may be of interest to Avocado hackers.

Submodules

avocado.core.app module

The core Avocado application.

class avocado.core.app.AvocadoApp

Bases: object

Avocado application.

run()

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(base_dir=None, unique_id=None)

Create a log directory for a job, or a stand alone execution of a test.

Parameters:
  • base_dir – Base log directory, if None, use value from configuration.
  • unique_id – The unique identification. If None, create one.
Return type:

str

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

Returns the list of cache dirs, according to configuration and convention

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.cancel_on(exceptions=None)

Cancel the test when decorated function produces exception of the specified type.

Parameters:exceptions – Tuple or single exception to be assumed as test CANCEL [Exception].
Note:self.error, self.cancel and self.fail remain intact.
Note:to allow simple usage param ‘exceptions’ must not be callable.
avocado.core.decorators.deco_factory(behavior, signal)

Decorator factory.

Returns a decorator used to signal the test when specified exception is raised. :param behavior: expected test result behavior. :param signal: delegating exception.

avocado.core.decorators.fail_on(exceptions=None)

Fail the test when decorated function produces exception of the specified type.

Parameters:exceptions – Tuple or single exception to be assumed as test FAIL [Exception].
Note:self.error, self.cancel and self.fail remain 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.defaults module

The Avocado core defaults

avocado.core.defaults.ENCODING = 'utf-8'

The encoding used by default on all data input

avocado.core.defaults.TIMEOUT_AFTER_INTERRUPTED = 60

The amount of time to give to the test process after it it has been interrupted (such as with CTRL+C)

avocado.core.defaults.TIMEOUT_PROCESS_ALIVE = 60

The amount of time to wait after a test has reported status but the test process has not finished

avocado.core.defaults.TIMEOUT_PROCESS_DIED = 10

The amount of to wait for a test status after the process has been noticed to be dead

avocado.core.dispatcher module

Extensions/plugins dispatchers

Besides the dispatchers listed here, there’s also a lower level dispatcher that these depend upon: avocado.core.settings_dispatcher.SettingsDispatcher

class avocado.core.dispatcher.CLICmdDispatcher

Bases: avocado.core.enabled_extension_manager.EnabledExtensionManager

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.enabled_extension_manager.EnabledExtensionManager

Calls extensions on configure/run

Automatically adds all the extension with entry points registered under ‘avocado.plugins.cli’

class avocado.core.dispatcher.JobPrePostDispatcher

Bases: avocado.core.enabled_extension_manager.EnabledExtensionManager

Calls extensions before Job execution

Automatically adds all the extension with entry points registered under ‘avocado.plugins.job.prepost’

class avocado.core.dispatcher.ResultDispatcher

Bases: avocado.core.enabled_extension_manager.EnabledExtensionManager

class avocado.core.dispatcher.ResultEventsDispatcher(config)

Bases: avocado.core.enabled_extension_manager.EnabledExtensionManager

class avocado.core.dispatcher.VarianterDispatcher

Bases: avocado.core.enabled_extension_manager.EnabledExtensionManager

map_method_with_return(method_name, *args, **kwargs)

The same as map_method but additionally reports the list of returned values and optionally deepcopies the passed arguments

Parameters:
  • method_name – Name of the method to be called on each ext
  • args – Arguments to be passed to all called functions
  • kwargs – Key-word arguments to be passed to all called functions if “deepcopy” == True is present in kwargs the args and kwargs are deepcopied before passing it to each called function.
map_method_with_return_copy(method_name, *args, **kwargs)

The same as map_method_with_return, but use copy.deepcopy on each passed arg

avocado.core.enabled_extension_manager module

Extension manager with disable/ordering support

class avocado.core.enabled_extension_manager.EnabledExtensionManager(namespace, invoke_kwds=None)

Bases: avocado.core.extension_manager.ExtensionManager

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.

avocado.core.exceptions module

Exception classes, useful for tests, and other parts of the framework code.

exception avocado.core.exceptions.JobBaseException

Bases: 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: 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: 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, 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.TestSkipError

Bases: avocado.core.exceptions.TestBaseException

Indicates 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.extension_manager module

Base extension manager

This is a mix of stevedore-like APIs and behavior, with Avocado’s own look and feel.

class avocado.core.extension_manager.Extension(name, entry_point, plugin, obj)

Bases: object

This is a verbatim copy from the stevedore.extension class with the same name

class avocado.core.extension_manager.ExtensionManager(namespace, invoke_kwds=None)

Bases: object

NAMESPACE_PREFIX = 'avocado.plugins.'

Default namespace prefix for Avocado extensions

enabled(extension)

Checks if a plugin is enabled

Sub classes can change this implementation to determine their own criteria.

fully_qualified_name(extension)

Returns the Avocado fully qualified plugin name

Parameters:extension (Extension) – an Extension instance
map_method(method_name, *args)

Maps method_name on each extension in case the extension has the attr

Parameters:
  • method_name – Name of the method to be called on each ext
  • args – Arguments to be passed to all called functions
map_method_with_return(method_name, *args, **kwargs)

The same as map_method but additionally reports the list of returned values and optionally deepcopies the passed arguments

Parameters:
  • method_name – Name of the method to be called on each ext
  • args – Arguments to be passed to all called functions
  • kwargs – Key-word arguments to be passed to all called functions if “deepcopy” == True is present in kwargs the args and kwargs are deepcopied before passing it to each called function.
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 standard sorted().

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

avocado.core.job module

Job module - describes a sequence of automated test operations.

class avocado.core.job.Job(config=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:config (dict) – the job configuration, usually set by command line options and argument parsing
LOG_MAP = {'critical': 50, 'debug': 10, 'error': 40, 'info': 20, 'warning': 30}
cleanup()

Cleanup the temporary job handlers (dirs, global setting, …)

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

The actual test execution phase

setup()

Setup the temporary job handlers (dirs, global setting, …)

test_parameters = None

Placeholder for test parameters (related to –test-parameters command line option). They’re kept in the job because they will be prepared only once, since they are read only and will be shared across all tests of a job.

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.

parse_args(argv)
run_tests()
avocado.core.job.main

alias of avocado.core.job.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(config, logdir, variants, references=None, cmdline=None)

Records all required job information.

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

Retrieves the job config 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 variants object from the results directory.

avocado.core.loader module

Test loader module.

class avocado.core.loader.AccessDeniedPath

Bases: object

Dummy object to represent reference pointing to a inaccessible path

Bases: object

Dummy object to represent reference pointing to a BrokenSymlink path

class avocado.core.loader.DiscoverMode

Bases: enum.Enum

An enumeration.

ALL = <object object>

All tests (including broken ones)

AVAILABLE = <object object>

Available tests (for listing purposes)

DEFAULT = <object object>

Show default tests (for execution)

class avocado.core.loader.ExternalLoader(args, extra_params)

Bases: avocado.core.loader.TestLoader

External-runner loader class

discover(reference, which_tests=<DiscoverMode.DEFAULT: <object object>>)
Parameters:
  • reference – arguments passed to the external_runner
  • which_tests (DiscoverMode) – Limit tests to be displayed
Returns:

list of matching tests

static get_decorator_mapping()

Get label mapping for display in test listing.

Returns:Dict {TestClass: decorator function}
static get_type_label_mapping()

Get label mapping for display in test listing.

Returns:Dict {TestClass: ‘TEST_LABEL_STRING’}
name = 'external'
class avocado.core.loader.FileLoader(args, extra_params)

Bases: avocado.core.loader.TestLoader

Test loader class.

discover(reference, which_tests=<DiscoverMode.DEFAULT: <object object>>)

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 (DiscoverMode) – Limit tests to be displayed
Returns:

list of matching tests

static get_decorator_mapping()

Get label mapping for display in test listing.

Returns:Dict {TestClass: decorator function}
static get_type_label_mapping()

Get label mapping for display in test listing.

Returns:Dict {TestClass: ‘TEST_LABEL_STRING’}
name = 'file'
exception avocado.core.loader.InvalidLoaderPlugin

Bases: avocado.core.loader.LoaderError

Invalid loader plugin

exception avocado.core.loader.LoaderError

Bases: 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=<DiscoverMode.DEFAULT: <object object>>)

Discover (possible) tests from an reference.

Parameters:
  • reference (str) – the reference to be inspected.
  • which_tests (DiscoverMode) – Limit tests to be displayed
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()
get_full_decorator_mapping()

Allows extending the decorator-mapping after the object is initialized

get_full_type_label_mapping()

Allows extending the type-label-mapping after the object is initialized

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=<DiscoverMode.DEFAULT: <object object>>, force=None)

Discover (possible) tests from test references.

Parameters:
  • references (builtin.list) – a list of tests references; if [] use plugin defaults
  • which_tests (DiscoverMode) – Limit tests to be displayed
  • 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)

avocado.core.nrunner module

class avocado.core.nrunner.BaseRunner(runnable)

Bases: object

Base interface for a Runner

run()
class avocado.core.nrunner.ExecRunner(runnable)

Bases: avocado.core.nrunner.BaseRunner

Runner for standalone executables with or without arguments

run()
class avocado.core.nrunner.ExecTestRunner(runnable)

Bases: avocado.core.nrunner.ExecRunner

Runner for standalone executables treated as tests

This is similar in concept to the Avocado “SIMPLE” test type, in which an executable returning 0 means that a test passed, and anything else means that a test failed.

run()
class avocado.core.nrunner.NoOpRunner(runnable)

Bases: avocado.core.nrunner.BaseRunner

Sample runner that performs no action before reporting FINISHED status

run()
class avocado.core.nrunner.PythonUnittestRunner(runnable)

Bases: avocado.core.nrunner.BaseRunner

Runner for Python unittests

The runnable uri is used as the test name that the native unittest TestLoader will use to find the test. A native unittest test runner (TextTestRunner) will be used to execute the test.

run()
avocado.core.nrunner.RUNNER_RUN_CHECK_INTERVAL = 0.01

The amount of time (in seconds) between each internal status check

avocado.core.nrunner.RUNNER_RUN_STATUS_INTERVAL = 0.5

The amount of time (in seconds) between a status report from a runner that performs its work asynchronously

class avocado.core.nrunner.Runnable(kind, uri=None, *args, **kwargs)

Bases: object

Describes an entity that be executed in the context of a task

A instance of BaseRunner is the entity that will actually execute a runnable.

class avocado.core.nrunner.StatusEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an OverflowError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (‘, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
class avocado.core.nrunner.StatusServer(uri, tasks_pending=None)

Bases: object

cb(reader, _)
create_server_task()
start()
wait()
class avocado.core.nrunner.Task(identifier, runnable, status_uris=None)

Bases: object

Wraps the execution of a runnable

While a runnable describes what to be run, and gets run by a runner, a task should be a unique entity to track its state, that is, whether it is pending, is running or has finished.

Parameters:
  • identifier
  • runnable
run()
class avocado.core.nrunner.TaskStatusService(uri)

Bases: object

Implementation of interface that a task can use to post status updates

TODO: make the interface generic and this just one of the implementations

close()
post(status)
avocado.core.nrunner.json_base64_decode(dct)
avocado.core.nrunner.json_dumps(data)
avocado.core.nrunner.json_loads(data)
avocado.core.nrunner.main()
avocado.core.nrunner.parse()
avocado.core.nrunner.runnable_from_args(args)
avocado.core.nrunner.runnable_from_recipe(recipe_path)

Returns a runnable from a runnable recipe file

avocado.core.nrunner.runner_from_runnable(runnable)

Gets a Runner instance from a Runnable

avocado.core.nrunner.subcommand_runnable_run(args, echo=<built-in function print>)
avocado.core.nrunner.subcommand_runnable_run_recipe(args, echo=<built-in function print>)
avocado.core.nrunner.subcommand_status_server(args)
avocado.core.nrunner.subcommand_task_run(args, echo=<built-in function print>)
avocado.core.nrunner.subcommand_task_run_recipe(args, echo=<built-in function print>)
avocado.core.nrunner.task_from_recipe(task_path)

Creates a task (which contains a runnable) from a task recipe file

avocado.core.nrunner.task_run(task, echo)

avocado.core.output module

Manages output and logging in avocado applications.

avocado.core.output.BUILTIN_STREAMS = {'app': 'application output', 'debug': 'tracebacks and other debugging info', 'early': 'early logging of other streams, including test (very verbose)', 'remote': 'fabric/paramiko debug', 'test': 'test output'}

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)

Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.

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)

Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.

avocado.core.output.LOG_JOB = <Logger avocado.test (WARNING)>

Pre-defined Avocado job/test logger

avocado.core.output.LOG_UI = <Logger avocado.app (WARNING)>

Pre-defined Avocado human UI logger

class avocado.core.output.LoggingFile(prefixes=None, level=10, loggers=None)

Bases: object

File-like object that will receive messages pass them to logging.

Constructor. Sets prefixes and which loggers are going to be used.

Parameters:
  • prefixes – Prefix per logger to be prefixed to each line.
  • level – Log level to be used when writing messages.
  • loggers – Loggers into which write should be issued. (list)
add_logger(logger, prefix='')
flush()
isatty()
rm_logger(logger)
write(data)

” Splits the line to individual lines and forwards them into loggers with expected prefixes. It includes the tailing newline <lf> as well as the last partial message. Do configure your logging to not to add newline <lf> automatically. :param data - Raw data (a string) 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)

Emit a record.

If a formatter is specified, it is used to format the record. The record is then written to the stream with a trailing newline. If exception information is present, it is formatted using traceback.print_exception and appended to the stream. If the stream has an ‘encoding’ attribute, it is used to determine how to do the output to the stream.

flush()

This is in-mem object, it does not require flushing

log = []
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)

Emit a record.

If a formatter is specified, it is used to format the record. The record is then written to the stream with a trailing newline. If exception information is present, it is formatted using traceback.print_exception and appended to the stream. If the stream has an ‘encoding’ attribute, it is used to determine how to do the output to the stream.

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

configured

Determines if a configuration of any sort has been performed

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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, 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 to logging.getLogger()
  • klass – Handler class (defaults to logging.StreamHandler)
  • stream – Logging stream, to be passed as an argument to klass (defaults to sys.stdout)
  • level – Log level (defaults to INFO`)
  • fmt – Logging format (defaults to %(name)s: %(message)s)
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.parameters module

Module related to test parameters

class avocado.core.parameters.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.parameters.AvocadoParams(leaves, paths, logger_name=None)

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.

Parameters:
  • leaves – List of TreeNode leaves defining current variant
  • paths – list of entry points
  • logger_name (str) – the name of a logger to use to record attempts to get parameters
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.

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’).
exception avocado.core.parameters.NoMatchError

Bases: KeyError

avocado.core.parser module

Avocado application command line parsing.

class avocado.core.parser.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)

Bases: argparse.ArgumentParser

Class to override argparse functions

error(message: string)

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

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 on attribute config.

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.parser_common_args module

avocado.core.parser_common_args.add_tag_filter_args(parser)

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

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

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, at avocado.core.job.Job.post_tests(). This is because JobPost 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, between avocado.core.job.Job.create_test_suite() and avocado.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

Base for all plugins

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

Bases: avocado.core.plugin_interfaces.Plugin

Base plugin to allow modifying settings.

Currently it only supports to extend/modify the default list of paths to config files.

adjust_settings_paths(paths)

Entry point where plugin can modify the list of configuration paths

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.

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

class avocado.core.runner.TestRunner(job, result)

Bases: object

A test runner class that displays tests results.

Creates an instance of TestRunner class.

Parameters:
DEFAULT_EXECUTION_ORDER = 'variants-per-test'

Mode in which this runner should iterate through tests and variants. The allowed values are “variants-per-test” or “tests-per-variant”

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 and variants. If not provided, will default to DEFAULT_EXECUTION_ORDER.
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.
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

class avocado.core.safeloader.PythonModule(path, module='avocado', klass='Test')

Bases: object

Representation of a Python module that might contain interesting classes

By default, it uses module and class names that matches Avocado instrumented tests, but it’s supposed to be agnostic enough to be used for, say, Python unittests.

Instantiates a new PythonModule representation

Parameters:
  • path (str) – path to a Python source code file
  • module (str) – the original module name from where the possibly interesting class must have been imported from
  • klass (str) – the possibly interesting class original name
add_imported_object(statement)

Keeps track of objects names and importable entities

imported_objects
is_matching_klass(klass)

Detect whether given class directly defines itself as <module>.<klass>

It can either be a <klass> that inherits from a test “symbol”, like:

`class FooTest(Test)`

Or from an <module>.<klass> symbol, like in:

`class FooTest(avocado.Test)`

Return type:bool
iter_classes()

Iterate through classes and keep track of imported avocado statements

klass
klass_imports
mod
mod_imports
module
path
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_avocado_tests(path)

Attempts to find Avocado instrumented tests from Python source files

Parameters:path (str) – path to a Python source code file
Returns:tuple where first item is dict with class name and additional info such as method names and tags; the second item is set of class names which look like avocado tests but are force-disabled.
Return type:tuple
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)
Returns:

an ordered dictionary with classes as keys and methods as values

Return type:

collections.OrderedDict

avocado.core.safeloader.find_python_unittests(path)

Attempts to find methods names from a given Python source file

This is a simpler, albeit more strict and correct, alternative version to find_class_and_methods(), in the sense that it checks for the (immediate) module name base class name.

Parameters:path (str) – path to a Python source code file
Returns:an ordered dictionary with classes as keys and methods as values
Return type:collections.OrderedDict
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
avocado.core.safeloader.get_docstring_directives_tags(docstring)

Returns the test categories based on a :avocado: tags=category docstring

Return type:dict
avocado.core.safeloader.get_methods_info(statement_body, class_tags)

Returns information on an Avocado instrumented test method

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 by ast.parse()
Returns:a mapping of names {<realname>: <alias>} of modules imported
Return type:dict
avocado.core.safeloader.statement_import_as(statement)

Returns a mapping of imported module names whether using aliases or not

Parameters:statement (ast.Import) – an AST import statement
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 (with Python’s 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=<class '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 and list.) – 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(path_)

Update list of config paths and process the given path

exception avocado.core.settings.SettingsError

Bases: 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.settings_dispatcher module

Settings Dispatcher

This is a special case for the dispatchers that can be found in avocado.core.dispatcher. This one deals with settings that will be read by the other dispatchers, while still being a dispatcher for configuration sources.

class avocado.core.settings_dispatcher.SettingsDispatcher

Bases: avocado.core.extension_manager.ExtensionManager

Dispatchers that allows plugins to modify settings

It’s not the standard “avocado.core.dispatcher” because that one depends on settings. This dispatcher is the bare-stevedore dispatcher which is executed before settings is parsed.

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_log – Whether 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(*args, **kwargs)

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_log – Whether 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 – Whether 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:argsargparse.Namespace object with command line params.

avocado.core.tags module

Test tags utilities module

avocado.core.tags.filter_test_tags(test_suite, filter_by_tags, include_empty=False, include_empty_key=False)

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
  • include_empty_key (bool) – if true tests “keys” on key:val tags will be included in the filtered results

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

Hook method for setting up the test fixture before exercising it.

class avocado.core.test.ExternalRunnerSpec(runner, chdir=None, test_dir=None)

Bases: object

Defines the basic options used by ExternalRunner

class avocado.core.test.ExternalRunnerTest(name, params=None, base_logdir=None, job=None, external_runner=None, external_runner_argument=None)

Bases: avocado.core.test.SimpleTest

filename

Returns the name of the file (path) that holds the current test

test()

Run the test and postprocess the results

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()
class avocado.core.test.PythonUnittest(name, params=None, base_logdir=None, job=None, test_dir=None, python_unittest_module=None, tags=None)

Bases: avocado.core.test.ExternalRunnerTest

Python unittest test

test()

Run the test and postprocess the results

class avocado.core.test.RawFileHandler(filename, mode='a', encoding=None, delay=False)

Bases: logging.FileHandler

File Handler that doesn’t include arbitrary characters to the logged stream but still respects the formatter.

Open the specified file and use it as the stream for logging.

emit(record)

Modifying the original emit() to avoid including a new line in streams that should be logged in its purest form, like in stdout/stderr recordings.

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()
class avocado.core.test.SimpleTest(name, params=None, base_logdir=None, job=None, executable=None)

Bases: avocado.core.test.Test

Run an arbitrary command that returns either 0 (PASS) or !=0 (FAIL).

DATA_SOURCES = ['variant', 'file']
filename

Returns the name of the file (path) that holds the current test

test()

Run the test and postprocess the results

avocado.core.test.TEST_STATE_ATTRIBUTES = ('name', 'logdir', 'logfile', 'status', 'running', 'paused', 'time_start', 'time_elapsed', 'time_end', 'fail_reason', 'fail_class', 'traceback', 'timeout', 'whiteboard', 'phase')

The list of test attributes that are used as the test state, which is given to the test runner via the queue they share

class avocado.core.test.Test(methodName='test', name=None, params=None, base_logdir=None, job=None, runner_queue=None, tags=None)

Bases: unittest.case.TestCase, avocado.core.test.TestData

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.TestID) – 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.
basedir

The directory where this test (when backed by a file) is located at

cache_dirs

Returns a list of cache directories as set in config file.

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
Warning message:
 This parameter will changed name to “msg” in the next LTS release because of lint W0221
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
Warning message:
 This parameter will changed name to “msg” in the next LTS release because of lint W0221
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
Warning message:
 This parameter will changed name to “msg” in the next LTS release because of lint W0221
fail_class
fail_reason
fetch_asset(name, asset_hash=None, algorithm=None, 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 avocado.utils.asset.DEFAULT_HASH_ALGORITHM)
  • 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

Returns the Test ID, which includes the test name

Return type:TestID
outputdir

Directory available to test writers to attach files to the results

params

Parameters of this test (AvocadoParam instance)

phase

The current phase of the test execution

Possible (string) values are: INIT, SETUP, TEST, TEARDOWN and FINISHED

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

status

The result status of this test

tags

The tags associated with 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

This property returns a writable directory that exists during the entire test execution, but will be cleaned up once the test finishes.

It can be used on tasks such as decompressing source tarballs, building software, etc.

class avocado.core.test.TestData

Bases: object

Class that adds the ability for tests to have access to data files

Writers of new test types can change the completely change the behavior and still be compatible by providing an DATA_SOURCES attribute and a meth:get_data method.

DATA_SOURCES = ['variant', 'test', 'file']

Defines the name of data sources that this implementation makes available. Users may choose to pick data file from a specific source.

get_data(filename, source=None, must_exist=True)

Retrieves the path to a given data file.

This implementation looks for data file in one of the sources defined by the DATA_SOURCES attribute.

Parameters:
  • filename (str) – the name of the data file to be retrieved
  • source (str) – one of the defined data sources. If not set, all of the DATA_SOURCES will be attempted in the order they are defined
  • must_exist (bool) – whether the existence of a file is checked for
Return type:

str or None

class avocado.core.test.TestError(*args, **kwargs)

Bases: avocado.core.test.Test

Generic test error.

test()
class avocado.core.test.TestID(uid, name, variant=None, no_digits=None)

Bases: object

Test ID construction and representation according to specification

This class wraps the representation of both Avocado’s Test ID specification and Avocado’s Test Name, which is part of a Test ID.

Constructs a TestID instance

Parameters:
  • uid – unique test id (within the job)
  • name – test name, as returned by the Avocado test resolver (AKA as test loader)
  • variant (dict) – the variant applied to this Test ID
  • no_digits – number of digits of the test uid
str_filesystem

Test ID in a format suitable for use in file systems

The string returned should be safe to be used as a file or directory name. This file system version of the test ID may have to shorten either the Test Name or the Variant ID.

The first component of a Test ID, the numeric unique test id, AKA “uid”, will be used as a an stable identifier between the Test ID and the file or directory created based on the return value of this method. If the filesystem can not even represent the “uid”, than an exception will be raised.

For Test ID “001-mytest;foo”, examples of shortened file system versions include “001-mytest;f” or “001-myte;foo”.

Raises:RuntimeError if the test ID cannot be converted to a filesystem representation.
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()

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:

http://pythonhosted.org/ete2/

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)

Add an element to a set.

This has no effect if the element is already present.

update(items)

Update a set with the union of itself and others.

class avocado.core.tree.TreeEnvironment

Bases: dict

TreeNode environment with values, origins and filters

copy() → a shallow copy of D
to_text(sort=False)

Human readable representation

Parameters:sort – Sorted to provide stable output
Return type:str
class avocado.core.tree.TreeNode(name='', value=None, parent=None, children=None)

Bases: object

Class for bounding nodes into tree-structure.

Parameters:
  • name (str) – a name for this node that will be used to define its path according to the name of its parents
  • value (dict) – a collection of keys and values that will be made into this node environment.
  • parent (TreeNode) – the node that is directly above this one in the tree structure
  • children (builtin.list) – the nodes that are directly beneath this one in the 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.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
fingerprint()
get_environment()
get_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

Base classes for implementing the varianter interface

class avocado.core.varianter.FakeVariantDispatcher(state)

Bases: object

This object can act instead of VarianterDispatcher to report loaded variants.

map_method_with_return(method, *args, **kwargs)

Reports list containing one result of map_method on self

to_str(summary=0, variants=0, **kwargs)
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 varianter
  • state – Force-varianter state
Note:

it’s necessary to check whether variants debug is enable 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:

[{'path': path,
  'variant_id': variant_id,
  'variant': dump_tree_nodes(original_variant)},
 {'path': [str, str, ...],
  'variant_id': str,
  'variant': [(str, [(str, str, object), ...])],
 {'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)
  • paths - 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

avocado.core.varianter.dump_ivariants(ivariants)

Walks the iterable variants and dumps them into json-serializable object

avocado.core.varianter.generate_variant_id(variant)

Basic function to generate variant-id from a variant

Parameters:variant – Avocado test variant (list of TreeNode-like objects)
Returns:String compounded of ordered node names and a hash of all values.
avocado.core.varianter.is_empty_variant(variant)

Reports whether the variant contains any data

Parameters:variant – Avocado test variant (list of TreeNode-like objects)
Returns:True when the variant does not contain (any useful) data
avocado.core.varianter.variant_to_str(variant, verbosity, out_args=None, debug=False)

Reports human readable representation of a variant

Parameters:
  • variant – Valid variant (list of TreeNode-like objects)
  • verbosity – Output verbosity where 0 means brief
  • out_args – Extra output arguments (currently unused)
  • debug – Whether the variant contains and should report debug info
Returns:

Human readable representation

avocado.core.version module

Module contents