Internal (Core) APIs

Internal APIs that may be of interest to Avocado hackers.

Everything under avocado.core is part of the application’s infrastructure and should not be used by tests.

Extensions and Plugins can use the core libraries, but API stability is not guaranteed at any level.

Subpackages

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.

This will be deprecated. Please use settings.as_dict() or self.config.

Warning

This method is deprecated, get values from settings.as_dict() or self.config

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

Warning

This method is deprecated, get values from settings.as_dict() or self.config

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_job_results_dir(job_ref, logs_dir=None)

Get the job results directory from a job reference.

Parameters

  • job_ref – job reference, which can be: * an valid path to the job results directory. In this case it is checked if ‘id’ file exists * the path to ‘id’ file * the job id, which can be ‘latest’ * an partial job id

  • logs_dir – path to base logs directory (optional), otherwise it uses the value from settings.

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.

Warning

This method is deprecated, get values from settings.as_dict() or self.config

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 from its source code 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.

Parameters

message (str) – the message given when the test is skipped

avocado.core.decorators.skipIf(condition, message=None)

Decorator to skip a test if a condition is True.

Parameters

  • condition (bool or callable) – a condition that will be evaluated as either True or False, if it’s a callable, it will be called with the class instance as a parameter

  • message (str) – the message given when the test is skipped

avocado.core.decorators.skipUnless(condition, message=None)

Decorator to skip a test if a condition is False.

Parameters

  • condition (bool or callable) – a condition that will be evaluated as either True or False, if it’s a callable, it will be called with the class instance as a parameter

  • message (str) – the message given when the test is skipped

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

Calls extensions on configure/run

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

class avocado.core.dispatcher.CacheDispatcher

Bases: EnabledExtensionManager

class avocado.core.dispatcher.InitDispatcher

Bases: EnabledExtensionManager

class avocado.core.dispatcher.JobPrePostDispatcher

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

class avocado.core.dispatcher.ResultEventsDispatcher(config)

Bases: EnabledExtensionManager

class avocado.core.dispatcher.RunnableRunnerDispatcher

Bases: EnabledExtensionManager

class avocado.core.dispatcher.SpawnerDispatcher(config=None, job=None)

Bases: EnabledExtensionManager

class avocado.core.dispatcher.SuiteRunnerDispatcher

Bases: EnabledExtensionManager

class avocado.core.dispatcher.TestPostDispatcher

Bases: EnabledExtensionManager

Calls extensions after Test execution

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

class avocado.core.dispatcher.TestPreDispatcher

Bases: EnabledExtensionManager

Calls extensions before Test execution

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

class avocado.core.dispatcher.VarianterDispatcher

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

It should never be raised directly.

exception avocado.core.exceptions.JobError

Bases: JobBaseException

A generic error happened during a job execution.

exception avocado.core.exceptions.JobFailFast

Bases: JobBaseException

Indicates that the test has failed because failfast is enabled.

Should be thrown when a test has failed and failfast is enabled. This will indicate that other tests will be skipped.

exception avocado.core.exceptions.JobTestSuiteDuplicateNameError

Bases: JobTestSuiteError

Error raised when a test suite name is not unique in a job

exception avocado.core.exceptions.JobTestSuiteEmptyError

Bases: JobTestSuiteError

Error raised when the creation of a test suite results in an empty suite

exception avocado.core.exceptions.JobTestSuiteError

Bases: JobBaseException

Generic error happened during the creation of a job’s test suite

exception avocado.core.exceptions.JobTestSuiteReferenceResolutionError

Bases: JobTestSuiteError

Test References did not produce a valid reference by any resolver

exception avocado.core.exceptions.OptionValidationError

Bases: Exception

An invalid option was passed to the test runner

exception avocado.core.exceptions.TestAbortError

Bases: 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: 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: 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: 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.TestSetupFail

Bases: TestBaseException

Indicates an error during a setup or cleanup procedure.

status = 'ERROR'
exception avocado.core.exceptions.TestSkipError

Bases: 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.TestWarn

Bases: 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.exit_codes.AVOCADO_WARNING = 22

Some internal avocado routine has not completed and probably it wasn’t at the JOB level. Usually this means that something it was skipped but it is safe to ignore.

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

get_extentions_by_name()

Returns extensions in alphabetical order

get_extentions_by_priority()

Returns extensions in execution order

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

