Avocado’s Configuration Reference

This is current Avocado Configuration reference. You can adjust the values by two ways:

  • Configuration file options;

  • Command-line options (when available)

Some options that are used often are available for your convenience also at the command-line.

This list has all options registered with Avocado so far.

Note

Please, keep in mind that we are in constant evolution and doing a huge improvements on how to configure Avocado, some options here can be changed in the near future.

assets.fetch.ignore_errors

always return success for the fetch command.

  • Default: False

  • Type: <class ‘bool’>

assets.fetch.references

Path to avocado instrumented test

  • Default: []

  • Type: <class ‘list’>

assets.fetch.timeout

Timeout to be used when download an asset.

  • Default: 300

  • Type: <class ‘int’>

assets.list.days

How old (in days) should Avocado look for assets?

  • Default: None

  • Type: <class ‘int’>

assets.list.overall_limit

Filter will be based on a overall system limit threshold in bytes (with assets ordered by last access) or with a suffix unit. Valid suffixes are: b,k,m,g,t

  • Default: None

  • Type: <class ‘str’>

assets.list.size_filter

Apply action based on a size filter (comparison operator + value) in bytes. Ex ‘>20’, ‘<=200’. Supported operators: ==, <, >, <=, >=

  • Default: None

  • Type: <class ‘str’>

assets.purge.days

How old (in days) should Avocado look for assets?

  • Default: None

  • Type: <class ‘int’>

assets.purge.overall_limit

Filter will be based on a overall system limit threshold in bytes (with assets ordered by last access) or with a suffix unit. Valid suffixes are: b,k,m,g,t

  • Default: None

  • Type: <class ‘str’>

assets.purge.size_filter

Apply action based on a size filter (comparison operator + value) in bytes. Ex ‘>20’, ‘<=200’. Supported operators: ==, <, >, <=, >=

  • Default: None

  • Type: <class ‘str’>

assets.register.name

Unique name to associate with this asset.

  • Default: None

  • Type: <class ‘str’>

assets.register.sha1_hash

SHA1 hash of this asset.

  • Default: None

  • Type: <class ‘str’>

assets.register.url

Path to asset that you would like to register manually.

  • Default: None

  • Type: <class ‘str’>

cache.clear

Clear avocado cache, you can specify which part of cache will be removed.

  • Default: []

  • Type: <class ‘list’>

cache.list

List metadata in avocado cache

  • Default: []

  • Type: <class ‘list’>

config.datadir

Shows the data directories currently being used by Avocado

  • Default: False

  • Type: <class ‘bool’>

core.paginator

Turn the paginator on. Useful when output is too long.

  • Default: False

  • Type: <class ‘bool’>

core.show

List of comma separated builtin logs, or logging streams optionally followed by LEVEL (DEBUG,INFO,…). Builtin streams are: “app”: application output; “test”: test output; “job”: job output; “early”: early logging of other streams, including test (very verbose); “all”: all builtin streams; “none”: disables regular output (leaving only errors enabled). By default: ‘app’

  • Default: {‘app’}

  • Type: <function register_core_options.<locals>.<lambda> at 0x7f70f036a5c0>

core.verbose

Some commands can produce more information. This option will enable the verbosity when applicable.

  • Default: False

  • Type: <class ‘bool’>

datadir.paths.base_dir

Base directory for Avocado tests and auxiliary data

  • Default: /home/docs/avocado

  • Type: <function prepend_base_path at 0x7f70f036ab60>

datadir.paths.cache_dirs

Cache directories to be used by the avocado test

  • Default: [‘/home/docs/avocado/data/cache’]

  • Type: <class ‘list’>

datadir.paths.data_dir

Data directory for Avocado

  • Default: /home/docs/avocado/data

  • Type: <function prepend_base_path at 0x7f70f036ab60>

datadir.paths.logs_dir

Logs directory for Avocado

  • Default: /home/docs/avocado/job-results

  • Type: <function prepend_base_path at 0x7f70f036ab60>

