How to Configure Different Hypervisors Using the vt.type Option in Avocado-VT

The vt.type option selects your backend hypervisor by loading hypervisor-specific driver modules and configuration files from virttest/backends/<type>/cfg/.

The avocado-framework/avocado-vt plugin provides a unified testing framework for multiple virtualization technologies. To switch between hypervisors like QEMU and Libvirt, you configure the vt.type option, which determines which backend driver is loaded and which default configuration files are parsed.

Understanding the vt.type Option

The vt.type configuration key (exposed as --vt-type on the command line) acts as the single source of truth for hypervisor selection in Avocado-VT. When you set this option, the framework validates the value against supported backends, loads the corresponding driver module, and imports hypervisor-specific default configurations.

Supported Hypervisor Backends

The framework supports multiple virtualization backends, each mapped to a specific driver module and configuration directory:

• qemu: Uses the QEMU driver and loads configurations from virttest/backends/qemu/cfg/
• libvirt: Uses the libvirt driver with configurations from virttest/backends/libvirt/cfg/
• openvswitch: Uses the openvswitch driver (inherits QEMU handling)
• lvsb: Uses the LVSB driver (no generic options)
• spice: Uses the Spice QA driver (independent of QEMU)

These values are defined in the SUPPORTED_TEST_TYPES list within virttest/standalone_test.py (lines 27-36).

How vt.type Works Under the Hood

The hypervisor selection process follows a four-stage pipeline implemented in avocado_vt/options.py and related modules.

Stage 1: Parsing and Validation

The option parser retrieves vt.type via get_opt(self.config, "vt.type") and validates it against SUPPORTED_TEST_TYPES. If the value is not recognized, the framework raises a configuration error before any backend code is loaded.

Stage 2: Loading Backend Configuration Files

If no custom --vt-config is provided, the framework resolves default configuration paths using data_dir.get_backend_cfg_path(vt_type, ...) (implemented in virttest/data_dir.py, lines 44-46). This function constructs paths to:

• machines.cfg
• guest-os.cfg
• tests.cfg (or tests-shared.cfg)

Located under virttest/backends/<vt_type>/cfg/.

Stage 3: Applying Backend-Specific Options

After generic options are processed, options._process_backend_specific_options(vt_type) dispatches to specialized handlers:

• _process_qemu_specific_options
• _process_libvirt_specific_options

This occurs in avocado_vt/options.py (lines 502-514), allowing each hypervisor to register unique command-line flags and configuration parameters.

Stage 4: Building the Test Matrix

Finally, the Cartesian parser constructs the test matrix using the selected backend's configuration files and any additional filters you provide via command-line arguments.

Practical Configuration Examples

Command Line Usage

Select your hypervisor directly when running tests:

# Run tests using QEMU backend

avocado run my_test --vt-type qemu

# Run tests using libvirt backend (requires running libvirtd)

avocado run my_test --vt-type libvirt

The --vt-type flag is registered in avocado_vt/plugins/vt.py (lines 76-78) and processed by the VirtTestOptionsProcess class.

Configuration File Method

Create a configuration file to set the default backend:

[vt]
type = libvirt

Run with the custom config:

avocado run my_test --vt-config myconfig.cfg

Alternatively, set the environment variable AVOCADO_VT_TYPE which the option parser reads from the configuration hierarchy.

Python API Access

Inspect or set the backend programmatically:

from avocado.utils import config
from avocado_vt.options import VirtTestOptionsProcess

# Simulate a config that contains vt.type

cfg = config.TestConfig()
cfg.set('vt.type', 'qemu')

# Process options (validates vt.type and loads backend)

options = VirtTestOptionsProcess(cfg)
parser = options.get_parser()

print(f"Backend selected: {cfg.get('vt.type')}")
print(f"Filters applied: {parser.only_filters}")

This triggers the same validation path used by the CLI (see VirtTestOptionsProcess._process_options in avocado_vt/options.py, lines 33-47).

Backend-Specific Configuration Files

Each hypervisor backend maintains its own configuration directory under virttest/backends/<type>/cfg/. When you set vt.type, the framework automatically loads:

• machines.cfg: Defines machine types and hardware profiles
• guest-os.cfg: Specifies guest operating system variants
• tests.cfg or tests-shared.cfg: Defines test parameters and variants

For example, when using --vt-type libvirt, the framework loads virttest/backends/libvirt/cfg/machines.cfg instead of the QEMU equivalent, ensuring that libvirt-specific options like connect_uri or driver_type are available.

Summary

• The vt.type option (CLI: --vt-type) is the single configuration key that determines which hypervisor backend Avocado-VT uses.
• Valid values are defined in SUPPORTED_TEST_TYPES within virttest/standalone_test.py and include qemu, libvirt, openvswitch, lvsb, and spice.
• The framework loads backend-specific configuration files from virttest/backends/<type>/cfg/ based on the selected type.
• Backend-specific option handlers in avocado_vt/options.py apply hypervisor-unique parameters after generic processing.

Frequently Asked Questions

What happens if I specify an unsupported vt.type value?

The framework validates vt.type against the SUPPORTED_TEST_TYPES list in virttest/standalone_test.py during the option processing stage. If you provide an unsupported value, Avocado-VT raises a configuration error immediately and exits before loading any backend code or configuration files.

Can I use vt.type to switch between different libvirt connection URIs?

While vt.type selects the libvirt backend, connection URIs are controlled separately through the vt.connect_uri option or the connect_uri parameter in your configuration files. When vt.type is set to libvirt, the framework processes libvirt-specific options via _process_libvirt_specific_options in avocado_vt/options.py, where you can specify connection details.

Do I need separate bootstrap commands for each hypervisor?

Yes. The avocado vt-bootstrap command respects the --vt-type flag to generate appropriate guest images and configuration files for the selected hypervisor. Run avocado vt-bootstrap --vt-type qemu for QEMU-specific assets or avocado vt-bootstrap --vt-type libvirt for libvirt-specific setups, as documented in docs/source/GettingStartedGuide.rst (lines 74-77).

Where are the backend-specific test parameters defined?

Backend-specific parameters reside in the configuration files under virttest/backends/<vt.type>/cfg/. The data_dir.get_backend_cfg_path() function in virttest/data_dir.py (lines 44-46) constructs these paths dynamically based on the vt.type value, loading machines.cfg, guest-os.cfg, and tests.cfg specific to your selected hypervisor.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}