class avocado.core.extension_manager.PluginPriority(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

HIGH = 70
LAST_RESORT = 0
LOW = 30
NORMAL = 50
VERY_HIGH = 100
VERY_LOW = 1

avocado.core.job module

Job module - describes a sequence of automated test operations.

class avocado.core.job.Job(config=None, test_suites=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.

A job has multiple test suites attached to it. Please keep in mind that when creating jobs from the constructor (Job()), we are assuming that you would like to have control of the test suites and you are going to build your own TestSuites.

If you would like any help to create the job’s test_suites from the config provided, please use Job.from_config() method and we are going to do our best to create the test suites.

So, basically, as described we have two “main ways” to create a job:

  1. Automatic discovery, using from_config() method:

    job = Job.from_config(job_config=job_config,
                      suites_configs=[suite_cfg1, suite_cfg2])

  2. Manual or Custom discovery, using the constructor:

    job = Job(config=config,
          test_suites=[suite1, suite2, suite3])

Creates an instance of Job class.

Note that config and test_suites are optional, if not passed you need to change this before running your tests. Otherwise nothing will run. If you need any help to create the test_suites from the config, then use the Job.from_config() method.

Parameters

  • config (dict) – the job configuration, usually set by command line options and argument parsing

  • test_suites (list) – A list with TestSuite objects. If is None the job will have an empty list and you can add suites after init accessing job.test_suites.

cleanup()

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

create_test_suite()
classmethod from_config(job_config, suites_configs=None)

Helper method to create a job from config dicts.

This is different from the Job() initialization because here we are assuming that you need some help to build the test suites. Avocado will try to resolve tests based on the configuration information instead of assuming pre populated test suites.

Keep in mind that here we are going to replace the suite.name with a counter.

If you need create a custom Job with your own TestSuites, please use the Job() constructor instead of this method.

Parameters

  • job_config (dict) – A config dict to be used on this job and also as a ‘global’ config for each test suite.

  • suites_configs (list) – A list of specific config dict to be used on each test suite. Each suite config will be merged with the job_config dict. If None is passed then this job will have only one test_suite with the same config as job_config.

get_failed_tests()

Gets the tests with status ‘FAIL’ and ‘ERROR’ after the Job ended.

Returns

List of failed tests

logdir

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.

render_results()

Render test results that depend on all tests having finished.

By default this runs the plugins that implement the avocado.core.plugin_interfaces.Result interface.

property result_events_dispatcher
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, …)

property size

Job size is the sum of all test suites sizes.

property test_results_path
property test_suite

This is the first test suite of this job (deprecated).

Please, use test_suites instead.

time_elapsed

The total amount of time the job took from start to finish, or None if it has not been started by means of the run() method

property timeout
property unique_id
avocado.core.job.register_job_options()

Register the few core options that the support the job operation.

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

Retrieves the variants path from the results directory.

avocado.core.jobdata.json_bad_variants_obj(item)
avocado.core.jobdata.record(job, cmdline=None)

Records all required job information.

avocado.core.jobdata.record_suite_variant(path_variants, suite)
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.main module

avocado.core.main.get_crash_dir()
avocado.core.main.handle_exception(*exc_info)
avocado.core.main.main()

avocado.core.messages module

class avocado.core.messages.BaseMessageHandler

Bases: object

Base interface for resolving runner messages.

This is the interface a job uses to deal with messages from runners.

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

process_message(message, task, job)

It transmits the message to the right handler.

Parameters

  • message (dict) – message from runner

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.BaseRunningMessageHandler

Bases: BaseMessageHandler

Base interface for resolving running messages.

class avocado.core.messages.FileMessageHandler

Bases: BaseRunningMessageHandler

Handler for file message.

In task directory will save log into the runner specific file. When the file doesn’t exist, the file will be created. If the file exist, the message data will be appended at the end.

Parameters

  • status – ‘running’

  • type – ‘file’

  • path (string) – relative path to the file. The file will be created under the Task directory and the absolute path will be created as absolute_task_directory_path/relative_file_path.

  • log (bytes) – data to be saved inside file

  • time (float) – Time stamp of the message

example: {‘status’: ‘running’, ‘type’: ‘file’, ‘path’:’foo/runner.log’,

‘log’: ‘this will be saved inside file’, ‘time’: 18405.55351474}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.FinishMessageHandler

Bases: BaseMessageHandler

Handler for finished message.

It will report the test status and triggers the ‘end_test’ event.

This is triggered when the runner ends the test.

Parameters

  • status – ‘finished’

  • result (avocado.core.teststatus.STATUSES) – test result

  • time (float) – end time of the test

  • fail_reason (string) – Parameter for brief specification, of the failed result. [Optional]

  • returncode (int) – Exit status of runner. [Optional]

  • class_name (string) – class name of the test. [Optional]

  • returncode – Exit status of runner. [Optional]

  • fail_class (string) – Exception class of the failure. [Optional]

  • traceback (string) – Traceback of the exception. [Optional]

example: {‘status’: ‘finished’, ‘result’: ‘pass’, ‘time’: 16444.819830573}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.LogMessageHandler

Bases: BaseRunningMessageHandler

Handler for log message.

It will save the log to the debug.log file in the task directory.

Parameters

  • status – ‘running’

  • type – ‘log’

  • log (string) – log message

  • time (float) – Time stamp of the message

  • log_name (string) – optional name of the logger, such as “avocado.test.foo”

  • log_levelname (string) – level of the logger, such as “INFO”, required if “log_name” is set

  • log_message (string) – message formatted as message only (no name, level or timestamp), require if “log_name” is set

example: {‘status’: ‘running’, ‘type’: ‘log’, ‘log’: ‘log message’,

‘time’: 18405.55351474}

or:

example: {‘status’: ‘running’, ‘type’: ‘log’, ‘log’: ‘log message’,

‘time’: 18405.55351474, ‘log_name’: ‘avocado.test.foo’, ‘log_levelname’: ‘INFO’, ‘log_message’: ‘foo content’}

handle(message, task, job)

Logs a textual message to a file.

This assumes that the log message will not contain a newline, and thus one is explicitly added here.

class avocado.core.messages.MessageHandler

Bases: BaseMessageHandler

Entry point for handling messages.

process_message(message, task, job)

It transmits the message to the right handler.

Parameters

  • message (dict) – message from runner

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.OutputMessageHandler

Bases: BaseRunningMessageHandler

Handler for displaying messages in UI.

It will show the message content in avocado UI.

Parameters

  • status – ‘running’

  • type – ‘output’

  • log (bytes) – output message

  • encoding (str) – optional value for decoding messages

  • time (float) – Time stamp of the message

example: {‘status’: ‘running’, ‘type’: ‘output’,

‘log’: ‘this is the output’, ‘time’: 18405.55351474}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.RunningMessageHandler

Bases: BaseMessageHandler

Entry point for handling running messages.

process_message(message, task, job)

It transmits the message to the right handler.

Parameters

  • message (dict) – message from runner

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.StartMessageHandler

Bases: BaseMessageHandler

Handler for started message.

It will create the test base directories and triggers the ‘start_test’ event.

This have to be triggered when the runner starts the test.

Parameters

  • status – ‘started’

  • time (float) – start time of the test

example: {‘status’: ‘started’, ‘time’: 16444.819830573}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

static prepare_metadata(task, job, start_time)

Creates metadata for task.

Parameters

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

  • start_time (float) – time when the task started

class avocado.core.messages.StderrMessageHandler

Bases: BaseRunningMessageHandler

Handler for stderr message.

It will save the stderr to the debug file in the task directory, and optionally (depending on “log_only” value) to the stderr file.

Parameters

  • status – ‘running’

  • type – ‘stderr’

  • log (bytes) – stderr message

  • log_only (bool) – whether to save the “log” message only to the standard test log (and not to the “stderr” file)

  • encoding (str) – optional value for decoding messages

  • time (float) – Time stamp of the message

example: {‘status’: ‘running’, ‘type’: ‘stderr’, ‘log’: ‘stderr message’,

‘log_only’: False, ‘time’: 18405.55351474}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.StdoutMessageHandler

Bases: BaseRunningMessageHandler

Handler for stdout message.

It will save the stdout to the debug file in the task directory, and optionally (depending on “log_only” value) to the stdout file.

Parameters

  • status – ‘running’

  • type – ‘stdout’

  • log (bytes) – stdout message

  • log_only (bool) – whether to save the “log” message only to the standard test log (and not to the “stdout” file)

  • encoding (str) – optional value for decoding messages

  • time (float) – Time stamp of the message

example: {‘status’: ‘running’, ‘type’: ‘stdout’, ‘log’: ‘stdout message’,

‘log_only’: False, ‘time’: 18405.55351474}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

class avocado.core.messages.WhiteboardMessageHandler

Bases: BaseRunningMessageHandler

Handler for whiteboard message.

It will save the stderr to the whiteboard file in the task directory.

Parameters

  • status – ‘running’

  • type – ‘whiteboard’

  • log (bytes) – whiteboard message

  • encoding (str) – optional value for decoding messages

  • time (float) – Time stamp of the message

example: {‘status’: ‘running’, ‘type’: ‘whiteboard’,

‘log’: ‘whiteboard message’, ‘time’: 18405.55351474}

handle(message, task, job)

Handle message from runner.

Parameters

  • message (dict) – message from runner.

  • task (avocado.core.nrunner.Task) – runtime_task which message is related to

  • job (avocado.core.job.Job) – job which task is related to

avocado.core.output module

Manages output and logging in avocado applications.

class avocado.core.output.FilterInfoAndLess(name='')

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

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

class avocado.core.output.FilterWarnAndMore(name='')

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

Returns True if the record should be logged, or False otherwise. 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()
static 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: 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: 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

property 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

avocado.core.output.TEST_STATUS_DECORATOR_MAPPING = {'CANCEL': <bound method TermSupport.skip_str of <avocado.core.output.TermSupport object>>, 'ERROR': <bound method TermSupport.error_str of <avocado.core.output.TermSupport object>>, 'FAIL': <bound method TermSupport.fail_str of <avocado.core.output.TermSupport object>>, 'INTERRUPTED': <bound method TermSupport.interrupt_str of <avocado.core.output.TermSupport object>>, 'PASS': <bound method TermSupport.pass_str of <avocado.core.output.TermSupport object>>, 'SKIP': <bound method TermSupport.skip_str of <avocado.core.output.TermSupport object>>, 'WARN': <bound method TermSupport.warn_str of <avocado.core.output.TermSupport object>>}

A collection of mapping from test status to formatting functions to be used consistently across the various plugins

avocado.core.output.TEST_STATUS_MAPPING = {'CANCEL': '', 'ERROR': '', 'FAIL': '', 'INTERRUPTED': '', 'PASS': '', 'SKIP': '', 'WARN': ''}

A collection of mapping from test statuses to colors to be used consistently across the various plugins

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(msg='ERROR', move='\x1b[1D')

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(msg='FAIL', move='\x1b[1D')

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(msg='INTERRUPT', move='\x1b[1D')

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(msg='PASS', move='\x1b[1D')

Print a pass string (green colored).

If the output does not support colors, just return the original string.

skip_str(msg='SKIP', move='\x1b[1D')

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(msg='WARN', move='\x1b[1D')

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

property 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, exit_on_error=True)

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

