How to Use the save_config Option to Debug Avocado-VT Test Configurations

Use the --vt-save-config command-line flag or the vt.save_config configuration setting to write the final Cartesian configuration to a file, allowing you to inspect exactly which parameters and filters the avocado-vt plugin will use during test execution.

The save_config option in the avocado-framework/avocado-vt repository provides a powerful debugging mechanism for complex virtualization test setups. When troubleshooting why specific tests are selected or why certain parameters are not being applied, this option reveals the complete, resolved Cartesian configuration that drives the test runner.

What the save_config Option Does

When you enable the save_config option, Avocado-VT writes the final Cartesian configuration built by the VT option processor to a specified file path. This snapshot includes:

• The original include line from your configuration files
• All automatically generated only and no filters derived from command-line arguments
• Every assignment (assign) generated from CLI options and the selected backend configuration

Inspecting this file lets you verify exactly which parameters the test runner will use, making it straightforward to spot missing values, incorrect filters, or unexpected configuration overrides that cause test-selection problems.

How save_config Works in the Source Code

The save_config functionality is implemented across three key files in the avocado-vt codebase:

1. CLI Registration – The --vt-save-config flag is declared in avocado_vt/plugins/vt.py at lines 60-62, making it available as a command-line argument.

2. Settings Registration – The corresponding configuration setting vt.save_config is registered in avocado_vt/plugins/vt_init.py at lines 48-51, allowing the option to be set via configuration files.

3. Persistence Logic – The actual writing of the Cartesian configuration occurs in avocado_vt/discovery.py within the DiscoveryMixIn class at lines 30-39. If the option is omitted or set to None, the saving step is bypassed entirely.

Using the save_config Option

Command-Line Usage

The most common way to use the save_config option is via the --vt-save-config flag when running avocado vt-run:

avocado vt-run \
    --vt-type qemu \
    --vt-arch x86_64 \
    --vt-save-config /tmp/vt_debug.cfg \
    my_test.py

After execution, /tmp/vt_debug.cfg contains the resolved configuration:

include /usr/share/avocado/vt/tests.cfg
only_filter qemu
only_filter x86_64
assign mem 2048
assign nettype bridge
...

Combining with Filters

When debugging complex filter chains, save the configuration to verify that your only and no filters are applied correctly:

avocado vt-run \
    --vt-type qemu \
    --vt-only-filter "smallpages" \
    --vt-no-filter "no_9p_export" \
    --vt-save-config ./debug.cfg

The resulting debug.cfg file records the additional filter statements, confirming whether the intended filters were actually applied to the Cartesian parser.

Programmatic Configuration

You can also enable the save_config option programmatically within Python scripts:

from avocado.core import settings
from avocado.core.nrunner import run

# Enable the save-config option via settings

settings.register_option('vt', key='save_config', default='debug.cfg')

# Run a VT test; the config will be written automatically

run(['avocado', 'vt-run', '--vt-type', 'qemu', 'example_test.py'])

Interpreting the Saved Configuration File

The file generated by the save_config option follows the Cartesian configuration syntax. Each line represents a directive that the Avocado-VT parser used to build the test set:

• include – Shows which base configuration file was loaded
• only_filter – Lists positive filters that restrict tests to specific variants
• no_filter – Lists negative filters that exclude specific variants
• assign – Shows parameter assignments derived from CLI arguments and backend defaults

When debugging, look for missing assign entries that should have been set by your command-line arguments, or unexpected only_filter entries that might be restricting your test selection too aggressively.

Summary

• The save_config option (--vt-save-config or vt.save_config) writes the final Cartesian configuration to a file for inspection.
• Use it to verify that command-line filters, backend settings, and parameter assignments are correctly resolved before test execution.
• The implementation spans avocado_vt/plugins/vt.py (CLI), avocado_vt/plugins/vt_init.py (settings), and avocado_vt/discovery.py (persistence logic).
• Inspect the saved file for include, only_filter, no_filter, and assign directives to troubleshoot test selection issues.

Frequently Asked Questions

Where is the save_config option defined in the Avocado-VT source code?

The option is defined in two locations within the avocado-framework/avocado-vt repository. The command-line flag --vt-save-config is registered in avocado_vt/plugins/vt.py at lines 60-62, while the corresponding configuration setting vt.save_config is registered in avocado_vt/plugins/vt_init.py at lines 48-51.

What file format does the save_config option generate?

The save_config option generates a plain text file using Cartesian configuration syntax. The file contains directives such as include statements for base configuration files, only_filter and no_filter entries for test selection criteria, and assign statements showing parameter values derived from command-line arguments and backend defaults.

Can I use save_config with custom filter combinations?

Yes, the save_config option works with any combination of --vt-only-filter and --vt-no-filter arguments. When you specify these filters alongside --vt-save-config, the generated file includes the resulting only_filter and no_filter directives, allowing you to verify that your filter logic was applied correctly to the Cartesian parser.

Is it possible to enable save_config programmatically instead of via CLI?

Yes, you can enable the save_config option programmatically by registering the vt.save_config setting through the Avocado settings API. Import avocado.core.settings, register the option with your desired default file path, and the configuration will be saved automatically when running VT tests through the Python API.

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