datadir.paths.test_dir

Test directory for Avocado tests

  • Default: /usr/share/doc/avocado/tests

  • Type: <function prepend_base_path at 0x7f70f036ab60>

diff.create_reports

Create temporary files with job reports to be used by other diff tools

  • Default: False

  • Type: <class ‘bool’>

diff.filter

Comma separated filter of diff sections: (no)cmdline,(no)time,(no)variants,(no)results, (no)config,(no)sysinfo (defaults to all enabled).

  • Default: [‘cmdline’, ‘time’, ‘variants’, ‘results’, ‘config’, ‘sysinfo’]

  • Type: <function Diff._validate_filters at 0x7f70eee363e0>

diff.html

Enable HTML output to the FILE where the result should be written.

  • Default: None

  • Type: <class ‘str’>

diff.jobids

A job reference, identified by a (partial) unique ID (SHA1) or test results directory.

  • Default: []

  • Type: <class ‘list’>

diff.open_browser

Generate and open a HTML report in your preferred browser. If no –html file is provided, create a temporary file.

  • Default: False

  • Type: <class ‘bool’>

diff.strip_id

Strip the “id” from “id-name;variant” when comparing test results.

  • Default: False

  • Type: <class ‘bool’>

distro.distro_def_arch

Primary architecture that the distro targets

  • Default:

  • Type: <class ‘str’>

distro.distro_def_create

Creates a distro definition file based on the path given.

  • Default: False

  • Type: <class ‘bool’>

distro.distro_def_name

Distribution short name

  • Default:

  • Type: <class ‘str’>

distro.distro_def_path

Top level directory of the distro installation files

  • Default:

  • Type: <class ‘str’>

distro.distro_def_release

Distribution release version number

  • Default:

  • Type: <class ‘str’>

distro.distro_def_type

Distro type (one of: rpm, deb)

  • Default:

  • Type: <class ‘str’>

distro.distro_def_version

Distribution major version name

  • Default:

  • Type: <class ‘str’>

filter.by_tags.include_empty

Include all tests without tags during filtering. This effectively means they will be kept in the test suite found previously to filtering.

  • Default: False

  • Type: <class ‘bool’>

filter.by_tags.include_empty_key

Include all tests that do not have a matching key in its key:val tags. This effectively means those tests will be kept in the test suite found previously to filtering.

  • Default: False

  • Type: <class ‘bool’>

filter.by_tags.tags

Filter tests based on tags

  • Default: []

  • Type: <class ‘list’>

human_ui.omit.statuses

Status that will be omitted from the Human UI. Valid statuses: SKIP, ERROR, FAIL, WARN, PASS, INTERRUPTED, CANCEL, STARTED

  • Default: []

  • Type: <class ‘list’>

job.output.loglevel

Sets the base log level of the output generated by the job, which is also the base logging level for the –show command line option. Any of the Python logging levels names are allowed here. Examples: DEBUG, INFO, WARNING, ERROR, CRITICAL. For more information refer to: https://docs.python.org/3/library/logging.html#levels

  • Default: DEBUG

  • Type: <class ‘str’>

job.output.testlogs.logfiles

The specific log files that will be shown for tests whose exit status match the ones defined in the “job.output.testlogs.statuses” configuration.

  • Default: [‘debug.log’]

  • Type: <class ‘list’>

job.output.testlogs.statuses

Status that will trigger the output of a test’s logs after the job ends. Valid statuses: SKIP, ERROR, FAIL, WARN, PASS, INTERRUPTED, CANCEL

  • Default: []

  • Type: <class ‘list’>

job.output.testlogs.summary_statuses

Status that will trigger the output of a summary after the job ends. This is useful to list failed tests for instances at the end of a job run. Valid statuses: SKIP, ERROR, FAIL, WARN, PASS, INTERRUPTED, CANCEL

  • Default: [‘ERROR’, ‘FAIL’, ‘INTERRUPTED’]

  • Type: <class ‘list’>