Controls claiming the right to write to the application standard output

class avocado.core.parser.HintParser(filename)

Bases: object

get_resolutions()

Return a list of resolutions based on the file definitions.

validate_kind_section(kind)

Validates a specific “kind section”.

This method will raise a settings.SettingsError if any problem is found on the file.

Parameters

kind – a string with the specific section.

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

abstract configure(parser)

Configures the command line parser with options specific to this plugin.

abstract 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: 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
abstract run(config)

Entry point for actually running the command.

class avocado.core.plugin_interfaces.Cache

Bases: Plugin

Plugin for manipulating with cache metadata interface

abstract clear()

Clear all cache entries

It removes every cache entire.

abstract list()

List all cache entries

Creates list of cache entries which represents current cache state.

Returns

Human-readable list of entries which will be printed to console.

Return type

str

class avocado.core.plugin_interfaces.DeploymentSpawner

Bases: Spawner

Spawners that needs basic deployment are based on this class.

Spawners that uses any type of isolation model would be a possible children of this.

abstract async deploy_artifacts()

Basic artifacts deployment for the isolated environment.

During this stage test references (i.e: mytest.py), data files (i.e: mytest.py.data/), and any other basic requirement should be deployed to the isolated environment. Please keep in mind that test requirements defined at the requirements resolver level are not part of this deployment and it will be fulfilled by the requirement resolver.

This method should also be executed before spawning the task.

