Extension (plugin) APIs

Extension APIs that may be of interest to plugin writers.

Submodules

avocado.plugins.archive module

Result Archive Plugin

class avocado.plugins.archive.Archive

Bases: avocado.core.plugin_interfaces.Result

description = 'Result archive (ZIP) support'
name = 'zip_archive'
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.plugins.archive.ArchiveCLI

Bases: avocado.core.plugin_interfaces.CLI

configure(parser)

Configures the command line parser with options specific to this plugin

description = 'Result archive (ZIP) support to run command'
name = 'zip_archive'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

avocado.plugins.config module

class avocado.plugins.config.Config

Bases: avocado.core.plugin_interfaces.CLICmd

Implements the avocado ‘config’ subcommand

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 = 'Shows avocado config keys'
name = 'config'
run(args)

Entry point for actually running the command

avocado.plugins.diff module

Job Diff

class avocado.plugins.diff.Diff

Bases: avocado.core.plugin_interfaces.CLICmd

Implements the avocado ‘diff’ subcommand

configure(parser)

Add the subparser for the diff action.

Parameters:parser – Main test runner parser.
description = 'Shows the difference between 2 jobs.'
name = 'diff'
run(args)

Entry point for actually running the command

avocado.plugins.distro module

avocado.plugins.distro.DISTRO_PKG_INFO_LOADERS = {'deb': <class 'avocado.plugins.distro.DistroPkgInfoLoaderDeb'>, 'rpm': <class 'avocado.plugins.distro.DistroPkgInfoLoaderRpm'>}

the type of distro that will determine what loader will be used

class avocado.plugins.distro.Distro

Bases: avocado.core.plugin_interfaces.CLICmd

Implements the avocado ‘distro’ subcommand

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 = 'Shows detected Linux distribution'
get_output_file_name(args)

Adapt the output file name based on given args

It’s not uncommon for some distros to not have a release number, so adapt the output file name to that

name = 'distro'
run(args)

Entry point for actually running the command

class avocado.plugins.distro.DistroDef(name, version, release, arch)

Bases: avocado.utils.distro.LinuxDistro

More complete information on a given Linux Distribution

Can and should include all the software packages that ship with the distro, so that an analysis can be made on whether a given package that may be responsible for a regression is part of the official set or an external package.

software_packages = None

All the software packages that ship with this Linux distro

software_packages_type = None

A simple text that denotes the software type that makes this distro

to_dict()

Returns the representation as a dictionary

to_json()

Returns the representation of the distro as JSON

class avocado.plugins.distro.DistroPkgInfoLoader(path)

Bases: object

Loads information from the distro installation tree into a DistroDef

It will go through all package files and inspect them with specific package utilities, collecting the necessary information.

get_package_info(path)

Returns information about a given software package

Should be implemented by classes inheriting from DistroDefinitionLoader.

Parameters:path (str) – path to the software package file
Returns:tuple with name, version, release, checksum and arch
Return type:tuple
get_packages_info()

This method will go through each file, checking if it’s a valid software package file by calling is_software_package() and calling load_package_info() if it’s so.

is_software_package(path)

Determines if the given file at path is a software package

This check will be used to determine if load_package_info() will be called for file at path. This method should be implemented by classes inheriting from DistroPkgInfoLoader and could be as simple as checking for a file suffix.

Parameters:path (str) – path to the software package file
Returns:either True if the file is a valid software package or False otherwise
Return type:bool
class avocado.plugins.distro.DistroPkgInfoLoaderDeb(path)

Bases: avocado.plugins.distro.DistroPkgInfoLoader

Loads package information for DEB files

get_package_info(path)

Returns information about a given software package

Should be implemented by classes inheriting from DistroDefinitionLoader.

Parameters:path (str) – path to the software package file
Returns:tuple with name, version, release, checksum and arch
Return type:tuple
is_software_package(path)

Determines if the given file at path is a software package

This check will be used to determine if load_package_info() will be called for file at path. This method should be implemented by classes inheriting from DistroPkgInfoLoader and could be as simple as checking for a file suffix.