job.replay.source_job_id

Replays a job, identified by: complete or partial Job ID, “latest” for the latest job, the job results path.

  • Default: latest

  • Type: <class ‘str’>

job.run.result.json.enabled

Enables default JSON result in the job results directory. File will be named “results.json”.

  • Default: True

  • Type: <class ‘bool’>

job.run.result.json.output

Enable JSON result format and write it to FILE. Use “-” to redirect to the standard output.

  • Default: None

  • Type: <class ‘str’>

job.run.result.tap.enabled

Enables default TAP result in the job results directory. File will be named “results.tap”

  • Default: True

  • Type: <class ‘bool’>

job.run.result.tap.include_logs

Include test logs as comments in TAP output.

  • Default: False

  • Type: <class ‘bool’>

job.run.result.tap.output

Enable TAP result output and write it to FILE. Use “-” to redirect to standard output.

  • Default: None

  • Type: <class ‘str’>

job.run.result.xunit.enabled

Enables default xUnit result in the job results directory. File will be named “results.xml”.

  • Default: True

  • Type: <class ‘bool’>

job.run.result.xunit.job_name

Override the reported job name. By default uses the Avocado job name which is always unique. This is useful for reporting in Jenkins as it only evaluates first-failure from jobs of the same name.

  • Default: None

  • Type: <class ‘str’>

job.run.result.xunit.max_test_log_chars

Limit the attached job log to given number of characters (k/m/g suffix allowed)

  • Default: 100000

  • Type: <function XUnitInit.initialize.<locals>.<lambda> at 0x7f70eef75a80>

job.run.result.xunit.output

Enable xUnit result format and write it to FILE. Use “-” to redirect to the standard output.

  • Default: None

  • Type: <class ‘str’>

job.run.store_logging_stream

Store given logging STREAMs in “$JOB_RESULTS_DIR/$STREAM.$LEVEL”.

  • Default: []

  • Type: <class ‘list’>

job.run.timeout

Set the maximum amount of time (in SECONDS) that tests are allowed to execute. Values <= zero means “no timeout”. You can also use suffixes, like: s (seconds), m (minutes), h (hours).

  • Default: 0

  • Type: <function time_to_seconds at 0x7f70ef33a480>

jobs.show.job_id

JOB id

  • Default: latest

  • Type: <class ‘str’>

json.variants.load

Load the Variants from a JSON serialized file

  • Default: None

  • Type: <class ‘str’>

list.recipes.write_to_directory

Writes runnable recipe files to a directory.

  • Default: None

  • Type: <class ‘str’>

list.write_to_json_file

Writes output to a json file.

  • Default: None

  • Type: <class ‘str’>

plugins.cache.order

Execution order for “plugins.cache” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.cli.cmd.order

Execution order for “plugins.cli.cmd” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.cli.order

Execution order for “plugins.cli” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.disable

Plugins that will not be loaded and executed

  • Default: []

  • Type: <class ‘list’>

plugins.init.order

Execution order for “plugins.init” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.job.prepost.order

Execution order for “plugins.job.prepost” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.jobscripts.post

Directory with scripts to be executed after a job is run

  • Default: /etc/avocado/scripts/job/post.d/

  • Type: <function prepend_base_path at 0x7f70f036ab60>

plugins.jobscripts.pre

Directory with scripts to be executed before a job is run

  • Default: /etc/avocado/scripts/job/pre.d/

  • Type: <function prepend_base_path at 0x7f70f036ab60>

plugins.jobscripts.warn_non_existing_dir

Warn if configured (or default) directory does not exist

  • Default: False

  • Type: <class ‘bool’>

plugins.jobscripts.warn_non_zero_status

Warn if any script run return non-zero status

  • Default: True

  • Type: <class ‘bool’>

plugins.ordered_list

Will list the plugins in execution order

  • Default: False

  • Type: <class ‘bool’>

plugins.resolver.order

Execution order for “plugins.resolver” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.result.order