abstract async deploy_avocado(where)

Avocado deployment for the isolated environment.

This method should be executed before spawning the task.

Parameters

where – handle for where the spawner should deploy avocado. You can use this parameter to pass any valid argument, like a container, vm, or any other isolated environment object or identifier.

class avocado.core.plugin_interfaces.Discoverer(config=None)

Bases: Plugin, ResolverMixin

Base plugin interface for discovering tests without reference.

abstract discover()

Discovers a test resolutions

It will be used when the test.references variable is empty, but the discoverer will be able to use another data for gathering test resolutions. It work same as the Resolver, but without the test reference.

Returns

the result of the resolution process, containing the success, failure or error, along with zero or more avocado.core.nrunner.Runnable objects

Return type

avocado.core.resolver.ReferenceResolution

class avocado.core.plugin_interfaces.Init

Bases: Plugin

Base plugin interface for plugins that needs to initialize itself.

abstract initialize()

Entry point for the plugin to perform its initialization.

class avocado.core.plugin_interfaces.JobPost

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

abstract post(job)

Entry point for actually running the post job action.

class avocado.core.plugin_interfaces.JobPostTests

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

abstract post_tests(job)

Entry point for job running actions after the tests execution.

class avocado.core.plugin_interfaces.JobPre

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

abstract pre(job)

Entry point for actually running the pre job action.

class avocado.core.plugin_interfaces.JobPreTests

Bases: 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().

abstract pre_tests(job)

Entry point for job running actions before tests execution.

class avocado.core.plugin_interfaces.Plugin

Bases: ABC

Base for all plugins.

class avocado.core.plugin_interfaces.PostTest

Bases: Plugin

Base plugin interface for adding tasks after a test run.

This interface helps to create avocado.core.nrunner.Task for running additional actions inside spawner environment after Test.

abstract post_test_runnables(test_runnable, suite_config=None)

Entry point for creating runnables, which will be run after test.

Parameters

  • test_runnable – Runnable of the Test itself.

  • suite_config – Configuration dict relevant for the whole suite.

Returns

PostTest task runnables created by plugin.

Return type

list of tuple(avocado.core.nrunner.Runnable,

avocado.core.task.runtime.RuntimeTask.possible_dependency_results)

class avocado.core.plugin_interfaces.PreTest

Bases: Plugin

Base plugin interface for adding tasks before a test run.

This interface helps to create avocado.core.nrunner.Task for running additional actions inside spawner environment before Test.

abstract pre_test_runnables(test_runnable, suite_config=None)

Entry point for creating runnables, which will be run before test.

Parameters

  • test_runnable – Runnable of the Test itself.

  • suite_config – Configuration dict relevant for the whole suite.

Returns

PreTest task runnables created by plugin.

Return type

list of avocado.core.nrunner.Runnable

class avocado.core.plugin_interfaces.Resolver(config=None)

Bases: Plugin, ResolverMixin

Base plugin interface for resolving test references into resolutions.

abstract resolve(reference)

Resolves the given reference into a reference resolution.

Parameters

reference (str) – a specification that can eventually be resolved into a test (in the form of a avocado.core.nrunner.Runnable)

Returns

the result of the resolution process, containing the success, failure or error, along with zero or more avocado.core.nrunner.Runnable objects

Return type

avocado.core.resolver.ReferenceResolution

class avocado.core.plugin_interfaces.ResolverMixin(config=None)

Bases: object

Common utilities for Resolver implementations.

class avocado.core.plugin_interfaces.Result

Bases: Plugin

abstract 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: JobPreTests, 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.

abstract end_test(result, state)

Event triggered when a test finishes running.

abstract start_test(result, state)

Event triggered when a test starts running.

abstract test_progress(progress=False)

Interface to notify progress (or not) of the running test.

class avocado.core.plugin_interfaces.RunnableRunner

Bases: Plugin

Base interface for a nrunner Runner.

abstract run(runnable)

Runner main method

Yields dictionary as output, containing status as well as relevant information concerning the results.

Parameters

runnable (avocado.core.nrunner.Runnable) – a Runnable instance that describes what is to be run

class avocado.core.plugin_interfaces.Settings

Bases: Plugin

Base plugin to allow modifying settings.

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

abstract adjust_settings_paths(paths)

Entry point where plugin can modify the list of configuration paths.

class avocado.core.plugin_interfaces.Spawner

Bases: Plugin

Base plugin interface spawners of tasks.

A spawner implementation will spawn Avocado in its intended location, and isolation model. Spawners that run on the same machine as Avocado is originally installed are possible children of this.

abstract async static check_task_requirements(runtime_task)

Checks if the requirements described within a task are available.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – wrapper for a Task with additional runtime information.

create_task_output_dir(runtime_task)

Creates output directory in the intended location, before the task spawn.

The output directory path will be saved to the task.runnable.config for the usage by runners.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – wrapper for a Task with additional runtime information.

abstract async static is_requirement_in_cache(runtime_task)

Checks if it’s necessary to run the requirement.

There are occasions when the similar requirement has been run and its results are already saved in cache. In such occasion, it is not necessary to run the task again. For example, this might be useful for tasks which would install the same package to the same environment.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – runtime task with requirement

Returns

If the results are already in cache.

Return type

True if task is in cache False if task is not in cache None if task is running in different process and should be in cache soon.

abstract static is_task_alive(runtime_task)

Determines if a task is alive or not.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – wrapper for a Task with additional runtime information.

abstract async static save_requirement_in_cache(runtime_task)

Saves the information about requirement in cache before the runtime_task is run.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – runtime task with requirement

abstract async spawn_task(runtime_task)

Spawns a task return whether the spawning was successful.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – wrapper for a Task with additional runtime information.