Parameters:path (str) – path to the software package file
Returns:either True if the file is a valid software package or False otherwise
Return type:bool
class avocado.plugins.distro.DistroPkgInfoLoaderRpm(path)

Bases: avocado.plugins.distro.DistroPkgInfoLoader

Loads package information for RPM files

get_package_info(path)

Returns information about a given software package

Should be implemented by classes inheriting from DistroDefinitionLoader.

Parameters:path (str) – path to the software package file
Returns:tuple with name, version, release, checksum and arch
Return type:tuple
is_software_package(path)

Systems needs to be able to run the rpm binary in order to fetch information on package files. If the rpm binary is not available on this system, we simply ignore the rpm files found

class avocado.plugins.distro.SoftwarePackage(name, version, release, checksum, arch)

Bases: object

Definition of relevant information on a software package

to_dict()

Returns the representation as a dictionary

to_json()

Returns the representation of the distro as JSON

avocado.plugins.distro.load_distro(path)

Loads the distro from an external file

Parameters:path (str) – the location for the input file
Returns:a dict with the distro definition data
Return type:dict
avocado.plugins.distro.load_from_tree(name, version, release, arch, package_type, path)

Loads a DistroDef from an installable tree

Parameters:
  • name (str) – a short name that precisely distinguishes this Linux Distribution among all others.
  • version (str) – the major version of the distribution. Usually this is a single number that denotes a large development cycle and support file.
  • release (str) – the release or minor version of the distribution. Usually this is also a single number, that is often omitted or starts with a 0 when the major version is initially release. It’s often associated with a shorter development cycle that contains incremental a collection of improvements and fixes.
  • arch (str) – the main target for this Linux Distribution. It’s common for some architectures to ship with packages for previous and still compatible architectures, such as it’s the case with Intel/AMD 64 bit architecture that support 32 bit code. In cases like this, this should be set to the 64 bit architecture name.
  • package_type (str) – one of the available package info loader types
  • path (str) – top level directory of the distro installation tree files
avocado.plugins.distro.save_distro(linux_distro, path)

Saves the linux_distro to an external file format

Parameters:
  • linux_distro (DistroDef) – an DistroDef instance
  • path (str) – the location for the output file
Returns:

None

avocado.plugins.envkeep module

class avocado.plugins.envkeep.EnvKeep

Bases: avocado.core.plugin_interfaces.CLI

Keep environment variables on remote executions

configure(parser)

Configures the command line parser with options specific to this plugin

description = 'Keep variables in remote environment'
name = 'envkeep'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

avocado.plugins.exec_path module

Libexec PATHs modifier

class avocado.plugins.exec_path.ExecPath

Bases: avocado.core.plugin_interfaces.CLICmd

Implements the avocado ‘exec-path’ subcommand

description = 'Returns path to avocado bash libraries and exits.'
name = 'exec-path'
run(args)

Print libexec path and finish

Parameters:args – Command line args received from the run subparser.

avocado.plugins.gdb module

Run tests with GDB goodies enabled.

class avocado.plugins.gdb.GDB

Bases: avocado.core.plugin_interfaces.CLI

Run tests with GDB goodies enabled

configure(parser)

Configures the command line parser with options specific to this plugin

description = "GDB options for the 'run' subcommand"
name = 'gdb'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

avocado.plugins.human module

Human result UI

class avocado.plugins.human.Human(args)

Bases: avocado.core.plugin_interfaces.ResultEvents

Human result UI

description = 'Human Interface UI'
end_test(result, state)

Event triggered when a test finishes running

name = 'human'
output_mapping = {'CANCEL': '', 'ERROR': '', 'FAIL': '', 'INTERRUPTED': '', 'PASS': '', 'SKIP': '', 'WARN': ''}
post_tests(job)

Entry point for job running actions after the tests execution

pre_tests(job)

Entry point for job running actions before tests execution

start_test(result, state)

Event triggered when a test starts running

test_progress(progress=False)

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

class avocado.plugins.human.HumanJob