Execution order for “plugins.result” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.result_events.order

Execution order for “plugins.result_events” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.runnable.runner.order

Execution order for “plugins.runnable.runner” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.skip_broken_plugin_notification

Suppress notification about broken plugins in the app standard error. Add the name of each broken plugin you want to suppress the notification in the list. (e.g. “avocado_result_html”)

  • Default: []

  • Type: <class ‘list’>

plugins.spawner.order

Execution order for “plugins.spawner” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.suite.runner.order

Execution order for “plugins.suite.runner” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.test.post.order

Execution order for “plugins.test.post” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.test.pre.order

Execution order for “plugins.test.pre” plugins

  • Default: []

  • Type: <class ‘list’>

plugins.varianter.order

Execution order for “plugins.varianter” plugins

  • Default: []

  • Type: <class ‘list’>

resolver.references

List of test references (aliases or paths)

  • Default: []

  • Type: <class ‘list’>

run.dict_variants

Load the Variants from Python dictionaries

  • Default: []

  • Type: <class ‘list’>

run.dict_variants.variant_id_keys

Configure the key that will be used to name the variant ID. If not set, will use all keys.

  • Default: []

  • Type: <class ‘list’>

run.dry_run.enabled

Instead of running the test only list them and log their params.

  • Default: False

  • Type: <class ‘bool’>

run.dry_run.no_cleanup

Do not automatically clean up temporary directories used by dry-run

  • Default: False

  • Type: <class ‘bool’>

run.execution_order

Defines the order of iterating through test suite and test variants

  • Default: variants-per-test

  • Type: <class ‘str’>

run.failfast

Enable the job interruption on first failed test.

  • Default: False

  • Type: <class ‘bool’>

run.ignore_missing_references

Force the job execution, even if some of the test references are not resolved to tests.

  • Default: False

  • Type: <class ‘bool’>

run.job_category

Categorizes this within a directory with the same name, by creating a link to the job result directory

  • Default: None

  • Type: <class ‘str’>

run.journal.enabled

Records test status changes (for use with avocado-journal-replay and avocado-server)

  • Default: False

  • Type: <class ‘bool’>

run.keep_tmp

Keep job temporary files (useful for avocado debugging).

  • Default: False

  • Type: <class ‘bool’>

run.log_test_data_directories

Logs the possible data directories for each test. This is helpful when writing new tests and not being sure where to put data files. Look for “Test data directories” in your test log

  • Default: False

  • Type: <class ‘bool’>

run.max_parallel_tasks

Number of maximum number tasks running in parallel. You can disable parallel execution by setting this to 1. Defaults to the amount of CPUs on this machine.

  • Default: 2

  • Type: <class ‘int’>

run.results.archive

Archive (ZIP) files generated by tests

  • Default: False

  • Type: <class ‘bool’>

run.results_dir

Forces to use of an alternate job results directory.

  • Default: None

  • Type: <class ‘str’>

run.shuffle

Shuffle the tasks to be executed

  • Default: False

  • Type: <class ‘bool’>

run.spawner

Spawn tasks in a specific spawner. Available spawners: ‘process’ and ‘podman’

  • Default: process

  • Type: <class ‘str’>

run.status_server_auto

If the status server should automatically choose a “status_server_listen” and “status_server_uri” configuration. Default is to auto configure a status server.

  • Default: True

  • Type: <class ‘bool’>

run.status_server_buffer_size

Buffer size that status server uses. This should generally not be a concern to most users, but it can be tuned in case a runner generates very large status messages, which is common if a test generates a lot of output. Default is 33554432 (32MiB)

  • Default: 33554432

  • Type: <class ‘int’>

run.status_server_listen

URI where status server will listen on. Usually a “HOST:PORT” string. This is only effective if “status_server_auto” is disabled. If “status_server_uri” is not set, the value from “status_server_listen ” will be used.

  • Default: 127.0.0.1:8888

  • Type: <class ‘str’>

