# Extension (plugin) APIs¶

Extension APIs that may be of interest to plugin writers.

## Submodules¶

Result Archive Plugin

class avocado.plugins.archive.Archive
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: result (avocado.core.result.Result) – the complete job result job (avocado.core.job.Job) – the finished job for which a result will be written
class avocado.plugins.archive.ArchiveCLI
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.

class avocado.plugins.config.Config

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

Job Diff

class avocado.plugins.diff.Diff

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

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)

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 tuple with name, version, release, checksum and arch 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 either True if the file is a valid software package or False otherwise bool
class avocado.plugins.distro.DistroPkgInfoLoaderDeb(path)

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 tuple with name, version, release, checksum and arch 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 either True if the file is a valid software package or False otherwise bool
class avocado.plugins.distro.DistroPkgInfoLoaderRpm(path)

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 tuple with name, version, release, checksum and arch 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 a dict with the distro definition data 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 None

class avocado.plugins.envkeep.EnvKeep

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.

Libexec PATHs modifier

class avocado.plugins.exec_path.ExecPath

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.

Run tests with GDB goodies enabled.

class avocado.plugins.gdb.GDB

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.

Human result UI

class avocado.plugins.human.Human(args)

Human result UI

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

Event triggered when a test finishes running

get_colored_status(status, extra=None)
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

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

class avocado.plugins.jobscripts.JobScripts
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

Journal Plugin

class avocado.plugins.journal.Journal

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)

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

class avocado.plugins.json_variants.JsonVariants

Processes the serialized file into variants

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

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 str
update_defaults(defaults)

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

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.

JSON output module.

class avocado.plugins.jsonresult.JSONCLI

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
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: result (avocado.core.result.Result) – the complete job result job (avocado.core.job.Job) – the finished job for which a result will be written

class avocado.plugins.list.List

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

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

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

Plugins information plugin

class avocado.plugins.plugins.Plugins

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

class avocado.plugins.replay.Replay

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.

Base Test Runner Plugins.

class avocado.plugins.run.Run

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.

System information plugin

class avocado.plugins.sysinfo.SysInfo

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

TAP output module.

class avocado.plugins.tap.TAP

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)

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

Tests temporary directory plugin

class avocado.plugins.teststmpdir.TestsTmpDir
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

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

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)

class avocado.plugins.wrapper.Wrapper

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.

xUnit module.

class avocado.plugins.xunit.XUnitCLI

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
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: result (avocado.core.result.Result) – the complete job result job (avocado.core.job.Job`) – the finished job for which a result will be written