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 0x7f0c0819e660>
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 0x7f0c0819ec00>
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 0x7f0c0819ec00>
datadir.paths.logs_dir
Logs directory for Avocado
Default: /home/docs/avocado/job-results
Type: <function prepend_base_path at 0x7f0c0819ec00>
datadir.paths.test_dir
Test directory for Avocado tests
Default: /usr/share/doc/avocado/tests
Type: <function prepend_base_path at 0x7f0c0819ec00>
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 0x7f0c06c51a80>
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’>
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 0x7f0c06d94f40>
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 0x7f0c07161e40>
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 0x7f0c0819ec00>
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 0x7f0c0819ec00>
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 0x7f0c06eae980>
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’>
simpletests.status.failure_fields
Fields to include in the presentation of executable test failures. Accepted values: status, stdout, stderr.
Default: [‘status’, ‘stdout’, ‘stderr’]
Type: <class ‘list’>
simpletests.status.skip_location
Location to search the regular expression on. Accepted values: all, stdout, stderr.
Default: all
Type: <class ‘str’>
simpletests.status.skip_regex
Python regular expression that will make the test status SKIP when matched.
Default: ^SKIP$
Type: <class ‘str’>
simpletests.status.warn_location
Location to search the regular expression on. Accepted values: all, stdout, stderr.
Default: all
Type: <class ‘str’>
simpletests.status.warn_regex
Python regular expression that will make the test status WARN when matched.
Default: ^WARN$
Type: <class ‘str’>
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/103.0/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/commands
Type: <function prepend_base_path at 0x7f0c0819ec00>
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/103.0/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/fail_commands
Type: <function prepend_base_path at 0x7f0c0819ec00>
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/103.0/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/fail_files
Type: <function prepend_base_path at 0x7f0c0819ec00>
sysinfo.collectibles.files
File with list of files that will be collected verbatim
Default: /home/docs/checkouts/readthedocs.org/user_builds/avocado-framework/envs/103.0/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/files
Type: <function prepend_base_path at 0x7f0c0819ec00>
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/103.0/lib/python3.11/site-packages/avocado/etc/avocado/sysinfo/profilers
Type: <function prepend_base_path at 0x7f0c0819ec00>
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 0x7f0c06c80040>
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 0x7f0c06c80040>
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’>