The Avocado team is proud to present another LTS (Long Term Stability) release: Avocado 82.0, AKA “Avengers: Endgame”, is now available!
For more information on what a LTS release means, please read RFC: Long Term Stability.
Upgrading from 69.x to 82.0¶
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 pipis an option) and install the
avocado-framework<83.0package to get the latest release of the current LTS version.
- When using RPM packages, please notice that there’s no package
python-avocadoanymore. Please use
python3-avocadoinstead. The same is true for plugins packages, they all have the
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:
avocado.mainfunction 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. See
examples/jobs/passjob_with_test.pyfor 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¶
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:
- Avocado can now run on systems with nothing but Python 3 (and
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
safeloaderis now able to properly find all of its own tests (almost 1000 of them).
- Removal of old and redundant command-line options, such as
--show-job-login favor of
- Job result categorization support, by means of the
--job-categoryoption 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.confshipped 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
vmimagecommand allows a user to list the virtual machine images downloaded by means of
avocado.utils.vmimageor download new images via the avocado
- The avocado
assets fetchcommand now accepts a
--ignore-errorsoption that returns exit code 0 even when some of the assets could not be fetched.
- The avocado
sysinfofeature 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-runneroption. Please refer to
avocado pluginsto 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.outputsection, and recognizes the values
- The jsonresult plugin added
interruptfields containing counters for the tests that ended with WARN and INTERRUPTED status, respectively.
avocado.utils.software_managerfunctionality is now also made available as the
- 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.
--ignore-missing-referencesoption 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 as
avocado jobs showwill show the latest job information.
- The remote, vm, and docker runner plugins were removed.
multiplexcommand, 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
- 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-virtiois 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.
avocado.Test.fetch_asset()method now has two new parameters:
cancel_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,
TAPhas been introduced along with a new loader and resolver. With a
TAPtest, it’s possible to execute a binary or script, similar to a
SIMPLEtest, and parse its Test Anything Protocol output to determine the test status.
- The decorators
avocado.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 of
1,2is treated as a list, a value of
abcis treated as a string, and a value of
1,2,5-10is treated as a list of integers as
1,2,-5(as it is evaluated by
- 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.
avocado.utils.runtimemodule 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.runtimemechanism, 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.pyin the source tree.
- Two simple utility APIs,
avocado.utils.genio.append_one_line()have been added.
- The new
avocado.utils.datadrainerprovides 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_validatorcan help test writers to make sure that given changes have been applied to files.
mountflags 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.
avocado.utils.cpuchanged how it identifies CPU vendors, architectures, and families, making those more consistent across the board.
- The names of the
avocado.utils.cpufunctions changed, from what’s listed on left hand side (now deprecated) the ones on the right hand side:
avocado.utils.cpu.get_arch()implementation for powerpc has been corrected to return
powerpcinstead of cpu family values like
avocado.utils.cpu.get_family()is added to get the cpu family values like
avocado.utils.cpu.offline()will now check the status of the CPU before attempting to apply a possibly (unnecessary) action.
avocado.utils.assetmodule 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.memorynow properly handles huge pages for the POWER platform.
avocado.utils.sshnow 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 the
examples/apis/utils/ssh.pyfor an example.
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.uncompress()and now supports LZMA compressed files transparently.
avocado.utils.vmimagemodule now has providers for the CirrOS cloud images.
avocado.utils.vmimagelibrary now allows a user to define the qemu-img binary that will be used for creating snapshot images via the
avocado.utils.vmimagemodule 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 the
avocado.utils.vmimage.Image.get()method is unchanged in the sense that it returns the path of a snapshot image.
avocado.utils.configure_networkmodule introduced a number of utilities, including MTU configuration support, a method for validating network among peers, IPv6 support, etc.
avocado.utils.configure_network.set_ip()function now supports different interface types through a
interface_typeparameter, 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.
avocado.utils.networkmodule received a complete overhaul and provides features for getting, checking, and setting network information from local and even remote hosts.
avocado.utils.network.interfacesmodule now supports different types of output produced by
avocado.utils.kernelreceived 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 the
avocado.utils.kernel.KernelBuild.vmlinuxproperty, allowing users to access that image if it was built.
- New functions such as
avocado.utils.multipath.suspend_mpath()have been introduced to the
- The new
avocado.utils.pmemmodule 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.gdbAPIs are now back to a working state, with many fixes related to bytes and strings, as well as buffered I/O caching fixes.
- The Avocado configuration that is logged during a job execution is
now the dictionary that is produced by the new
avocado.core.settingsmodule, 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”.