82.0 LTS
The Avocado team is proud to present another LTS (Long Term Stability) release: Avocado 82.0, AKA “Avengers: Endgame”, is now available!
LTS Release
For more information on what a LTS release means, please read RFC: Long Term Stability.
Upgrading from 69.x to 82.0
Upgrading Installations
Avocado is available on a number of different repositories and installation methods. You can find the complete details in Installing Avocado. After looking at your installation options, please consider the following when planning an in-place upgrade or a deployment version bump:
Avocado previously also supported Python 2, but it now supports Python 3 only. If your previous installation was based on Python 2, please consider that the upgrade path includes moving to Python 3. Dependency libraries, syntax changes, and maybe even the availability of a Python 3 interpreter are examples of things to consider.
No issues were observed when doing an in-place upgrade from Python 2 based Avocado 69.x LTS to Python 3 based Avocado 82.0 LTS.
When using Python’s own package management, that is,
pip
, simply switch to a Python 3 based pip (python3 -m pip
is an option) and install theavocado-framework<83.0
package to get the latest release of the current LTS version.When using RPM packages, please notice that there’s no package
python-avocado
anymore. Please usepython3-avocado
instead. The same is true for plugins packages, they all have thepython3-avocado-plugins
prefix.
Porting Tests (Test API compatibility)
If you’re migrating from the previous LTS version, these are the changes on the Test API that most likely will affect your test:
The
avocado.main
function isn’t available anymore. If you were importing it but not really executing the test script, simply remove it. If you need to execute Avocado tests as scripts, you need to resort to the Job API instead. Seeexamples/jobs/passjob_with_test.py
for an example.
Porting Tests (Utility API compatibility)
The changes in the utility APIs (those that live under the
avocado.utils
namespace are too many to present porting
suggestion. Please refer to the Utility APIs section
for a comprehensive list of changes, including new features your test
may be able to leverage.
Changes from previous LTS
Note
This is not a collection of all changes encompassing all releases from 69.0 to 82.0. This list contains changes that are relevant to users of 69.0, when evaluating an upgrade to 82.0.
When compared to the last LTS (version 69.3), the main changes introduced by this versions are:
Users
Avocado can now run on systems with nothing but Python 3 (and “quasi-standard-library” module
setuptools
). This means that it won’t require extra packages, and should be easier to deploy on containers, embedded systems, etc. Optional plugins may have additional requirements.Improved safeloader support for Python unit tests, including support for finding test classes that use multiple inheritances. As an example, Avocado’s
safeloader
is now able to properly find all of its own tests (almost 1000 of them).Removal of old and redundant command-line options, such as
--silent
and--show-job-log
in favor of--show=none
and--show=test
, respectively.Job result categorization support, by means of the
--job-category
option to the run command, allows a user to create an easy to find directory, within the job results directory, for a given type of executed jobs.The glib plugin got a configuration option for safe/unsafe operation, that is, whether it will execute binaries in an attempt to find the whole list of tests. Look for the
glib.conf
shipped with the plugin to enable the unsafe mode.The HTML report got upgrades as pop-up whiteboard, filtering support and resizable columns.
When using the output check record features, duplicate files created by different tests/variants will be consolidated into unique files.
The new
vmimage
command allows a user to list the virtual machine images downloaded by means ofavocado.utils.vmimage
or download new images via the avocadovmimage get
command.The avocado
assets fetch
command now accepts a--ignore-errors
option that returns exit code 0 even when some of the assets could not be fetched.The avocado
sysinfo
feature file will now work out of the box on pip based installations.The sysinfo collection now logs a much clearer message when a command is not found and thus can not have its output collected.
Users can now select which runner plugin will be used to run tests. To select a runner on the command line, use the
--test-runner
option. Please refer toavocado plugins
to see the runner plugins available.A new runner, called
nrunner
, has been introduced and has distinguishing features such as parallel test execution support either in processes or in Podman based containers.A massive documentation overhaul, now designed around guides to different target audiences. The “User’s Guide”, “Test Writer’s Guide” and “Contributor’s Guide” can be easily found as first level sections containing curated content for those audiences.
It’s now possible to enforce colored or non-colored output, no matter if the output is a terminal or not. The configuration item color was introduced in the
runner.output
section, and recognizes the valuesauto
,always
, ornever
.The jsonresult plugin added
warn
andinterrupt
fields containing counters for the tests that ended with WARN and INTERRUPTED status, respectively.Avocado’s
avocado.utils.software_manager
functionality is now also made available as theavocado-software-manager
command-line tool.Avocado now supports “hint files” that can tweak how the Avocado resolver will recognize tests. This is useful for projects making use of Avocado as a test runner, and it can allow complete integration with a simple configuration file in a project repository. For more information check out the documentation.
The
--ignore-missing-references
option now takes no parameter. The feature it controls is not enabled unless you supply the command line option (but no on or off is required).A brand new command,
jobs
, enables users to, among other things, list information about previously executed jobs. A command such asavocado jobs show
will show the latest job information.The remote, vm, and docker runner plugins were removed.
The
multiplex
command, an alias to variants, has been removed.A new settings API that is tightly linked to the Job API. You can see all the existing configurations at runtime by running avocado config reference. To integrate Avocado to an existing project or a CI environment, a custom job with a few configurations will give you a lot of flexibility with very little need to write Python code. Some examples are available at
examples/jobs
.
Test Writers
Python 2 support has been removed. Support for Python versions include 3.5, 3.6, 3.7 and 3.8. If you require Python 2 support, the 69.X LTS version should be used.
A fully usable Job API, making most of Avocado’s functionalities programmable and highly customizable.
Support for multiple test suites in a Job, so that each test suite can be configured differently and independently from each other. Fulfill your use case easily (or let your imagination go wild) and define different runners, different parameters to different test suites, or run some test suites locally, while others run isolated on containers. Anything that is configurable with the new settings API should be transparently configurable in the context of a test suite (provided the test suite deals with that feature).
A completely new implementation of the CIT Varianter plugin, now with support for constraints. Refer to CIT Varianter Plugin for more information.
The new
avocado.cancel_on()
decorator has been added to the Test APIs, allowing you to define the conditions for a test to be considered canceled. See one example here.Avocado can now use tags inside Python Unittests, and not only on its own Instrumented tests.
The tags feature (see Categorizing tests) now supports an extended character set, adding . and - to the allowed characters. A tag such as
:avocado: tags=machine:s390-ccw-virtio
is now valid.INSTRUMENTED tests using the
avocado.Test.fetch_asset()
can take advantage of plugins that will attempt to download (and cache) assets before the test execution. This should make the overall test execution more reliable, and give better test execution times as the download time will be excluded. Users can also manually execute the avocado assets command to manually fetch assets from tests.The
avocado.Test.fetch_asset()
method now has two new parameters:find_only
andcancel_on_missing
. These can be combined to cancel tests if the asset is missing after a download attempt (find_only=False
) or only if it’s present in the local system without a download having been attempted during the test (find_only=True
). This can bring better determinism for tests that would download sizable assets, and/or allow test jobs to be executable in offline environments.A new test type,
TAP
has been introduced along with a new loader and resolver. With aTAP
test, it’s possible to execute a binary or script, similar to aSIMPLE
test, and parse its Test Anything Protocol output to determine the test status.The decorators
avocado.skip()
,avocado.skipIf()
, andavocado.skipUnless()
can now be used to decorate entire classes, resulting in all its tests getting skipped if/when the given condition is satisfied.The “log level” of Avocado is now defined using the standard Python level names. If you have a custom configuration for this setting, you may need to adjust it.
The yaml_to_mux varianter plugin now attempts to respect the type of the value given to
--mux-inject
. For example, 1 is treated as an integer, a value of1,2
is treated as a list, a value ofabc
is treated as a string, and a value of1,2,5-10
is treated as a list of integers as1,2,-5
(as it is evaluated byast.literal_eval()
).For users of the Job API, a “dictionary-based” varianter was introduced, that allows you to describe the variations of tests in a test suite directly via a Python dictionary.
The
avocado.utils.runtime
module has been removed.The test runner feature that would allow binaries to be run transparently inside GDB was removed. The reason for dropping such a feature has to do with how it limits the test runner to run one test at a time, and the use of the
avocado.utils.runtime
mechanism, also removed.The “standalone job” feature was removed. The alternative is to use an Avocado Job (using the Job API), with a test defined on the same file, as can be seen on the example file
examples/jobs/passjob_with_test.py
in the source tree.
Utility APIs
Two simple utility APIs,
avocado.utils.genio.append_file()
andavocado.utils.genio.append_one_line()
have been added.The new
avocado.utils.datadrainer
provides an easy way to read from and write to various input/output sources without blocking a test (by spawning a thread for that).The new
avocado.utils.diff_validator
can help test writers to make sure that given changes have been applied to files.avocado.utils.partition
now allowsmkfs
andmount
flags to be set.Users of the
avocado.utils.partition.mount()
function can now skip checking if the devices/mountpoints are mounted, which is useful for bind mounts.avocado.utils.cpu.get_cpu_vendor_name()
now returns the CPU vendor name for POWER9.The
avocado.utils.cpu
changed how it identifies CPU vendors, architectures, and families, making those more consistent across the board.The names of the
avocado.utils.cpu
functions changed, from what’s listed on left hand side (now deprecated) the ones on the right hand side:
avocado.utils.cpu.total_cpus_count()
=>avocado.utils.cpu.total_count()
avocado.utils.cpu._get_cpu_info()
=>avocado.utils.cpu._get_info()
avocado.utils.cpu._get_cpu_status()
=>avocado.utils.cpu._get_status()
avocado.utils.cpu.get_cpu_vendor_name()
=>avocado.utils.cpu.get_vendor()
avocado.utils.cpu.get_cpu_arch()
=>avocado.utils.cpu.get_arch()
avocado.utils.cpu.cpu_online_list()
=>avocado.utils.cpu.online_list()
avocado.utils.cpu.online_cpus_count()
=>avocado.utils.cpu.online_count()
avocado.utils.cpu.get_cpuidle_state()
=>avocado.utils.cpu.get_idle_state()
avocado.utils.cpu.set_cpuidle_state()
=>avocado.utils.cpu.set_idle_state()
avocado.utils.cpu.set_cpufreq_governor()
=>avocado.utils.cpu.set_freq_governor()
avocado.utils.cpu.get_cpufreq_governor()
=>avocado.utils.cpu.get_freq_governor()
Additionally,
avocado.utils.cpu.get_arch()
implementation for powerpc has been corrected to returnpowerpc
instead of cpu family values likepower8
,power9
.New
avocado.utils.cpu.get_family()
is added to get the cpu family values likepower8
,power9
.The
avocado.utils.cpu.online()
andavocado.utils.cpu.offline()
will now check the status of the CPU before attempting to apply a possibly (unnecessary) action.The
avocado.utils.asset
module now allows a given location, as well as a list, to be given, simplifying the most common use case.avocado.utils.process.SubProcess.stop()
now supports setting a timeout.avocado.utils.memory
now properly handles huge pages for the POWER platform.avocado.utils.ssh
now allows password-based authentication, in addition to public key-based authentication.The new
avocado.utils.ssh.Session.get_raw_ssh_command()
method allows access to the generated (local) commands, which could be used for advanced use cases, such as running multiple (remote) commands in a test. See theexamples/apis/utils/ssh.py
for an example.The
avocado.utils.ssh.Session.cmd()
method now allows users to ignore the exit status of the command with the ignore_status parameter.avocado.utils.path.usable_ro_dir()
will no longer create a directory, but will just check for its existence and the right level of access.avocado.utils.archive.compress()
andavocado.utils.archive.uncompress()
and now supports LZMA compressed files transparently.The
avocado.utils.vmimage
module now has providers for the CirrOS cloud images.The
avocado.utils.vmimage
library now allows a user to define the qemu-img binary that will be used for creating snapshot images via theavocado.utils.vmimage.QEMU_IMG
variable.The
avocado.utils.vmimage
module will not try to create snapshot images when it’s not needed, acting lazily in that regard. It now provides a different method for download-only operations,avocado.utils.vmimage.Image.download()
that returns the base image location. The behavior of theavocado.utils.vmimage.Image.get()
method is unchanged in the sense that it returns the path of a snapshot image.The
avocado.utils.configure_network
module introduced a number of utilities, including MTU configuration support, a method for validating network among peers, IPv6 support, etc.The
avocado.utils.configure_network.set_ip()
function now supports different interface types through ainterface_type
parameter, while still defaulting to Ethernet.avocado.utils.configure_network.is_interface_link_up()
is a new utility function that returns, quite obviously, whether an interface link is up.The
avocado.utils.network
module received a complete overhaul and provides features for getting, checking, and setting network information from local and even remote hosts.The
avocado.utils.network.interfaces
module now supports different types of output produced byiproute
.avocado.utils.kernel
received a number of fixes and cleanups, and also new features. It’s now possible to configure the kernel for multiple targets, and also set kernel configurations at configuration time without manually touching the kernel configuration files. It also introduced theavocado.utils.kernel.KernelBuild.vmlinux
property, allowing users to access that image if it was built.New functions such as
avocado.utils.multipath.add_path()
,avocado.utils.multipath.remove_path()
,avocado.utils.multipath.get_mpath_status()
andavocado.utils.multipath.suspend_mpath()
have been introduced to theavocado.utils.multipath
module.The new
avocado.utils.pmem
module provides an interface to manage persistent memory. It allows for creating, deleting, enabling, disabling, and re-configuring both namespaces and regions depending on supported hardware. It wraps the features present on the ndctl and daxctl binaries.All of the
avocado.utils.gdb
APIs are now back to a working state, with many fixes related to bytes and strings, as well as buffered I/O caching fixes.
Contributors
The Avocado configuration that is logged during a job execution is now the dictionary that is produced by the new
avocado.core.settings
module, instead of the configuration file(s) content. This is relevant because this configuration contains the result of everything that affects a job, such as defaults registered by plugins, command-line options, all in addition to the configuration file. The goal is to have more consistent behavior and increased job “replayability”.
Complete list of changes
For a complete list of changes between the last LTS release (69.3) and this release, please check out the Avocado commit changelog.