Bases: avocado.core.plugin_interfaces.JobPre, avocado.core.plugin_interfaces.JobPost

Human result UI

description = 'Human Interface UI'
name = 'human'
post(job)

Entry point for actually running the post job action

pre(job)

Entry point for actually running the pre job action

avocado.plugins.jobscripts module

class avocado.plugins.jobscripts.JobScripts

Bases: avocado.core.plugin_interfaces.JobPre, avocado.core.plugin_interfaces.JobPost

description = 'Runs scripts before/after the job is run'
name = 'jobscripts'
post(job)

Entry point for actually running the post job action

pre(job)

Entry point for actually running the pre job action

avocado.plugins.journal module

Journal Plugin

class avocado.plugins.journal.Journal

Bases: avocado.core.plugin_interfaces.CLI

Test journal

configure(parser)

Configures the command line parser with options specific to this plugin

description = "Journal options for the 'run' subcommand"
name = 'journal'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

class avocado.plugins.journal.JournalResult(args)

Bases: avocado.core.plugin_interfaces.ResultEvents

Test Result Journal class.

This class keeps a log of the test updates: started running, finished, etc. This information can be forwarded live to an avocado server and provide feedback to users from a central place.

Creates an instance of ResultJournal.

Parameters:job – an instance of avocado.core.job.Job.
description = 'Journal event based results implementation'
end_test(result, state)

Event triggered when a test finishes running

lazy_init_journal(state)
name = 'journal'
post_tests(job)

Entry point for job running actions after the tests execution

pre_tests(job)

Entry point for job running actions before tests execution

start_test(result, state)

Event triggered when a test starts running

test_progress(progress=False)

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

avocado.plugins.json_variants module

class avocado.plugins.json_variants.JsonVariants

Bases: avocado.core.plugin_interfaces.Varianter

Processes the serialized file into variants

description = 'JSON serialized based Varianter'
initialize(args)
name = 'json variants'
to_str(summary, variants, **kwargs)

Return human readable representation

The summary/variants accepts verbosity where 0 means silent and maximum is up to the plugin.

Parameters:
  • summary – How verbose summary to output (int)
  • variants – How verbose list of variants to output (int)
  • kwargs – Other free-form arguments
Return type:

str

update_defaults(defaults)

Add default values

Note:Those values should not be part of the variant_id
variants = None
class avocado.plugins.json_variants.JsonVariantsCLI

Bases: avocado.core.plugin_interfaces.CLI

Serialized based Varianter options

configure(parser)

Configures the command line parser with options specific to this plugin

description = "JSON serialized based Varianter options for the 'run' subcommand"
name = 'json variants'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

avocado.plugins.jsonresult module

JSON output module.

class avocado.plugins.jsonresult.JSONCLI

Bases: avocado.core.plugin_interfaces.CLI

JSON output

configure(parser)

Configures the command line parser with options specific to this plugin

description = "JSON output options for 'run' command"
name = 'json'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

class avocado.plugins.jsonresult.JSONResult

Bases: avocado.core.plugin_interfaces.Result

description = 'JSON result support'
name = 'json'
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:

avocado.plugins.list module

class avocado.plugins.list.List

Bases: avocado.core.plugin_interfaces.CLICmd

Implements the avocado ‘list’ subcommand

configure(parser)

Add the subparser for the list action.

Parameters:parser – Main test runner parser.
description = 'List available tests'
name = 'list'
run(args)

Entry point for actually running the command

class avocado.plugins.list.TestLister(args)

Bases: object

Lists available test modules

list()

avocado.plugins.multiplex module

class avocado.plugins.multiplex.Multiplex(*args, **kwargs)

Bases: avocado.plugins.variants.Variants

DEPRECATED version of the “avocado multiplex” command which is replaced by “avocado variants” one.

name = 'multiplex'
run(args)

Entry point for actually running the command

avocado.plugins.plugins module

Plugins information plugin

class avocado.plugins.plugins.Plugins

Bases: avocado.core.plugin_interfaces.CLICmd

Plugins information

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 = 'Displays plugin information'
name = 'plugins'
run(args)

