docs/source/releases/lts/92_0.rst
.. _lts_92_0:
========
92.0 LTS
========
The Avocado team is proud to present another LTS (Long Term Stability)
release: Avocado 92.0, AKA "Monsters, Inc.", is now available!
LTS Release
===========
For more information on what a LTS release means, please read
:ref:`rfc-long-term-stability`.
Upgrading from 82.x to 92.0
===========================
Upgrading Installations
-----------------------
Avocado is available on a number of different repositories and
installation methods. You can find the complete details
:ref:`here <installing>`.
After looking at your installation options, please consider the
following when planning an in-place upgrade or a deployment version
bump:
* When using Python's own package management, that is, ``pip``, simply
choose a version lower to the *next* Avocado release to benefit from
minor releases (bugfixes) in this LTS series. In short,
``avocado-framework<93.0`` will get you the latest release of this
LTS series.
* When using RPM packages on Linux distributions that provide modular
packages, select the ``92lts`` stream. If no modules are available,
use your package manager tools (such as DNF's versionlock plugin) to
pin the installation to the 92.x versions.
Porting Tests
-------------
Test API compatibility
~~~~~~~~~~~~~~~~~~~~~~
There is only one known incompatible changes on the Test API:
* The :class:`avocado.Test` used to contain a reference to its
:class:`avocado.core.job.Job` in its ``job`` attribute. Even
though it was intended for internal use, the fact that the
attribute was available to tests, means that tests could
be relying on it. If your test uses the ``job`` attribute,
please consider looking at the suite's configuration instead,
and passing that information as a test parameter.
Utility API compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~
The changes in the utility APIs (those that live under the
``avocado.utils`` namespace) are too many to present porting
suggestions. Please refer to the :ref:`lts_92_0_utility_apis` section
for a comprehensive list of changes, including new features your test
may be able to leverage.
General points
~~~~~~~~~~~~~~
* With regards to logging, from now on, Avocado limits itself to
``avocado.*`` loggers. If your test is logging using the root
logger ( ``logging.info(...)``), make sure you are using a proper
namespace. i.e::
import logging
LOG = logging.getLogger('avocado.test.foo')
LOG.info('your message')
Important Announcement
======================
Since the previous LTS version (82.0), Avocado has switched the
default runner, from the implementation most people currently use
(internally simply called ``runner``), to the newer architecture and
implementation called ``nrunner``).
**Users migrating from Avocado 82.x will be impacted by this change
and should act accordingly.**
To keep using the current (soon to be legacy) runner, you **must** set
the ``--test-runner=runner`` command line option (or the equivalent
``test_runner`` configuration option, under section ``[run]``).
Known issues are being tracked on our GitHub project page, with the
``nrunner`` tag, and new issue reports are appreciated.
Changes from previous LTS
=========================
.. note:: This is not a collection of all changes encompassing all releases
from 82.0 to 92.0. This list contains changes that are relevant
to users of 82.0, when evaluating an upgrade to 92.0.
When compared to the last LTS (version 82.0), the main changes
introduced by this versions are:
Users / Test Writers
--------------------
* The ``nrunner`` test runner implementation is now the default on
every ``avocado run`` command (or equivalent Job API scripts).
Since the previous release, ``nrunner`` supports:
1. the "fail fast" (``run --failfast``) feature.
2. The ``--dry-run`` feature.
3. :ref:`the varianter <varianter>` feature.
4. UNIX domain sockets as the communication channel with runners (the
new default).
5. a ``sysinfo`` runner, which will allow for sysinfo collection on
any supported spawner.
6. early notification of missing runners for tasks in the requested
suite.
* Yaml To Mux plugin now properly supports ``None`` values.
* Command line options related to results, such as
``--json-job-result``, ``--tap-job-result``, ``--xunit-job-result``
and ``--html-job-result`` are now "proper boolean" options (such as
``--disable-json-job-result``, ``--disable-xunit-job-result``, etc).
* The JSON results (``results.json``) now contain a field with the
path of the test log file.
* Pre and Post (job) plugins are now respected when used with the Job
API.
* Support for ``avocado list`` "extra information" has been
restored. This is used in Avocado-VT loaders. They will be removed
(again) for good after its usage is deprecated and removed in
Avocado-VT.
* It’s now possible to set a timeout (via the ``task.timeout.running
configuration`` option) for nrunner tasks. Effectively this works as
an execution timeout for tests run with ``--test-runner=nrunner``.
* The ``avocado assets`` command introduces three different subcommands:
1. ``register`` allows users to register their own assets with the
avocado assets register command. Then, the registered asset can
be used transparently with the
:meth:`avocado.core.test.Test.fetch_asset` by its name. This
feature helps with tests that need to use assets that can not be
downloaded by Avocado itself.
2. ``list`` allows listing of assets based on their sizes or the
number of days since they have been last accessed.
3. ``purge`` allows purging of assets based on their sizes or the
number of days since they have been last accessed. For more
information please refer to :ref:`managing-assets`.
* The assets plugin ``fetch`` command (``avocado assets fetch``) now
supports:
1. fetching assets defined in a Python list in ``INSTRUMENTED``
tests.
2. setting a timeout for the download of assets.
* :func:`avocado.skipIf` and :func:`avocado.skipUnless` now allow the
condition to be a callable, to be evaluated much later, and also
gives them access to the test class. For more information, please
refer to the documentation: :ref:`skip-advanced-conditionals`.
* The presentation of SIMPLE tests has been improved in the sense that
they are now much more configurable. One can now set the
``simpletests.status.failure_fields`` to configure how the status
line showed just after a failed test will look like, and
``job.output.testlogs.logfiles`` to determine the files that will be
shown at the end of the job for failed tests.
* Avocado's safeloader (the system used to find Python based tests
without executing them) received a major overhaul and now supports:
1. Multi-level module imports, such as ``from my.base.test import
Test`` where a project may contain a ``my/base`` directory
structure containing ``test.py`` that defines a custom ``Test``
class.
2. Support for following the import/inheritance hierarchy when a
module contains an import for a given symbol, instead of the
actual ``class`` definition of a symbol.
3. Considers coroutines (AKA ``async def``) as valid tests, reducing
the number of boiler plate code necessary for tests of ``asyncio``
based code.
4. Supports class definitions (containing tests or not) that use a
typing hint with subscription, commonly used in generics.
* Test parameters given with ``-p`` are now supported when using the
nrunner.
* Improved checks when users attempt to use the varianter and simple
parameters (``-p``) at the same time.
* All status server URIs in the configuration are now respected for
``nrunner`` executions.
* The resolver plugins now have access to the job/suite configuration.
* The data directories now have fewer heuristics and are now more
predictable and consistent with the configuration set.
* The root logger for Python's :mod:`logging` should no longer be
impacted by Avocado's own logging initialization and clean-up (which
now limits itself to ``avocado.*`` loggers).
* The Podman spawner (``--nrunner-spawner=podman``) will now attempt
to use a container image (``--spawner-podman-image=``) that matches
the host Linux distribution. If it’s not possible to detect the host
distribution, the latest Fedora image will be used.
* The ``exec-test`` runner now accepts a configuration
(``runner.exectest.exitcodes.skip``) that will determine valid exit
codes to be treated as ``SKIP`` test results.
* The Loader based on the YAML Multiplexer has been removed. Users are
advised to use Job API and multiple test suites to fulfill similar
use cases.
* The GLib plugin has been removed. Users are advised to use TAP test
types instead, given that GLib’s GTest framework now defaults to
producing TAP output.
* The paginator feature is now a boolean style option. To enable it,
use ``--enable-paginator``.
* The nrunner status server now has two different options regarding
its URI. The first one, ``--nrunner-status-server-listen``
determines the URI to which a status server will listen. The second
one, ``--nrunner-status-server-uri`` determines where the results
will be sent to. This allows the status server to be on a different
network location than the tasks reporting to it.
* The ``avocado-software-manager`` command line application now
properly returns exit status for failures.
* The Podman spawner now exposes command-line options to set the
container image (``--spawner-podman-image``) and the Podman binary
(``--spawner-podman-bin``) used on an avocado invocation.
* The Requirements Resolver feature has been introduced, and it's
available for general use. It allows users to describe requirements
tests may have, and will attempt to fulfill those before the test is
executed. It has support for **package** requirements, meaning
operating system level packages such as RPM, DEB, etc, and **asset**
requirements, allowing users to declare any asset obtainable with
:mod:`avocado.utils.asset` to be downloaded, cached and thus be
available to tests.
This can greatly simplify the setup of the environments the tests
will run on, and at the same time, not cause test errors because of
the missing requirements (which will cause the test to be skipped).
For more information please refer to the :ref:`managing-requirements`
section.
* ``avocado list`` got a ``--json`` option, which will output the list
of tests in a machine-readable format.
* The minimal Python version requirement now is 3.6. Python 3.5 and
earlier are not tested nor supported starting with this release.
* Because of the characteristics of the nrunner architecture, it has
been decided that log content generated by tests will not be copied
to the ``job.log`` file, but will only be available on the
respective test logs on the ``test-results`` directory. Still, users
will often need to know if tests have been started or have finished
while looking at the ``job.log`` file. This feature has been
implemented by means of the ``testlogs`` plugin.
* Avocado will log a warning, making it clear that it can not check
the integrity of a requested asset when no hash is given. This is
related to users of the :mod:`avocado.utils.asset` module or
:meth:`avocado.Test.fetch_asset` utility method.
* Avocado’s cache directory defined in the configuration will now have
the ultimate saying, instead of the dynamic probe for “sensible”
cache directories that could end up not respecting the user’s
configurations.
* The man page has been thoroughly updated and put in sync with the
current avocado command features and options.
* Avocado can now run from Python eggs. It’s expected that official
egg builds will be made available in the future. Avocado is planning
to use eggs as an automatic and transparent deployment mechanism for
environments such as containers and VMs.
* The ``datadir.paths.logs_dir`` and ``datadir.paths.data_dir`` are
set to more consistent and predictable values, and won’t rely
anymore on dynamic probes for “suitable” directories.
* The Human UI plugin can now be configured to omit certain statuses
from being show in a new line. This can be used, for instance, to
prevent the ``STARTED`` lines to be shown, showing only the final
test result.
* The nrunner ``exec`` runnable kind does not exist anymore, and its
functionality was consolidated into the ``exec-test``.
* Executing Python's unittest that are skipped are now always shown as
having status ``SKIP``, instead of the previous ``CANCEL``.
* Avocado will no longer incorporate log messages coming from any
logger (including the "root logger") into the test's and job's log
files. Only loggers that under the ``avocado.`` namespace will be
included. Users are encouraged to continue to follow the pattern::
self.log.info("message goes here")
When logging from a test. When logging from somewhere else, the
following pattern is advised (replace ``my.namespace``
accordingly)::
import logging
LOG = logging.getLogger('avocado.my.namespace')
LOG.info('your message')
* Python 3.10 is now fully supported.
* The reason for fail/error/skip tests in Python unittest are now
given on the various test result formats (including on the UI).
Bug Fixes
---------
* The ``run.dict_variants`` setting is now properly registered in an
Init plugin.
* The avocado replay command was calling pre/post plugins twice after
a change delegated that responsibility to
:meth:`avocado.core.job.Job.run`.
* The :mod:`avocado.core.safeloader` now supports relative imports
with names, meaning that syntax such as ``from ..upper import foo``
was not properly parsed.
* The TAP parser (:mod:`avocado.core.tapparser`) will not choke on
unexpected content, ignoring it according to the standard.
* The assets plugin (``avocado assets`` command) now returns
meaningful exit code on some failures and success situations.
* The extraction of DEB packages by means of
:meth:`avocado.utils.software_manager.SoftwareManager.extract_from_package`
was fixed and does not depend on the ``ar`` utility anymore (as it now
uses the :mod:`avocado.utils.ar` module).
* The ``--store-logging-stream`` parameter value was being incorrectly
parsed as a list of characters. If a ``bar`` value is given, it
would generate the ``b.INFO``, ``a.INFO``, and ``r.INFO`` file. The
fix parses the command line arguments by treating the value as a
comma-separated list (that becomes a set).
* If a job contains multiple test suites with the same name, and tests
within those suites also have the same name, test results would be
overwritten. Now job name uniqueness is enforced and no test results
from a suite should be able to overwrite others.
* :meth:`avocado.utils.network.interfaces.NetworkInterface.is_admin_link_up`
and
:meth:`avocado.utils.network.interfaces.NetworkInterface.is_operational_link_up`
now behave properly on interfaces based on bonding.
* :mod:`avocado.utils.process` utilities that use ``sudo`` would check
for executable permissions on the binary. Many systems will have
sudo with the executable bit set, but not the readable bit. This is
now accounted for.
* The “external runner” feature now works properly when used outside
of an avocado command-line invocation, that is, when used in a
script based on the Job APIs.
* Avocado will now give an error message and exit cleanly, instead of
crashing, when the resulting test suite to be executed contains no
tests. That can happen, for instance, when invalid references are
given along with the ``--ignore-missing-references`` command-line
option.
* A crash when running ``avocado distro --distro-def-create`` has been
fixed.
* Properties, that is, methods decorated with ``@property`` are no
longer seen as tests.
* If a path to a Python unittest file contained dots, the conversion
to a unittest "dotted name" would fail.
* Tests on classes that inherit from one marked with ``:avocado:
disable`` were not being detected.
nrunner stabilization
~~~~~~~~~~~~~~~~~~~~~
* :class:`avocado.core.nrunner.Runnables` created by suites will now
contain the full suite configuration.
* The nrunner implementation for ``exec-test`` suffered from a
limitation to the amount of output it could collect. It was related
to the size of the ``PIPE`` used internally by the Python subprocess
module. This limitation has now been lifted.
* nrunner will now properly translate reference names with absolute
paths into Python unittest “dotted names”.
* The nrunner status server can be configured with the maximum buffer
size that it uses.
* The ``avocado-instrumented`` nrunner runner now covers all valid
test statuses.
* The correct failure reason for tests executed with the nrunner is
now being captured, instead of a possible exception caused by an
error within the runner itself.
* The nrunner status server socket is now properly closed, which
allows multiple test suites in a job to not conflict.
* The nrunner status server now properly handles the asyncio API with
Python 3.6.
* The ``testlog`` plugin wasn’t able to show the log location for
tests executed via the ``avocado-runner-avocado-instrumented``
runner and this is now fixed.
* The ``avocado-runner-avocado-instrumented`` was producing duplicate
log entries because Avocado’s log handler for the
:class:`avocado.core.test.Test` was previously configured to
propagate the logged messages.
* The nrunner TAP runner now supports/parses large amounts of data,
where it would previously crash when buffers were overrun.
* The Podman spawner will now respect the Podman binary set in the job
configuration.
* The ``whiteboard`` file and data are now properly saved when using
the nrunner.
* Some occurrences of the incorrect ``AVOCADO_TEST_OUTPUT_DIR``
environment variable name were renamed to the proper name
``AVOCADO_TEST_OUTPUTDIR``.
* The selection of an nrunner based runner, from its Python module
name/path, has been fixed.
* The ``nrunner`` now properly sets all test status to the suite summary,
making sure that errors are communicated to the end-user through,
among other means, the avocado execution exit code.
* When running tests in parallel, multiple downloads of the same image
(when using :mod:`avocado.utils.vmimage`) is now prevented by a
better (early) locking.
* A condition in which tests running in parallel could collide over
the existence of the asset’s cache directory (created by other
running tests) is now fixed.
.. _lts_92_0_utility_apis:
Utility APIs
------------
* A new :mod:`avocado.utils.ar` module was introduced that allows
extraction of UNIX ar archive contents.
* A new :mod:`avocado.utils.sysinfo` module that powers the sysinfo
feature, but is now also accessible to job/test writers.
* Times related to the duration of tasks are now limited to nanosecond
precision to improve readability.
* A new module :mod:`avocado.utils.dmesg` with utilities for
interacting with the kernel ring buffer messages.
* A new utility :func:`avocado.utils.linux.is_selinux_enforcing`
allows quick check of SELinux enforcing status.
* The :mod:`avocado.utils.pmem` library introduced a number of new
utility methods, adding support for daxctl operations such as
``offline-memory``, ``online-memory``, and ``reconfigure-device``.
* :meth:`avocado.utils.software_manager.SoftwareManager.extract_from_package`
is a new method that lets users extract the content of supported
package types (currently RPM and DEB).
* :mod:`avocado.utils.pci` now accommodates newer slot names.
* :mod:`avocado.utils.memory` now properly handles the 16GB hugepages
with both the HASH and Radix MMU (by removing the check in case
Radix is used).
* The :mod:`avocado.utils.cloudinit` module will give a better error
message when the system is not capable of creating ISO images, with
a solution for resolution.
* Various documentation improvements for the
:mod:`avocado.core.multipath` module.
* The :mod:`avocado.utils.partition` utility module now properly keeps
track of loop devices and multiple mounts per device.
* A specific exception, and thus a clearer error message, is now used
when a command with an empty string is given to
:func:`avocado.utils.process.run`.
:mod:`avocado.utils.ssh`
~~~~~~~~~~~~~~~~~~~~~~~~
* :class:`avocado.utils.ssh.Session` now contains a
:meth:`avocado.utils.ssh.Session.cleanup_master` method and a
:attr:`avocado.utils.ssh.Session.control_master` property.
* :mod:`avocado.utils.ssh` now respects the username set when copying
files via ``scp``.
:mod:`avocado.utils.vmimage`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :mod:`avocado.utils.vmimage` can now access both current and
non-current Fedora versions (which are hosted at different
locations).
* :func:`avocado.utils.vmimage.get` is now deprecated in favor of
:meth:`avocado.utils.vmimage.Image.from_parameters`
:mod:`avocado.utils.network`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :mod:`avocado.utils.network.interfaces` now supports setting
configuration for SUSE-based systems.
* :class:`avocado.utils.network.interfaces.NetworkInterface` can now
access and present information on interfaces that do not have an IP
address assigned to them.
* The :mod:`avocado.utils.network.hosts` won’t consider
bonding_masters anymore, a file that may exist at
``/sys/class/net``, as the name of an interface.
* The :mod:`avocado.utils.network.interfaces` now support
configuration files compatible with SUSE distributions.
* :meth:`avocado.utils.network.interfaces.NetworkInterface.remove_link`
is a new utility method that allows one to delete a virtual
interface link.
* :meth:`avocado.utils.network.hosts.Host.get_default_route_interface` is a
new utility method that allows one to get a list of default routes
interfaces.
:mod:`avocado.utils.cpu`
~~~~~~~~~~~~~~~~~~~~~~~~
* The :mod:`avocado.utils.cpu` now makes available mapping of vendor
names to the data that matches in ``/proc/cpuinfo`` on that vendor’s
CPUs (:attr:`avocado.utils.cpu.VENDORS_MAP`). This allows users to
have visibility about the logic used to determine the vendor’s name,
and overwrite it if needed.
* The :mod:`avocado.utils.cpu` library now properly handles the s390x
z13 family of CPUs.
:mod:`avocado.utils.distro`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :mod:`avocado.utils.distro:` can now detect the distribution on remote
machines.
* The :mod:`avocado.utils.distro:` will now correctly return a
``avocado.utils.distro.UNKNOWN_DISTRO`` on non UNIX systems, instead of
crashing.
Complete list of changes
------------------------
For a complete list of changes between the last LTS release (82.1) and
this release, please check out `the Avocado commit changelog
<https://github.com/avocado-framework/avocado/compare/82.1...92.0>`_.