abstract async terminate_task(runtime_task)

Terminates a task before finish.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – wrapper for a Task with additional runtime information.

abstract async static update_requirement_cache(runtime_task, result)

Updates the information about requirement in cache based on result.

Parameters
abstract async wait_task(runtime_task)

Waits for a task to finish.

Parameters

runtime_task (avocado.core.task.runtime.RuntimeTask) – wrapper for a Task with additional runtime information.

class avocado.core.plugin_interfaces.SuiteRunner

Bases: Plugin

Base plugin interface for runners for suites.

This is the interface a job uses to drive the tests execution in a suite.

NOTE: This interface is not to be confused with the internal interface or idiosyncrasies of the The “nrunner” test runner.

abstract run_suite(job, test_suite)

Run one or more tests and report with test result.

Parameters

  • job – an instance of avocado.core.job.Job.

  • test_suite – an instance of TestSuite with some tests to run.

Returns

a set with types of test failures.

class avocado.core.plugin_interfaces.Varianter

Bases: Plugin

Base plugin interface for producing test variants.

abstract 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

avocado.core.references module

Test loader module.

avocado.core.references.reference_split(reference)

Splits a test reference into a path and additional info

This should be used dependent on the specific type of resolver. If a resolver is not expected to support multiple test references inside a given file, then this is not suitable.

Returns

(path, additional_info)

Type

(str, str or None)

avocado.core.resolver module

Test resolver module.

class avocado.core.resolver.Discoverer(config=None)

Bases: EnabledExtensionManager

Secondary test reference resolution utility.

When the user didn’t provide any test references, Discoverer will discover tests from different data according to active discoverer plugins.

discover()
class avocado.core.resolver.ReferenceResolution(reference, result, resolutions=None, info=None, origin=None)

Bases: object

Represents one complete reference resolution

Note that the reference itself may result in many resolutions, or none.

Parameters

  • reference (str) – a specification that can eventually be resolved into a test (in the form of a avocado.core.nrunner.Runnable)

  • result (ReferenceResolutionResult) – if the complete resolution was a success, failure or error

  • resolutions (list of avocado.core.nrunner.Runnable) – the runnable definitions resulting from the resolution

  • info (str) – free form information the resolver may add

  • origin (str) – the name of the resolver that performed the resolution

class avocado.core.resolver.ReferenceResolutionAction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CONTINUE = <object object>

Continue to resolve the given reference

RETURN = <object object>

Stop trying to resolve the reference

class avocado.core.resolver.ReferenceResolutionAssetType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

DATA_FILE = 'data_file'

Auxiliary data file placed alongside the test in a “.data” directory

TEST_FILE = 'test_file'

The actual test file. Spawners may use this as the entry point to run the tests. Usually only one of this is given, and the behavior with either a single or multiple items given is spawner dependent.

