# VirtTest Timeout Mechanism: How It Works and How to Override It

> Understand the VirtTest timeout mechanism in avocado-vt Discover how its four-layer hierarchy works and learn to override defaults via CLI config files or code.

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

---

**The VirtTest timeout mechanism in avocado-vt operates through a four-layer hierarchy that defaults to 24 hours at the runner level, but can be overridden via command-line parameters, Cartesian configuration files, or programmatically within test code.**

The VirtTest timeout mechanism controls how long virtualized tests can execute before the avocado-vt plugin forcibly terminates them. Understanding this layered system is essential for managing long-running virtualization scenarios, debugging hung processes, and preventing premature test failures in the `avocado-framework/avocado-vt` repository.

## How the VirtTest Timeout Mechanism Works

The timeout system implements a cascading priority structure across four distinct layers, where more specific configurations override broader defaults.

### Runner-Level Default (24 Hours)

At the highest level, the VT runner enforces a hard ceiling for all test processes. In [`avocado_vt/plugins/vt_runner.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_runner.py), line 38 defines `VTTestRunner.DEFAULT_TIMEOUT = 86400`, establishing an absolute maximum of 24 hours for any VirtTest execution regardless of other settings.

### Test Class Default (Per-Test Timeout)

The `VirtTest` class in [`avocado_vt/test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/test.py) handles individual test timeout configuration. During initialization at lines 94-97, the constructor extracts the `test_timeout` value from the `vt_params` dictionary:

```python
self.timeout = vt_params.get("test_timeout", self.timeout)

```

If the cartesian configuration does not specify a value, this falls back to Avocado's built-in default, typically 3600 seconds (1 hour).

### Configuration File Defaults

The shared configuration in [`virttest/shared/cfg/base.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/shared/cfg/base.cfg) provides baseline values for generic environments. Line 710 defines `test_timeout = 14400`, setting a 4-hour default for tests that do not specify their own timeout in more specific configuration layers.

### Utility Helper Propagation

Helper functions throughout the codebase respect the timeout parameter to ensure consistent behavior across guest operations. For example, in [`virttest/utils_spice.py`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/utils_spice.py) at lines 119-124, guest session commands receive the timeout argument:

```python
guest_session.cmd("systemctl start vdagent", timeout=test_timeout)

```

This propagation ensures that individual commands inside the test respect the same time limits as the overall test execution.

## How to Override the VirtTest Timeout

You can customize timeout values at three primary levels, with the most specific setting taking precedence over broader defaults.

### Command-Line Override

Pass a custom value through the `--vt-params` argument to inject timeout settings directly into the test parameters without modifying configuration files:

```bash
avocado run mytest.py --vt-params "test_timeout=7200"

```

This sets a 2-hour timeout for that specific execution only.

### Cartesian Configuration File

For test-specific defaults, add the parameter to your Cartesian configuration:

```ini

# mycartesian.cfg

[boot_linux]
vm_type = qemu
test_timeout = 900

```

Run the test with your custom configuration:

```bash
avocado run virt-tests/guest-os/linux/boot.py -c mycartesian.cfg

```

### Global Configuration Changes

To modify defaults across all tests, edit [`virttest/shared/cfg/base.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/shared/cfg/base.cfg) and adjust the `test_timeout` value on line 710. This affects all tests that do not specify their own timeout in more specific configuration layers.

### Programmatic Override Inside Tests

Within test code, dynamically adjust the timeout by modifying the `timeout` attribute directly:

```python
def my_test(test, params, env):
    test.timeout = 120  # Force 2-minute limit

    # ... test logic ...

```

This approach is useful when specific test phases require different timing constraints than the overall test configuration.

## Summary

- The VirtTest timeout mechanism implements a four-layer hierarchy: runner default (24 hours), test class initialization, configuration files, and utility helpers.
- Default values cascade from [`virttest/shared/cfg/base.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/shared/cfg/base.cfg) (4 hours) through the `VirtTest` constructor to individual test instances.
- Override options include command-line parameters (`--vt-params`), Cartesian configuration files, global configuration edits, and programmatic modification of `test.timeout`.
- The runner's hard limit of 86400 seconds in `VTTestRunner` provides an absolute safety ceiling for all VirtTest executions.

## Frequently Asked Questions

### What is the default VirtTest timeout?

The default timeout depends on which configuration layer applies. The `VTTestRunner` in [`avocado_vt/plugins/vt_runner.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_runner.py) defines a hard ceiling of 86400 seconds (24 hours). However, most tests inherit a default of 14400 seconds (4 hours) from [`virttest/shared/cfg/base.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/shared/cfg/base.cfg), or 3600 seconds (1 hour) from Avocado's built-in default if no configuration value is present.

### How do I set a custom timeout for a single test run?

Use the `--vt-params` command-line argument to inject a timeout value directly into the test parameters. For example, `avocado run mytest.py --vt-params "test_timeout=7200"` sets a 2-hour timeout for that specific execution without modifying any configuration files.

### Can I override the timeout programmatically during test execution?

Yes, you can modify the `timeout` attribute of the test object directly within your test function. Setting `test.timeout = 120` forces a 2-minute limit for the remainder of the test execution. This is useful when specific test phases require different timing constraints than the overall test configuration.

### Where is the VirtTest timeout defined in the source code?

The timeout mechanism spans multiple files. The runner default is defined in [`avocado_vt/plugins/vt_runner.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_runner.py) at line 38 as `DEFAULT_TIMEOUT = 86400`. The per-test timeout is read in [`avocado_vt/test.py`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/test.py) at lines 94-97 where `VirtTest.__init__` extracts `test_timeout` from `vt_params`. Default configuration values reside in [`virttest/shared/cfg/base.cfg`](https://github.com/avocado-framework/avocado-vt/blob/main/virttest/shared/cfg/base.cfg) at line 710.