run.status_server_uri

URI for connecting to the status server, usually a “HOST:PORT” string. Use this if your status server is in another host, or different port. This is only effective if “status_server_auto” is disabled. If “status_server_listen” is not set, the value from “status_server_uri” will be used.

  • Default: 127.0.0.1:8888

  • Type: <class ‘str’>

run.suite_runner

Selects the runner implementation from one of the installed and active implementations. You can run “avocado plugins” and find the list of valid runners under the “Plugins that run test suites on a job (runners)” section. Defaults to “nrunner”, which is the only runner that ships with core Avocado at this moment.

  • Default: nrunner

  • Type: <class ‘str’>

run.test_parameters

Parameter name and value to pass to all tests. This is only applicable when not using a varianter plugin. This option format must be given in the NAME=VALUE format, and may be given any number of times, or per parameter.

  • Default: []

  • Type: <function Run._test_parameter at 0x7f70ef0834c0>

run.unique_job_id

Forces the use of a particular job ID. Used internally when interacting with an avocado server. You should not use this option unless you know exactly what you’re doing

  • Default: None

  • Type: <class ‘str’>

runner.exectest.exitcodes.skip

Use a custom exit code list to consider a test as skipped. This is only used by exec-test runners. Default is [].

  • Default: []

  • Type: <class ‘list’>

runner.identifier_format

By default Avocado runners will use the {uri} of a test as its identifier. Use a custom f-string identifier in order to change it.

  • Default: {uri}

  • Type: <class ‘str’>

runner.output.color

Whether to force colored output to non-tty outputs (e.g. log files). Allowed values: auto, always, never

  • Default: auto

  • Type: <class ‘str’>

runner.output.colored

Whether to display colored output in terminals that support it

  • Default: True

  • Type: <class ‘bool’>

runner.task.interval.from_hard_termination_to_verification

The amount of time to wait between executing a more forceful termination of a task, and the verification of the actual termination. This may allow spawners to give the necessary time for their isolation models to fully terminate a task. Spawners are free to implement a behavior that is suitable to their isolation model, including ignoring this configuration.

  • Default: 0

  • Type: <class ‘int’>

runner.task.interval.from_soft_to_hard_termination

The amount of time to wait between asking nicely for a task to be terminated (say sending a signal) and proceeding with a more forceful termination. This may allow runners within tasks to perform clean ups. Spawners are free to implement a behavior that is suitable to their isolation model, including ignoring this configuration.

  • Default: 1

  • Type: <class ‘int’>

spawner.lxc.arch

Architecture of the LXC container

  • Default: i386

  • Type: <class ‘str’>

spawner.lxc.create_hook

Container creation hook command to customize optional new containers

  • Default:

  • Type: <class ‘str’>

spawner.lxc.dist

Distribution for the LXC container

  • Default: fedora

  • Type: <class ‘str’>

spawner.lxc.release

Release of the LXC container (depends on the choice of distro)

  • Default: 32

  • Type: <class ‘str’>

spawner.lxc.slots

List of already available container slots to spawn in

  • Default: []

  • Type: <class ‘list’>

spawner.podman.avocado_spawner_egg

