How the vt_init Plugin Initializes the VT Test Environment on First Use

The vt_init plugin bootstraps the VT test environment by registering configuration sections, merging external config files, and injecting the VirtTestLoader into Avocado's plugin system during the first initialization cycle.

When you run any Avocado command in the avocado-framework/avocado-vt repository, the vt_init plugin ensures the virtualization testing (VT) environment is fully configured. This happens transparently on first use through Avocado's plugin interface, setting up all necessary configuration hierarchies and test loaders required for virt-test execution.

How the vt_init Plugin is Discovered

Avocado discovers the plugin through the entry point declared in setup.py:

avocado.plugins.init → vt-init = avocado_vt.plugins.vt_init:VtInit

This entry point maps to the VtInit class defined in avocado_vt/plugins/vt_init.py. When Avocado starts and loads plugins implementing the Init interface, it instantiates VtInit and calls its initialize() method.

First-Time Initialization Guard

The plugin uses a guard mechanism to prevent duplicate configuration registration. Inside initialize(), the first check is:

if not is_registering_settings_required():
    return

The is_registering_settings_required() function lives in virttest/compat.py. It returns True only during the first plugin initialization cycle and False on subsequent runs, ensuring the VT environment setup happens exactly once.

Configuration Section Registration

When the guard passes, initialize() creates the VT configuration hierarchy using avocado.core.settings.settings.register_option. The plugin registers the following sections:

• vt – High-level options including config file paths, guest OS selection, and filter lists (settings.register_option(section, key="config", …))
• vt.setup – Image handling controls such as backup_image_before_test and restore operations
• vt.common – Global VM defaults including memory size (mem), architecture, and data directories
• vt.qemu – QEMU-specific settings including binary path (qemu_bin), acceleration type, device configurations, and sandboxing options
• vt.libvirt – Libvirt connection URI and related parameters
• vt.debug – Debug flags such as no_cleanup to preserve test artifacts
• vt.filter – Default filter overrides for test selection
• plugins.vtjoblock – Lock-file directory configuration for the vt-joblock plugin

After registering all options, the plugin merges external configuration files:

settings.merge_with_configs()

This ensures user-provided settings in /etc/avocado/conf.d/ or ~/.config/avocado/ override the defaults.

Test Loader Registration

If the Avocado loader module is available (Avocado ≥ 82), the plugin registers the VT test loader:

virt_loader = getattr(importlib.import_module("avocado_vt.loader"), "VirtTestLoader")
loader.register_plugin(virt_loader)

The VirtTestLoader class defined in avocado_vt/loader.py enables the avocado vt command to discover and execute virt-test tests using Cartesian configuration files.

Summary

• The vt_init plugin is discovered via the avocado.plugins.init entry point in setup.py.
• First-time initialization is guarded by is_registering_settings_required() in virttest/compat.py to prevent duplicate registrations.
• The plugin registers nine configuration sections (vt, vt.setup, vt.common, vt.qemu, vt.libvirt, vt.debug, vt.filter, plugins.vtjoblock) using settings.register_option.
• External configuration files are merged via settings.merge_with_configs().
• The VirtTestLoader is registered with Avocado's loader system, enabling VT test discovery.

Frequently Asked Questions

What triggers the vt_init plugin to run?

The plugin runs whenever Avocado loads its plugin system, which happens on any Avocado command execution. The initialize() method is called automatically because VtInit implements the Init plugin interface registered under the avocado.plugins.init entry point.

How does the plugin prevent settings from being registered multiple times?

The plugin calls is_registering_settings_required() from virttest/compat.py at the start of initialize(). This function returns False on subsequent runs after the first initialization, causing the method to return early and skip duplicate registrations.

Where are the VT configuration options stored after registration?

The options are stored in Avocado's global settings object (avocado.core.settings.settings). They can be viewed using avocado plugins --list vt or overridden via command-line flags like --vt-guest-os or configuration files in /etc/avocado/conf.d/.

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