==================
Welcome to Avocado
==================
Avocado is a set of tools and libraries to help with automated testing.
One can call it a test framework with benefits. Native tests are written in
Python and they follow the ``unittest`` pattern, but any executable can
serve as a test.
How does it work?
=================
You should first experience Avocado by using the test runner, that is, the
command line tool that will conveniently run your tests and collect their
results.
To do so, please run ``avocado`` with the ``run`` sub-command followed by a
test reference, which could be either a path to the file, or a recognizable
name::
$ avocado run /bin/true
JOB ID : e0134e010afa18b55d93276ac2a790dc38db7948
JOB LOG : $HOME/avocado/job-results/job-2023-09-06T10.55-e0134e0/job.log
(1/1) /bin/true: STARTED
(1/1) /bin/true: PASS (0.02 s)
RESULTS : PASS 1 | ERROR 0 | FAIL 0 | SKIP 0 | WARN 0 | INTERRUPT 0 | CANCEL 0
JOB HTML : $HOME/avocado/job-results/job-2023-09-06T10.55-e0134e0/results.html
JOB TIME : 1.52 s
You probably noticed that we used ``/bin/true`` as a test, and in accordance
with our expectations, it passed! These are known as **exec-test**, but there
is also another type of test, which we call **instrumented tests**.
.. tip:: See more at the `Test types`_ section on the `Avocado User's Guide`_.
Why should I use it?
====================
Multiple result formats
-----------------------
A regular run of Avocado will present the test results on standard output, a
nice and colored report useful for human beings. But results for machines can
also be generated.
Check the job-results folder (``$HOME/avocado/job-results/latest/``) to see the
outputs.
Currently we support, out of box, the following output formats:
* **xUnit**: an XML format that contains test results in a structured form,
and are used by other test automation projects, such as jenkins.
* **JSON**: a widely used data exchange format. The JSON Avocado plugin
outputs job information, similarly to the xunit output plugin.
* **TAP**: Provides the basic TAP (`Test Anything Protocol`_) results,
currently in v12. Unlike most existing Avocado machine readable outputs
this one is streamlined (per test results).
.. note:: You can see the results of the latest job inside the folder
``$HOME/avocado/job-results/latest/``. You can also specify at the command line
the options ``--xunit``, ``--json`` or ``--tap`` followed by a filename.
Avocado will write the output on the specified filename.
When it comes to outputs, Avocado is very flexible. You can check the various
**output plugins**. If you need something more sophisticated, visit our `plugins
section`_.
Sysinfo data collector
----------------------
Avocado comes with a sysinfo plugin, which automatically gathers some system
information per each job or even between tests. This is very helpful when
trying to identify the cause of a test failure.
Check out the files stored at ``$HOME/avocado/job-results/latest/sysinfo/``::
$ ls $HOME/avocado/job-results/latest/sysinfo/pre/
'brctl show' hostname modules
cmdline 'ifconfig -a' mounts
cpuinfo installed_packages 'numactl --hardware show'
current_clocksource interrupts partitions
'df -mP' 'ip link' scaling_governor
dmesg 'ld --version' 'uname -a'
dmidecode lscpu uptime
'fdisk -l' 'lspci -vvnn' version
'gcc --version' meminfo
For more information about sysinfo collector, please consult the `Avocado User's Guide`_.
Job Replay and Job Diff
-----------------------
In order to reproduce a given job using the same data, one can use the
``replay`` subcommand, informing the hash id from the original job to be
replayed. The hash id can be partial, as long as the provided part corresponds
to the initial characters of the original job id and it is also unique enough.
Or, instead of the job id, you can use the string latest and Avocado will
replay the latest job executed.
Example::
$ avocado replay 825b86
JOB ID : 55a0d10132c02b8cc87deb2b480bfd8abbd956c3
SRC JOB ID : 825b860b0c2f6ec48953c638432e3e323f8d7cad
JOB LOG : $HOME/avocado/job-results/job-2016-01-11T16.18-55a0d10/job.log
(1/2) /bin/true: PASS (0.01 s)
(2/2) /bin/false: FAIL (0.01 s)
RESULTS : PASS 1 | ERROR 0 | FAIL 1 | SKIP 0 | WARN 0 | INTERRUPT 0
JOB TIME : 0.11 s
JOB HTML : $HOME/avocado/job-results/job-2016-01-11T16.18-55a0d10/html/results.html
Avocado Diff plugin allows users to easily compare several aspects of two given
jobs. The basic usage is:
.. code-block:: diff
$ avocado diff 7025aaba 384b949c
--- 7025aaba9c2ab8b4bba2e33b64db3824810bb5df
+++ 384b949c991b8ab324ce67c9d9ba761fd07672ff
@@ -1,15 +1,15 @@
COMMAND LINE
-/usr/bin/avocado run sleeptest.py
+/usr/bin/avocado run passtest.py
TOTAL TIME
-1.00 s
+0.00 s
TEST RESULTS
-1-sleeptest.py:SleepTest.test: PASS
+1-passtest.py:PassTest.test: PASS
...
Extensible by plugins
---------------------
Avocado has a plugin system that can be used to extend it in a clean way. The
``avocado`` command line tool has a builtin ``plugins`` command that lets you
list available plugins. The usage is pretty simple::
$ avocado plugins
Plugins that add new commands (avocado.plugins.cli.cmd):
exec-path Returns path to Avocado bash libraries and exits.
run Run one or more tests (native test, test alias, binary or script)
sysinfo Collect system information
...
Plugins that add new options to commands (avocado.plugins.cli):
remote Remote machine options for 'run' subcommand
journal Journal options for the 'run' subcommand
...
For more information about plugins, please visit the `Plugin System`_ section on
the `Avocado User's Guide`_.
Utility libraries
-----------------
When writing tests, developers often need to perform basic tasks on OS and end
up having to implement these routines just to run they tests.
Avocado has **more than 40** *utility modules* that helps you to perform basic
operations.
Below a small subset of our utility modules:
* **utils.vmimage**: This utility provides a API to download/cache VM images
(QCOW) from the official distributions repositories.
* **utils.memory**: Provides information about memory usage.
* **utils.cpu**: Get information from the current's machine CPU.
* **utils.software_manager**: Software package management library.
* **utils.download**: Methods to download URLs and regular files.
* **utils.archive**: Module to help extract and create compressed archives.
Avocado Python API
==================
If the command-line is limiting you, then you can use our new API and
create custom jobs and test suites:
.. code-block:: python
import sys
from avocado.core.job import Job
with Job.from_config({'resolver.references': ['/bin/true']}) as job:
sys.exit(job.run())
How to install
==============
It is super easy, just run the follow command::
$ pip3 install --user avocado-framework
This will install the avocado command in your home directory.
.. note:: For more details and alternative methods, please visit the
`Installing section on Avocado User’s Guide`_
Documentation
=============
Please use the following links for full documentation, including installation
methods, tutorials and API or browse this site for more content.
* `latest release <https://avocado-framework.readthedocs.io/>`_
* `development version <https://avocado-framework.readthedocs.io/en/latest/>`_
Bugs/Requests
=============
Please use the `GitHub issue tracker`_ to submit bugs or request features.
Changelog
=========
Please consult the `Avocado Releases`_ for fixes and enhancements of each version.
License
=======
Except where otherwise indicated in a given source file, all original
contributions to Avocado are licensed under the GNU General Public License
version 2 `(GPLv2) <https://www.gnu.org/licenses/gpl-2.0.html>`_ or any later
version.
By contributing you agree that these contributions are your own (or approved by
your employer) and you grant a full, complete, irrevocable copyright license to
all users and developers of the Avocado project, present and future, pursuant
to the license of the project.
Build and Quality Status
========================
.. image:: https://copr.fedorainfracloud.org/coprs/g/avocado/avocado-latest/package/python-avocado/status_image/last_build.png
:target: https://copr.fedorainfracloud.org/coprs/g/avocado/avocado-latest/package/python-avocado/
:alt: Copr build
.. image:: https://api.codeclimate.com/v1/badges/03f506164e1d19f95480/maintainability
:target: https://codeclimate.com/github/avocado-framework/avocado/maintainability
:alt: Code Climate Maintainability
.. image:: https://readthedocs.org/projects/avocado-framework/badge/?version=latest
:target: https://avocado-framework.readthedocs.io/en/latest/
:alt: Documentation Status
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code Style checking by Black
.. _Avocado User's Guide: https://avocado-framework.readthedocs.io/en/latest/guides/user/index.html
.. _Installing section on Avocado User’s Guide: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html#installing
.. _Test types: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/concepts.html#test-types
.. _plugins section: https://avocado-framework.readthedocs.io/en/latest/plugins/index.html
.. _Plugin System: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/plugins.html
.. _Avocado Releases: https://avocado-framework.readthedocs.io/en/latest/releases/index.html
.. _GitHub issue tracker: https://github.com/avocado-framework/avocado/issues
.. _Test Anything Protocol: https://testanything.org/
Raw data
{
"_id": null,
"home_page": "https://avocado-framework.github.io/",
"name": "avocado-framework",
"maintainer": "",
"docs_url": "https://pythonhosted.org/avocado-framework/",
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Avocado Developers",
"author_email": "avocado-devel@redhat.com",
"download_url": "https://files.pythonhosted.org/packages/11/01/99b73af4d852483f6b3e9ecd660385105b0023cb43cd4ca3b09f41fb9f1d/avocado-framework-104.0.tar.gz",
"platform": null,
"description": "==================\nWelcome to Avocado\n==================\n\nAvocado is a set of tools and libraries to help with automated testing.\n\nOne can call it a test framework with benefits. Native tests are written in\nPython and they follow the ``unittest`` pattern, but any executable can\nserve as a test.\n\nHow does it work?\n=================\n\nYou should first experience Avocado by using the test runner, that is, the\ncommand line tool that will conveniently run your tests and collect their\nresults.\n\nTo do so, please run ``avocado`` with the ``run`` sub-command followed by a\ntest reference, which could be either a path to the file, or a recognizable\nname::\n\n $ avocado run /bin/true\n JOB ID : e0134e010afa18b55d93276ac2a790dc38db7948\n JOB LOG : $HOME/avocado/job-results/job-2023-09-06T10.55-e0134e0/job.log\n (1/1) /bin/true: STARTED\n (1/1) /bin/true: PASS (0.02 s)\n RESULTS : PASS 1 | ERROR 0 | FAIL 0 | SKIP 0 | WARN 0 | INTERRUPT 0 | CANCEL 0\n JOB HTML : $HOME/avocado/job-results/job-2023-09-06T10.55-e0134e0/results.html\n JOB TIME : 1.52 s\n\nYou probably noticed that we used ``/bin/true`` as a test, and in accordance\nwith our expectations, it passed! These are known as **exec-test**, but there\nis also another type of test, which we call **instrumented tests**.\n\n.. tip:: See more at the `Test types`_ section on the `Avocado User's Guide`_.\n\nWhy should I use it?\n====================\n\nMultiple result formats\n-----------------------\n\nA regular run of Avocado will present the test results on standard output, a\nnice and colored report useful for human beings. But results for machines can\nalso be generated.\n\nCheck the job-results folder (``$HOME/avocado/job-results/latest/``) to see the\noutputs.\n\nCurrently we support, out of box, the following output formats:\n\n* **xUnit**: an XML format that contains test results in a structured form,\n and are used by other test automation projects, such as jenkins.\n\n* **JSON**: a widely used data exchange format. The JSON Avocado plugin\n outputs job information, similarly to the xunit output plugin.\n\n* **TAP**: Provides the basic TAP (`Test Anything Protocol`_) results,\n currently in v12. Unlike most existing Avocado machine readable outputs\n this one is streamlined (per test results).\n\n.. note:: You can see the results of the latest job inside the folder\n ``$HOME/avocado/job-results/latest/``. You can also specify at the command line\n the options ``--xunit``, ``--json`` or ``--tap`` followed by a filename.\n Avocado will write the output on the specified filename.\n\nWhen it comes to outputs, Avocado is very flexible. You can check the various\n**output plugins**. If you need something more sophisticated, visit our `plugins\nsection`_.\n\nSysinfo data collector\n----------------------\n\nAvocado comes with a sysinfo plugin, which automatically gathers some system\ninformation per each job or even between tests. This is very helpful when\ntrying to identify the cause of a test failure.\n\nCheck out the files stored at ``$HOME/avocado/job-results/latest/sysinfo/``::\n\n $ ls $HOME/avocado/job-results/latest/sysinfo/pre/\n 'brctl show' hostname modules\n cmdline 'ifconfig -a' mounts\n cpuinfo installed_packages 'numactl --hardware show'\n current_clocksource interrupts partitions\n 'df -mP' 'ip link' scaling_governor\n dmesg 'ld --version' 'uname -a'\n dmidecode lscpu uptime\n 'fdisk -l' 'lspci -vvnn' version\n 'gcc --version' meminfo\n\n\nFor more information about sysinfo collector, please consult the `Avocado User's Guide`_.\n\nJob Replay and Job Diff\n-----------------------\n\nIn order to reproduce a given job using the same data, one can use the\n``replay`` subcommand, informing the hash id from the original job to be\nreplayed. The hash id can be partial, as long as the provided part corresponds\nto the initial characters of the original job id and it is also unique enough.\nOr, instead of the job id, you can use the string latest and Avocado will\nreplay the latest job executed.\n\nExample::\n\n $ avocado replay 825b86\n JOB ID : 55a0d10132c02b8cc87deb2b480bfd8abbd956c3\n SRC JOB ID : 825b860b0c2f6ec48953c638432e3e323f8d7cad\n JOB LOG : $HOME/avocado/job-results/job-2016-01-11T16.18-55a0d10/job.log\n (1/2) /bin/true: PASS (0.01 s)\n (2/2) /bin/false: FAIL (0.01 s)\n RESULTS : PASS 1 | ERROR 0 | FAIL 1 | SKIP 0 | WARN 0 | INTERRUPT 0\n JOB TIME : 0.11 s\n JOB HTML : $HOME/avocado/job-results/job-2016-01-11T16.18-55a0d10/html/results.html\n\nAvocado Diff plugin allows users to easily compare several aspects of two given\njobs. The basic usage is:\n\n.. code-block:: diff\n\n $ avocado diff 7025aaba 384b949c\n --- 7025aaba9c2ab8b4bba2e33b64db3824810bb5df\n +++ 384b949c991b8ab324ce67c9d9ba761fd07672ff\n @@ -1,15 +1,15 @@\n\n COMMAND LINE\n -/usr/bin/avocado run sleeptest.py\n +/usr/bin/avocado run passtest.py\n\n TOTAL TIME\n -1.00 s\n +0.00 s\n\n TEST RESULTS\n -1-sleeptest.py:SleepTest.test: PASS\n +1-passtest.py:PassTest.test: PASS\n\n ...\n\n\nExtensible by plugins\n---------------------\n\nAvocado has a plugin system that can be used to extend it in a clean way. The\n``avocado`` command line tool has a builtin ``plugins`` command that lets you\nlist available plugins. The usage is pretty simple::\n\n $ avocado plugins\n Plugins that add new commands (avocado.plugins.cli.cmd):\n exec-path Returns path to Avocado bash libraries and exits.\n run Run one or more tests (native test, test alias, binary or script)\n sysinfo Collect system information\n ...\n Plugins that add new options to commands (avocado.plugins.cli):\n remote Remote machine options for 'run' subcommand\n journal Journal options for the 'run' subcommand\n ...\n\nFor more information about plugins, please visit the `Plugin System`_ section on\nthe `Avocado User's Guide`_.\n\nUtility libraries\n-----------------\n\nWhen writing tests, developers often need to perform basic tasks on OS and end\nup having to implement these routines just to run they tests.\n\nAvocado has **more than 40** *utility modules* that helps you to perform basic\noperations.\n\nBelow a small subset of our utility modules:\n\n* **utils.vmimage**: This utility provides a API to download/cache VM images\n (QCOW) from the official distributions repositories.\n* **utils.memory**: Provides information about memory usage.\n* **utils.cpu**: Get information from the current's machine CPU.\n* **utils.software_manager**: Software package management library.\n* **utils.download**: Methods to download URLs and regular files.\n* **utils.archive**: Module to help extract and create compressed archives.\n\nAvocado Python API\n==================\n\nIf the command-line is limiting you, then you can use our new API and\ncreate custom jobs and test suites:\n\n.. code-block:: python\n\n import sys\n\n from avocado.core.job import Job\n\n with Job.from_config({'resolver.references': ['/bin/true']}) as job:\n sys.exit(job.run())\n\nHow to install\n==============\n\nIt is super easy, just run the follow command::\n\n $ pip3 install --user avocado-framework\n\nThis will install the avocado command in your home directory.\n\n.. note:: For more details and alternative methods, please visit the\n `Installing section on Avocado User\u2019s Guide`_\n\nDocumentation\n=============\n\nPlease use the following links for full documentation, including installation\nmethods, tutorials and API or browse this site for more content.\n\n* `latest release <https://avocado-framework.readthedocs.io/>`_\n\n* `development version <https://avocado-framework.readthedocs.io/en/latest/>`_\n\nBugs/Requests\n=============\n\nPlease use the `GitHub issue tracker`_ to submit bugs or request features.\n\nChangelog\n=========\n\nPlease consult the `Avocado Releases`_ for fixes and enhancements of each version.\n\nLicense\n=======\n\nExcept where otherwise indicated in a given source file, all original\ncontributions to Avocado are licensed under the GNU General Public License\nversion 2 `(GPLv2) <https://www.gnu.org/licenses/gpl-2.0.html>`_ or any later\nversion.\n\nBy contributing you agree that these contributions are your own (or approved by\nyour employer) and you grant a full, complete, irrevocable copyright license to\nall users and developers of the Avocado project, present and future, pursuant\nto the license of the project.\n\nBuild and Quality Status\n========================\n\n.. image:: https://copr.fedorainfracloud.org/coprs/g/avocado/avocado-latest/package/python-avocado/status_image/last_build.png\n :target: https://copr.fedorainfracloud.org/coprs/g/avocado/avocado-latest/package/python-avocado/\n :alt: Copr build\n\n.. image:: https://api.codeclimate.com/v1/badges/03f506164e1d19f95480/maintainability\n :target: https://codeclimate.com/github/avocado-framework/avocado/maintainability\n :alt: Code Climate Maintainability\n\n.. image:: https://readthedocs.org/projects/avocado-framework/badge/?version=latest\n :target: https://avocado-framework.readthedocs.io/en/latest/\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code Style checking by Black\n\n\n.. _Avocado User's Guide: https://avocado-framework.readthedocs.io/en/latest/guides/user/index.html\n.. _Installing section on Avocado User\u2019s Guide: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html#installing\n.. _Test types: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/concepts.html#test-types\n.. _plugins section: https://avocado-framework.readthedocs.io/en/latest/plugins/index.html\n.. _Plugin System: https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/plugins.html\n.. _Avocado Releases: https://avocado-framework.readthedocs.io/en/latest/releases/index.html\n.. _GitHub issue tracker: https://github.com/avocado-framework/avocado/issues\n.. _Test Anything Protocol: https://testanything.org/\n",
"bugtrack_url": null,
"license": "GPLv2+",
"summary": "Avocado Test Framework",
"version": "104.0",
"project_urls": {
"Homepage": "https://avocado-framework.github.io/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "64e5c9f0452271057e7b8052e5c60ba0d56e1656cc7c41dd6f043e71c9aba9de",
"md5": "88b0dbfef42fe1f47d24fc609452353f",
"sha256": "cb77eb93a8e84264e47419835d7bb8a67a30ef2e9f9eef5eecd84f10b76128cf"
},
"downloads": -1,
"filename": "avocado_framework-104.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88b0dbfef42fe1f47d24fc609452353f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 445459,
"upload_time": "2024-03-19T19:27:24",
"upload_time_iso_8601": "2024-03-19T19:27:24.181038Z",
"url": "https://files.pythonhosted.org/packages/64/e5/c9f0452271057e7b8052e5c60ba0d56e1656cc7c41dd6f043e71c9aba9de/avocado_framework-104.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "110199b73af4d852483f6b3e9ecd660385105b0023cb43cd4ca3b09f41fb9f1d",
"md5": "79ada54b90e0911ecb9f66c11dbd1a8e",
"sha256": "6f1894cd241dd8cc0d5bb7ca5bae314307a8cb1ff630fd9c97447c6af4e520c0"
},
"downloads": -1,
"filename": "avocado-framework-104.0.tar.gz",
"has_sig": false,
"md5_digest": "79ada54b90e0911ecb9f66c11dbd1a8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1040275,
"upload_time": "2024-03-19T19:26:33",
"upload_time_iso_8601": "2024-03-19T19:26:33.148629Z",
"url": "https://files.pythonhosted.org/packages/11/01/99b73af4d852483f6b3e9ecd660385105b0023cb43cd4ca3b09f41fb9f1d/avocado-framework-104.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-19 19:26:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "avocado-framework"
}
JSON