Avocado egg path to be used during initial bootstrap of avocado inside the isolated environment. By default, Avocado will try to download (or get from cache) an egg from its repository. Please use a valid URL, including the protocol (for local files, use the “file:///” prefix).

  • Default: None

  • Type: <class ‘str’>

spawner.podman.bin

Path to the podman binary

  • Default: /usr/bin/podman

  • Type: <class ‘str’>

spawner.podman.image

Image name to use when creating the container. The first default choice is a container image matching the current OS. If unable to detect, default becomes the latest Fedora release. Default on this system: Ubuntu:22

  • Default: Ubuntu:22

  • Type: <class ‘str’>

sysinfo.collect.commands_timeout

Overall timeout to collect commands, when <=0 no timeout is enforced

  • Default: -1

  • Type: <class ‘int’>

sysinfo.collect.enabled

Enable or disable sysinfo collection (like hardware details, profiles, etc.)

  • Default: True

  • Type: <class ‘bool’>

sysinfo.collect.installed_packages

Whether to take a list of installed packages previous to avocado jobs

  • Default: False

  • Type: <class ‘bool’>

sysinfo.collect.locale

Force LANG for sysinfo collection

  • Default: C

  • Type: <class ‘str’>

sysinfo.collect.optimize

Optimize sysinfo collected so that duplicates between pre and post re not stored in post

  • Default: False

  • Type: <class ‘bool’>

sysinfo.collect.per_test

Enable or disable sysinfo collection (like hardware details, profiles, etc.) for each test

  • Default: False

  • Type: <class ‘bool’>

sysinfo.collect.profiler

Whether to run certain commands in bg to give extra job debug information

  • Default: False

  • Type: <class ‘bool’>

sysinfo.collect.sysinfodir

Directory where Avocado will dump sysinfo data. If one is not given explicitly, it will default to a directory named “sysinfo-” followed by a timestamp in the current working directory.

  • Default: None

  • Type: <class ‘str’>

sysinfo.collectibles.commands

File with list of commands that will be executed and have their output collected

  • Default: /home/docs/checkouts/readthedocs.org/user_builds/avocado-framework/envs/latest/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/commands

  • Type: <function prepend_base_path at 0x7f70f036ab60>

sysinfo.collectibles.fail_commands

File with list of commands that will be executed and have their output collected, in case of failed test

  • Default: /home/docs/checkouts/readthedocs.org/user_builds/avocado-framework/envs/latest/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/fail_commands

  • Type: <function prepend_base_path at 0x7f70f036ab60>

sysinfo.collectibles.fail_files

File with list of files that will be collected verbatim, in case of failed test

  • Default: /home/docs/checkouts/readthedocs.org/user_builds/avocado-framework/envs/latest/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/fail_files

  • Type: <function prepend_base_path at 0x7f70f036ab60>

sysinfo.collectibles.files

File with list of files that will be collected verbatim

  • Default: /home/docs/checkouts/readthedocs.org/user_builds/avocado-framework/envs/latest/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/files

  • Type: <function prepend_base_path at 0x7f70f036ab60>

sysinfo.collectibles.profilers

File with list of commands that will run alongside the job/test

  • Default: /home/docs/checkouts/readthedocs.org/user_builds/avocado-framework/envs/latest/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/profilers

  • Type: <function prepend_base_path at 0x7f70f036ab60>

task.timeout.running

The amount of time a test has to complete in seconds.

  • Default: None

  • Type: <class ‘int’>

variants.contents

[obsoleted by –variants] Shows the node content (variables)

  • Default: False

  • Type: <class ‘bool’>

variants.debug

Use debug implementation to gather more information.

  • Default: False

  • Type: <class ‘bool’>

variants.inherit

[obsoleted by –summary] Show the inherited values

  • Default: False

  • Type: <class ‘bool’>

variants.json_variants_dump

Dump the Variants to a JSON serialized file

  • Default: None

  • Type: <class ‘str’>

variants.summary

Verbosity of the variants summary. (positive integer - 0, 1, … - or none, brief, normal, verbose, full, max

  • Default: 0

  • Type: <function map_verbosity_level at 0x7f70eee549a0>

variants.tree

[obsoleted by –summary] Shows the multiplex tree structure

  • Default: False

  • Type: <class ‘bool’>

variants.variants

Verbosity of the list of variants. (positive integer - 0, 1, … - or none, brief, normal, verbose, full, max

  • Default: 1

  • Type: <function map_verbosity_level at 0x7f70eee549a0>

vmimage.get.arch

Image architecture

  • Default: None

  • Type: <class ‘str’>

vmimage.get.distro

Name of image distribution

  • Default: None

  • Type: <class ‘str’>

vmimage.get.version

Image version

  • Default: None

  • Type: <class ‘str’>