class avocado.core.resolver.ReferenceResolutionResult(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

ERROR = <object object>

Internal error in the resolution process

NOTFOUND = <object object>

Given test reference was not properly resolved

SUCCESS = <object object>

Given test reference was properly resolved

class avocado.core.resolver.Resolver(config=None)

Bases: EnabledExtensionManager

Main test reference resolution utility.

This performs the actual resolution according to the active resolver plugins and a resolution policy.

DEFAULT_POLICY = {<ReferenceResolutionResult.SUCCESS: <object object>>: <ReferenceResolutionAction.RETURN: <object object>>, <ReferenceResolutionResult.NOTFOUND: <object object>>: <ReferenceResolutionAction.CONTINUE: <object object>>, <ReferenceResolutionResult.ERROR: <object object>>: <ReferenceResolutionAction.CONTINUE: <object object>>}
resolve(reference)
avocado.core.resolver.check_file(path, reference, suffix='.py', type_check=<function isfile>, type_name='regular file', access_check=4, access_name='readable')
avocado.core.resolver.get_file_assets(test_file_path)

Gets asset files from the test file and its the “.data” directory

Parameters

test_file_path (str) – the filesystem location of the test file

Returns

list of tuples with (asset type, path)

avocado.core.resolver.resolve(references, hint=None, ignore_missing=True, config=None)

avocado.core.result module

Contains the Result class, used for result accounting.

class avocado.core.result.Result(job_unique_id, job_logfile, job_start_date_time=None)

Bases: object

Result class, holder for job (and its tests) result information.

Creates an instance of Result.

Parameters

  • job_unique_id – the job’s unique ID, usually from avocado.core.job.Job.unique_id

  • job_logfile – the job’s unique ID, usually from avocado.core.job.Job.logfile

  • job_start_date_time – the date and time a job started running

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.

property 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.settings module

This module is a new and experimental configuration handler.

This will handle both, command line args and configuration files. Settings() = configparser + argparser

Settings() is an attempt to implement part of BP001 and concentrate all default values in one place. This module will read the Avocado configuration options from many sources, in the following order:

  1. Default values: This is a “source code” defined. When plugins or core needs a settings, basically needs to call settings.register_option() with default value as argument. Developers only need to register the default value once, here when calling this methods.

  2. User/System configuration files (/etc/avocado or ~/.avocado/): This is configured by the user, on a more “permanent way”.

  3. Command-line options parsed in runtime. This is configured by the user, on a more “temporary way”;

exception avocado.core.settings.ConfigFileNotFound(path_list)

Bases: SettingsError

Error thrown when the main settings file could not be found.

class avocado.core.settings.ConfigOption(namespace, help_msg, key_type=<class 'str'>, default=None, parser=None, short_arg=None, long_arg=None, positional_arg=False, choices=None, nargs=None, metavar=None, required=None, action=None, argparse_type=None, argparse_help_msg=None)

Bases: object

property action
add_argparser(parser, long_arg, short_arg=None, positional_arg=False, choices=None, nargs=None, metavar=None, required=None, action=None, argparse_type=None, argparse_help_msg=None)

Add an command-line argparser to this option.

property arg_parse_args
property argparse_help_msg
property argparse_type
property key
property metavar
property name_or_tags
property section
set_value(value, convert=False)
property value
exception avocado.core.settings.DuplicatedNamespace

Bases: SettingsError

Raised when a namespace is already registered.

exception avocado.core.settings.NamespaceNotRegistered

Bases: SettingsError

Raised when a namespace is not registered.

class avocado.core.settings.Settings

Bases: object

Settings is the Avocado configuration handler.

It is a simple wrapper around configparser and argparse.

Also, one object of this class could be passed as config to plugins and modules.

Basically, if you are going to have options (configuration options), either via config file or via command line, you should use this class. You don’t need to instantiate a new settings, just import and use register_option().

from avocado.core.settings import settings settings.register_option(…)

And when you needs get the current value, check on your configuration for the namespace (section.key) that you registered. i.e:

value = config.get(‘a.section.with.subsections.key’)

Note

Please, do not use a default value when using get() here. If you are using an existing namespace, get will always return a value, either the default value, or the value set by the user.

Please, note that most of methods and attributes here are private. Only public methods and attributes should be used outside this module.

Constructor. Tries to find the main settings files and load them.

add_argparser_to_option(namespace, parser, long_arg=None, short_arg=None, positional_arg=False, choices=None, nargs=None, metavar=None, required=None, action=None, allow_multiple=False, argparse_type=None, help_msg=None)

Add a command-line argument parser to an existing option.

This method is useful to add a parser when the option is registered without any command-line argument options. You should call the “register_option()” method for the namespace before calling this method.

Arguments

namespacestr

What is the namespace of the option (section.key)

parserargparser parser

Since that you would like to have a command-line option, you should specify what is the parser or parser group that we should add this option.

long_arg:str

A long option for the command-line. i.e: –debug for debug.

short_argstr

A short option for the command-line. i.e: -d for debug.

positional_argbool

If this option is an positional argument or not. Default is False.

choicestuple

If you would like to limit the option to a few choices. i.e: (‘foo’, ‘bar’)

nargsint or str

The number of command-line arguments that should be consumed. Could be a int, ‘?’, ‘*’ or ‘+’. For more information visit the argparser documentation.

metavarstr

String presenting available sub-commands in help, if None we will use the section+key as metavar.

requiredbool

If this is a required option or not when on command-line. Default is False.

action :

The basic type of action to be taken when this argument is encountered at the command line. For more information visit the argparser documentation.

allow_multiple :

Whether the same option may be available on different parsers. This is useful when the same option is available on different commands, such as “avocado run” or “avocado list”.

argparse_type :

A possibly different type for the command line handling of an option. For instance, when an option has a “key_type” of “list”, its respective configuration file entry will expect a string that can be evaluated to a Python list, but that is far from convenient to set on the command line. With this argument, a function that will, for instance, split a comma separated list may be used, resulting in command line users being able to provide convenient input.

help_msgstr

A help message, different from the original ConfigOption help message, to be shown on the command line. To be used when the command line usage and the original help message do not make sense together.

as_dict(regex=None)

Return an dictionary with the current active settings.

This will return a dict with all parsed options (either via config file or via command-line). If regex is not None, this method will filter the current config matching regex with the namespaces.

Parameters

regex – A regular expression to be used on the filter.

as_full_dict()
as_json(regex=None)

Return a JSON with the current active settings.

This will return a JSON with all parsed options (either via config file or via command-line). If regex is not None, it will be used to filter namespaces.

Parameters

regex – A regular expression to be used on the filter.

static filter_config(config, regex)

Utility to filter a config by namespaces based on a regex.

Parameters

  • config – dict object with namespaces and values

  • regex – regular expression to use against the namespace

merge_with_arguments(arg_parse_config)

Merge the current settings with the command-line args.

After parsing argument options this method should be executed to have an unified settings.

Parameters

arg_parse_config – argparse.config dictionary with all command-line parsed arguments.

merge_with_configs()

Merge the current settings with the config file options.

After parsing config file options this method should be executed to have an unified settings.

process_config_path(path)

Update list of config paths and process the given path.

register_option(section, key, default, help_msg, key_type=<class 'str'>, parser=None, positional_arg=False, short_arg=None, long_arg=None, choices=None, nargs=None, metavar=None, required=False, action=None, allow_multiple=False)

Method used to register a configuration option inside Avocado.

This should be used to register a settings option (either config file option or command-line option). This is the central point that plugins and core should use to register a new configuration option.

This method will take care of the ‘under the hood dirt’, registering the configparse option and, if desired, the argparse too. Instead of using argparse and/or configparser, Avocado’s contributors should use this method.

Using this method, you need to specify a “section”, “key”, “default” value and a “help_msg” always. This will create a relative configuration file option for you.

For instance:

settings.register_option(section=’foo’, key=’bar’, default=’hello’,

help_msg=’this is just a test’)

This will register a ‘foo.bar’ namespace inside Avocado internals settings. And this could be now, be changed by the users or system configuration option:

[foo] bar = a different message replacing ‘hello’

If you would like to provide also the flexibility to the user change the values via command-line, you should pass the other arguments.

Arguments

sectionstr

The configuration file section that your option should be present. You can specify subsections with dots. i.e: run.output.json

keystr

What is the key name of your option inside that section.

defaulttypeof(key_type)

The default value of an option. It sets the option value when the key is not defined in any configuration files or via command-line. The default value should be “processed”. It means the value should match the type of key_type. Due to some internal limitations, the Settings module will not apply key_type to the default value.

help_msgstr

The help message that will be displayed at command-line (-h) and configuration file template.

key_typeany method

What is the type of your option? Currently supported: int, list, str or a custom method. Default is str.

parserargparser parser

Since that you would like to have a command-line option, you should specify what is the parser or parser group that we should add this option.

positional_argbool

If this option is an positional argument or not. Default is False.

short_argstr

A short option for the command-line. i.e: -d for debug.

long_arg:str

A long option for the command-line. i.e: –debug for debug.

choicestuple

If you would like to limit the option to a few choices. i.e: (‘foo’, ‘bar’)

nargsint or str

The number of command-line arguments that should be consumed. Could be a int, ‘?’, ‘*’ or ‘+’. For more information visit the argparser documentation.

metavarstr

String presenting available sub-commands in help, if None we will use the section+key as metavar.

requiredbool

If this is a required option or not when on command-line. Default is False.

action :

The basic type of action to be taken when this argument is encountered at the command line. For more information visit the argparser documentation.

allow_multiple :

Whether the same option may be available on different parsers. This is useful when the same option is available on different commands, such as “avocado run” or “avocado list”.

Note

Most of the arguments here (like parser, positional_arg, short_arg, long_arg, choices, nargs, metavar, required and action) are only necessary if you would like to add a command-line option.

update_option(namespace, value, convert=False)

Convenient method to change the option’s value.

This will update the value on Avocado internals and if necessary the type conversion will be realized.

For instance, if an option was registered as bool and you call:

settings.register_option(namespace=’foo.bar’, value=’true’,

convert=True)

This will be stored as True, because Avocado will get the ‘key_type’ registered and apply here for the conversion.

This method is useful when getting values from config files where everything is stored as string and a conversion is needed.

Arguments

namespacestr

Your section plus your key, separated by dots. The last part of the namespace is your key. i.e: run.outputs.json.enabled (section is run.outputs.json and key is enabled)

valueany type

This is the new value to update.

convertbool

If Avocado should try to convert the value and store it as the ‘key_type’ specified during the register. Default is False.

exception avocado.core.settings.SettingsError

Bases: Exception

Base settings error.

avocado.core.settings.sorted_dict(dict_object)

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: 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.streams module

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

Builtin special keywords to enable set of logging streams

avocado.core.streams.BUILTIN_STREAM_SETS = {'all': 'all builtin streams', 'none': 'disables regular output (leaving only errors enabled)'}

Groups of builtin streams

avocado.core.suite module

class avocado.core.suite.TestSuite(name, config=None, tests=None, job_config=None, resolutions=None, enabled=True)

Bases: object

classmethod from_config(config, name=None, job_config=None)

Helper method to create a TestSuite from config dicts.

This is different from the TestSuite() initialization because here we are assuming that you need some help to build the test suite. Avocado will try to resolve tests based on the configuration information instead of assuming pre populated tests.

If you need to create a custom TestSuite, please use the TestSuite() constructor instead of this method.

Parameters

  • config (dict) – A config dict to be used on the desired test suite.

  • name (str) – The name of the test suite. This is optional and default is a random uuid.

  • job_config (dict) – The job config dict (a global config). Use this to avoid huge configs per test suite. This is also optional.

get_test_variants()

Computes test variants based on the parameters

property references
run(job)

Run this test suite with the job context in mind.

Parameters

job – A avocado.core.job.Job instance.

Return type

set

property runner
property size

The overall length/size of this test suite.

property stats

Return a statistics dict with the current tests.

property status
property tags_stats

Return a statistics dict with the current tests tags.

property test_parameters

Placeholder for test parameters.

This is related to –test-parameters command line option or (run.test_parameters).

property variants
exception avocado.core.suite.TestSuiteError

Bases: Exception

class avocado.core.suite.TestSuiteStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

RESOLUTION_NOT_STARTED = <object object>
TESTS_FOUND = <object object>
TESTS_NOT_FOUND = <object object>
UNKNOWN = <object object>
avocado.core.suite.resolutions_to_runnables(resolutions, config)

Transforms resolver resolutions into runnables suitable for a suite

A resolver resolution (avocado.core.resolver.ReferenceResolution) contains information about the resolution process (if it was successful or not) and in case of successful resolutions a list of resolutions. It’s expected that the resolution contain one or more avocado.core.nrunner.Runnable.

This function sets the runnable specific configuration for each runnable. It also performs tag based filtering on the runnables for possibly excluding some of the Runnables.

Parameters
Returns

the resolutions converted to runnables

Return type

list of avocado.core.nrunner.Runnable

avocado.core.sysinfo module

class avocado.core.sysinfo.SysInfo(basedir=None, log_packages=None, profiler=None)

Bases: object

Log different system properties at some key control points.

Includes support for a start and stop event, with daemons running in between. An event may be a job, a test, or any other event with a beginning and end.

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.

end(status='')

Logging hook called whenever a job finishes.

start()

Log all collectibles at the start of the event.

avocado.core.sysinfo.collect_sysinfo(basedir)

Collect sysinfo to a base directory.

avocado.core.sysinfo.gather_collectibles_config(config)

avocado.core.tags module

Test tags utilities module

avocado.core.tags.filter_tags_on_runnables(resolutions, filter_by_tags, include_empty=False, include_empty_key=False)

Filters out runnables that do not match the tags criteria given

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

  • resolutions (list of avocado.core.resolver.ReferenceResolution) – possible multiple resolutions for multiple references

  • 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

Returns

the resolutions converted to runnables filtered by tags

Return type

list of avocado.core.nrunner.Runnable

avocado.core.tapparser module

class avocado.core.tapparser.TapParser(tap_io)

Bases: object

class Bailout(message)

Bases: tuple

Create new instance of Bailout(message,)

message

Alias for field number 0

class Error(message)

Bases: tuple

Create new instance of Error(message,)

message

Alias for field number 0

class Plan(count, late, skipped, explanation)

Bases: tuple

Create new instance of Plan(count, late, skipped, explanation)

count

Alias for field number 0

explanation

Alias for field number 3

late

Alias for field number 1

skipped

Alias for field number 2

class Test(number, name, result, explanation)

Bases: tuple

Create new instance of Test(number, name, result, explanation)

explanation

Alias for field number 3

name

Alias for field number 1

number

Alias for field number 0

result

Alias for field number 2

class Version(version)

Bases: tuple

Create new instance of Version(version,)

version

Alias for field number 0

parse()
parse_test(ok, num, name, directive, explanation)
class avocado.core.tapparser.TestResult(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

FAIL = 'FAIL'
PASS = 'PASS'
SKIP = 'SKIP'
XFAIL = 'XFAIL'
XPASS = 'XPASS'

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)

avocado.core.test.TEST_STATE_ATTRIBUTES = ('name', 'logdir', 'logfile', 'status', 'running', 'paused', 'time_start', 'time_elapsed', 'time_end', 'actual_time_start', 'actual_time_end', 'fail_reason', 'fail_class', 'traceback', 'tags', '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, config=None, runner_queue=None, tags=None)

Bases: TestCase, 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 a temporary directory will be created.

  • config (dict) – the job configuration, usually set by command line options and argument parsing

actual_time_end = -1

(unix) time when the test finished, actual one to be shown to users

actual_time_start = -1

(unix) time when the test started, actual one to be shown to users

property basedir

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

property cache_dirs

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

static cancel(msg=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

msg (str) – an optional message that will be recorded in the logs

static error(msg=None)

Errors the currently running test.

After calling this method a test will be terminated and have its status as ERROR.

Parameters

msg (str) – an optional message that will be recorded in the logs

static fail(msg=None)

Fails the currently running test.

After calling this method a test will be terminated and have its status as FAIL.

Parameters

msg (str) – an optional message that will be recorded in the logs

property fail_class
property fail_reason
fetch_asset(name, asset_hash=None, algorithm=None, locations=None, expire=None, find_only=False, cancel_on_missing=False)

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

  • find_only – When True, fetch_asset only looks for the asset in the cache, avoiding the download/move action. Defaults to False.

  • cancel_on_missing – whether the test should be canceled if the asset was not found in the cache or if fetch could not add the asset to the cache. Defaults to False.

Raises

OSError – when it fails to fetch the asset or file is not in the cache and cancel_on_missing is False.

Returns

asset file local path.

property 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

property log

The enhanced test log

property logdir

Path to this test’s logging dir

property logfile

Path to this test’s main debug.log file

property name

Returns the Test ID, which includes the test name

Return type

TestID

property outputdir

Directory available to test writers to attach files to the results

property params

Parameters of this test (AvocadoParam instance)

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

property runner_queue

The communication channel between test and test runner

property running

Whether this test is currently being executed

set_runner_queue(runner_queue)

Override the runner_queue

property status

The result status of this test

property tags

The tags associated with this test

tearDown()

Hook method for deconstructing the test fixture after testing it.

property 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, monotonic (could be forced from test)

time_start = -1

(unix) time when the test started, monotonic (could be forced from test)

timeout = None

Test timeout (the timeout from params takes precedence)

property traceback
whiteboard = ''

Arbitrary string which will be stored in $logdir/whiteboard location when the test finishes.

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

SUFFIX = '.data'

The name of data directory associated with a file name is expected to match the file name, plus this suffix.

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

avocado.core.test_id module

class avocado.core.test_id.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

  • variant (dict) – the variant applied to this Test ID

  • no_digits – number of digits of the test uid

classmethod from_identifier(identifier)

It wraps an identifier by the TestID class.

Parameters

identifier – Any identifier that is guaranteed to be unique within the context of an avocado Job.

Returns

TestID with uid as string representation of identifier and name “test”.

Return type

avocado.core.test_id.TestID

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

avocado.core.teststatus module

Valid test statuses and whether they signal success (or failure).

avocado.core.teststatus.STATUSES = ['SKIP', 'ERROR', 'FAIL', 'WARN', 'PASS', 'INTERRUPTED', 'CANCEL']

Valid test statuses, if a returned status is not listed here, it should be handled as error condition.

avocado.core.teststatus.STATUSES_MAPPING = {'CANCEL': True, 'ERROR': False, 'FAIL': False, 'INTERRUPTED': False, 'PASS': True, 'SKIP': True, 'WARN': True}

Maps the different status strings in avocado to booleans.

avocado.core.teststatus.STATUSES_NOT_OK = ['ERROR', 'FAIL', 'INTERRUPTED']

List of status that are NOT considered OK (should cause a job failure)

avocado.core.teststatus.STATUSES_OK = ['SKIP', 'WARN', 'PASS', 'CANCEL']

List of status that are considered OK (should not cause a job failure)

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

property 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

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

property parents

List of parent nodes

property path

Node path

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

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

classmethod from_resultsdir(resultsdir)

Retrieves the job variants objects from the results directory.

This will return a list of variants since a Job can have multiple suites and the variants is per suite.

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

Apply options defined on the cmdline and initialize the plugins.

Parameters

config (dict) – Configuration received from configuration files, command line parser, etc.

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.dump_variant(variant)

Dump a variant into a json-serializable representation

Parameters

variant – Valid variant (list of TreeNode-like objects)

Returns

json-serializable representation

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

avocado.core.initialize_plugin_infrastructure()
avocado.core.initialize_plugins()
avocado.core.register_core_options()