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

> Debug avocado-vt test configurations by using the save_config option to write the final Cartesian configuration to a file. Inspect parameters and filters used during test execution.

- Repository: [avocado/avocado-vt](https://github.com/avocado-framework/avocado-vt)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/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`:

```bash
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`](https://github.com/avocado-framework/avocado-vt/blob/main//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:

```bash
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`](https://github.com/avocado-framework/avocado-vt/blob/main/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:

```python
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`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt.py) (CLI), [`avocado_vt/plugins/vt_init.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_init.py) (settings), and [`avocado_vt/discovery.py`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/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.