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

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, 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 handles individual test timeout configuration. During initialization at lines 94-97, the constructor extracts the test_timeout value from the vt_params dictionary:

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 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 at lines 119-124, guest session commands receive the timeout argument:

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:

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:

# mycartesian.cfg

[boot_linux]
vm_type = qemu
test_timeout = 900

Run the test with your custom configuration:

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 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:

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 (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 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, 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 at line 38 as DEFAULT_TIMEOUT = 86400. The per-test timeout is read in 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 at line 710.

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