Repository files navigation

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 inPython and they follow theunittest pattern, but any executable canserve as a test.

You should first experience Avocado by using the test runner, that is, thecommand line tool that will conveniently run your tests and collect theirresults.

To do so, please runavocado with therun sub-command followed by atest reference, which could be either a path to the file, or a recognizablename:

$ avocado run /bin/trueJOB ID     : e0134e010afa18b55d93276ac2a790dc38db7948JOB 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 0JOB HTML   : $HOME/avocado/job-results/job-2023-09-06T10.55-e0134e0/results.htmlJOB TIME   : 1.52 s

You probably noticed that we used/bin/true as a test, and in accordancewith our expectations, it passed! These are known asexec-test, but thereis also another type of test, which we callinstrumented tests.

A regular run of Avocado will present the test results on standard output, anice and colored report useful for human beings. But results for machines canalso be generated.

Check the job-results folder ($HOME/avocado/job-results/latest/) to see theoutputs.

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 pluginoutputs 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 outputsthis one is streamlined (per test results).

When it comes to outputs, Avocado is very flexible. You can check the variousoutput plugins. If you need something more sophisticated, visit ourpluginssection.

Avocado comes with a sysinfo plugin, which automatically gathers some systeminformation per each job or even between tests. This is very helpful whentrying 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 theAvocado User's Guide.

In order to reproduce a given job using the same data, one can use thereplay subcommand, informing the hash id from the original job to bereplayed. The hash id can be partial, as long as the provided part correspondsto 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 willreplay the latest job executed.

Example:

$ avocado replay 825b86JOB ID     : 55a0d10132c02b8cc87deb2b480bfd8abbd956c3SRC JOB ID : 825b860b0c2f6ec48953c638432e3e323f8d7cadJOB 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 0JOB TIME   : 0.11 sJOB 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 givenjobs. The basic usage is:

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

Avocado has a plugin system that can be used to extend it in a clean way. Theavocado command line tool has a builtinplugins command that lets youlist available plugins. The usage is pretty simple:

$ avocado pluginsPlugins 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' subcommandjournal Journal options for the 'run' subcommand...

For more information about plugins, please visit thePlugin System section ontheAvocado User's Guide.

When writing tests, developers often need to perform basic tasks on OS and endup having to implement these routines just to run they tests.

Avocado hasmore than 40utility modules that helps you to perform basicoperations.

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.

If the command-line is limiting you, then you can use our new API andcreate custom jobs and test suites:

importsysfromavocado.core.jobimportJobwithJob.from_config({'resolver.references': ['/bin/true']})asjob:sys.exit(job.run())

It is super easy, just run the follow command:

$ pip3 install --user avocado-framework

This will install the avocado command in your home directory.

Please use the following links for full documentation, including installationmethods, tutorials and API or browse this site for more content.

• latest release
• development version

Please use theGitHub issue tracker to submit bugs or request features.

Please consult theAvocado Releases for fixes and enhancements of each version.

Except where otherwise indicated in a given source file, all originalcontributions to Avocado are licensed under the GNU General Public Licenseversion 2(GPLv2) or any laterversion.

By contributing you agree that these contributions are your own (or approved byyour employer) and you grant a full, complete, irrevocable copyright license toall users and developers of the Avocado project, present and future, pursuantto the license of the project.