Entry point for actually running the command

avocado.plugins.replay module

class avocado.plugins.replay.Replay

Bases: avocado.core.plugin_interfaces.CLI

Replay a job

configure(parser)

Configures the command line parser with options specific to this plugin

description = "Replay options for 'run' subcommand"
load_config(resultsdir)
name = 'replay'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

avocado.plugins.run module

Base Test Runner Plugins.

class avocado.plugins.run.Run

Bases: avocado.core.plugin_interfaces.CLICmd

Implements the avocado ‘run’ subcommand

configure(parser)

Add the subparser for the run action.

Parameters:parser – Main test runner parser.
description = 'Runs one or more tests (native test, test alias, binary or script)'
name = 'run'
run(args)

Run test modules or simple tests.

Parameters:args – Command line args received from the run subparser.

avocado.plugins.sysinfo module

System information plugin

class avocado.plugins.sysinfo.SysInfo

Bases: avocado.core.plugin_interfaces.CLICmd

Collect system information

configure(parser)

Add the subparser for the run action.

Parameters:parser – Main test runner parser.
description = 'Collect system information'
name = 'sysinfo'
run(args)

Entry point for actually running the command

avocado.plugins.tap module

TAP output module.

class avocado.plugins.tap.TAP

Bases: avocado.core.plugin_interfaces.CLI

TAP Test Anything Protocol output avocado plugin

configure(parser)

Configures the command line parser with options specific to this plugin

description = 'TAP - Test Anything Protocol results'
name = 'TAP'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

class avocado.plugins.tap.TAPResult(args)

Bases: avocado.core.plugin_interfaces.ResultEvents

TAP output class

description = 'TAP - Test Anything Protocol results'
end_test(result, state)

Log the test status and details

name = 'tap'
post_tests(job)

Entry point for job running actions after the tests execution

pre_tests(job)

Log the test plan

start_test(result, state)

Event triggered when a test starts running

test_progress(progress=False)

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

avocado.plugins.tap.file_log_factory(log_file)

Generates a function which simulates writes to logger and outputs to file

Parameters:log_file – The output file

avocado.plugins.teststmpdir module

Tests temporary directory plugin

class avocado.plugins.teststmpdir.TestsTmpDir

Bases: avocado.core.plugin_interfaces.JobPre, avocado.core.plugin_interfaces.JobPost

description = 'Creates a temporary directory for tests consumption'
name = 'teststmpdir'
post(job)

Entry point for actually running the post job action

pre(job)

Entry point for actually running the pre job action

avocado.plugins.variants module

class avocado.plugins.variants.Variants(*args, **kwargs)

Bases: avocado.core.plugin_interfaces.CLICmd

Implements “variants” command to visualize/debug test variants and params

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 = 'Tool to analyze and visualize test variants and params'
name = 'variants'
run(args)

Entry point for actually running the command

avocado.plugins.variants.map_verbosity_level(level)

avocado.plugins.wrapper module

class avocado.plugins.wrapper.Wrapper

Bases: avocado.core.plugin_interfaces.CLI

Implements the ‘–wrapper’ flag for the ‘run’ subcommand

configure(parser)

Configures the command line parser with options specific to this plugin

description = "Implements the '--wrapper' flag for the 'run' subcommand"
name = 'wrapper'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

avocado.plugins.xunit module

xUnit module.

class avocado.plugins.xunit.XUnitCLI

Bases: avocado.core.plugin_interfaces.CLI

xUnit output

configure(parser)

Configures the command line parser with options specific to this plugin

description = 'xUnit output options'
name = 'xunit'
run(args)

Execute any action the plugin intends.

Example of action may include activating a special features upon finding that the requested command line options were set by the user.

Note: this plugin class is not intended for adding new commands, for that please use CLICmd.

class avocado.plugins.xunit.XUnitResult

Bases: avocado.core.plugin_interfaces.Result

PRINTABLE = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~\n\r '
UNKNOWN = '<unknown>'
description = 'XUnit result support'
name = 'xunit'
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:

Module contents