How to Integrate VT Tests with CI/CD Pipelines Using the Avocado Framework

Integrate Avocado-VT into CI/CD by installing the Avocado core and VT plugin, running avocado vt-bootstrap --yes-to-all to prepare the environment, and executing tests with avocado run -t vt.

The avocado-framework/avocado-vt repository provides a virtualization testing plugin that enables automated testing of QEMU, libvirt, and other virtualization backends. To integrate VT tests with CI/CD pipelines using the Avocado framework, you must automate the bootstrap process that prepares guest images and configuration files, then execute the test suite using Avocado's standard runner commands.

Prerequisites and Environment Setup

Before integrating VT tests into your pipeline, ensure your runner has Python 3.9 or newer and sufficient disk space for guest images. The Avocado-VT plugin depends on the core Avocado framework, so you must install both components. The repository ships a requirements-travis.txt file that pins all Python dependencies needed for CI execution.

Understanding the Bootstrap Process

The avocado vt-bootstrap command is the critical entry point for CI automation. Implemented in avocado_vt/plugins/vt_bootstrap.py (lines 27‑55), this plugin invokes the core bootstrap logic defined in virttest/bootstrap.py at line 919. The bootstrap process performs three essential tasks:

• Downloads JeOS guest images and places them in $HOME/.avocado/vt
• Generates configuration files such as virttest.cfg based on the host architecture
• Creates necessary directory structures for test data and ISO images

For CI environments, always append the --yes-to-all flag to bypass interactive prompts that would otherwise hang the build.

CI/CD Integration Architecture

The official repository provides a reference implementation in .github/workflows/ci.yml that demonstrates the exact sequence required for any CI system. You can replicate these steps in GitLab CI, Jenkins, Azure Pipelines, or similar platforms.

Dependency Installation

First, install the Python requirements and both Avocado components:

pip install -r requirements-travis.txt
pip install -e .
git clone https://github.com/avocado-framework/avocado avocado-libs
pip install -e avocado-libs

This editable installation ensures the CI uses the exact code from the pull request or branch under test.

Handling Host Binary Dependencies

The bootstrap step checks for host utilities such as arping and tcpdump. In minimal CI runners, create dummy placeholders to satisfy these checks without installing full packages:

mkdir -p /tmp/dummy_bin
touch /tmp/dummy_bin/arping /tmp/dummy_bin/tcpdump
chmod +x /tmp/dummy_bin/*
export PATH="/tmp/dummy_bin:$PATH"

This pattern appears in .github/workflows/ci.yml (lines 52‑58) and prevents the bootstrap from aborting due to missing system tools.

Executing the Bootstrap Command

Run the bootstrap with flags optimized for CI automation:

avocado vt-bootstrap --vt-skip-verify-download-assets --yes-to-all

The --vt-skip-verify-download-assets flag accelerates the process by skipping checksum verification when network conditions are stable. Set AVOCADO_LOG_DEBUG=yes to capture verbose output for troubleshooting.

Running the Test Suite

After bootstrap completes, execute VT tests using the standard Avocado runner:

avocado run -t vt --json - --output-dir=avocado-results

You can filter tests by category using -k (e.g., -k "boot") or specify a particular backend with --vt-type qemu (default) or --vt-type libvirt.

Complete CI/CD Configuration Example

Below is a production-ready GitHub Actions workflow that integrates VT tests with CI/CD pipelines using the Avocado framework. Adapt the runs-on and strategy sections for GitLab CI or Jenkins as needed.

name: Avocado-VT CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  vt-tests:
    runs-on: ubuntu-24.04
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
          cache-dependency-path: requirements-travis.txt

      - name: Install Avocado core & VT plugin
        run: |
          pip install -r requirements-travis.txt
          pip install -e .
          git clone https://github.com/avocado-framework/avocado avocado-libs
          pip install -e avocado-libs

      - name: Dummy host binaries (needed by vt-bootstrap)
        run: |
          mkdir -p /tmp/dummy_bin
          touch /tmp/dummy_bin/arping /tmp/dummy_bin/tcpdump
          chmod +x /tmp/dummy_bin/*
          echo "/tmp/dummy_bin" >> $GITHUB_PATH

      - name: Bootstrap VT environment
        run: |
          AVOCADO_LOG_DEBUG=yes avocado vt-bootstrap --vt-skip-verify-download-assets --yes-to-all

      - name: Run VT test suite
        run: |
          avocado run -t vt --json - --output-dir=avocado-results

To optimize performance, add a cache step for $HOME/.avocado/vt between the bootstrap and test execution phases.

Local Development and Testing

Before committing to CI, verify the integration locally using the same commands executed in the pipeline:

# Install dependencies

pip install -r requirements-travis.txt
pip install -e .
git clone https://github.com/avocado-framework/avocado avocado-libs
pip install -e avocado-libs

# Prepare dummy binaries if needed

mkdir -p /tmp/dummy_bin
touch /tmp/dummy_bin/arping /tmp/dummy_bin/tcpdump
chmod +x /tmp/dummy_bin/*
export PATH="/tmp/dummy_bin:$PATH"

# Bootstrap the environment

avocado vt-bootstrap --yes-to-all

# Run a specific test category

avocado run -t vt -k "boot"

Use --vt-type libvirt instead of the default QEMU backend if your development machine uses libvirt-managed virtualization.

Key Source Files Reference

Understanding these files helps troubleshoot CI failures and customize the bootstrap process:

• .github/workflows/ci.yml – Complete GitHub Actions workflow definition showing checkout, dependency installation, dummy binary creation, and test execution (lines 24‑58).
• avocado_vt/plugins/vt_bootstrap.py – Implements the VTBootstrap plugin class and its run() method (lines 27‑55) that exposes the avocado vt-bootstrap command.
• virttest/bootstrap.py – Contains the core bootstrap(options, interactive) function (line 919) that downloads assets, creates guest images, and generates configuration files.
• virttest/defaults.py – Defines default guest OS images and architecture constants used during bootstrap.
• docs/source/WritingTests/WritingSimpleTests.rst – Documentation reference showing example avocado vt-bootstrap usage (line 286).

Summary

• Automated bootstrap is essential for CI/CD; use avocado vt-bootstrap --yes-to-all to prepare the VT environment without interaction.
• Dummy binaries for arping and tcpdump prevent bootstrap failures on minimal runners; create these in /tmp/dummy_bin and add to $PATH.
• Installation order matters: install requirements-travis.txt, then the VT plugin in editable mode, then the Avocado core from avocado-framework/avocado.
• Test execution uses standard Avocado commands: avocado run -t vt filters for VT tests, while --vt-type selects the virtualization backend.
• Caching the $HOME/.avocado/vt directory between CI runs significantly reduces bootstrap time by preserving downloaded JeOS images.

Frequently Asked Questions

How do I handle missing host utilities like arping and tcpdump in CI environments?

Create dummy placeholder binaries in a temporary directory and add that directory to your $PATH before running avocado vt-bootstrap. The bootstrap process checks for these utilities but does not require functional implementations for basic test preparation. This pattern is implemented in .github/workflows/ci.yml (lines 52‑58) to prevent the bootstrap from aborting on minimal Ubuntu runners.

What is the difference between avocado vt-bootstrap and running tests directly?

avocado vt-bootstrap is a setup command implemented in avocado_vt/plugins/vt_bootstrap.py that downloads guest images, generates configuration files, and prepares the virttest/ directory structure. You must run this command once before executing any VT tests. The actual test execution uses avocado run -t vt, which discovers and runs the tests prepared during the bootstrap phase.

Can I use a virtualization backend other than QEMU in my CI pipeline?

Yes, specify the backend using the --vt-type parameter during both bootstrap and test execution. For example, use avocado vt-bootstrap --vt-type libvirt --yes-to-all followed by avocado run -t vt --vt-type libvirt. Ensure your CI runner has the corresponding virtualization infrastructure installed (e.g., libvirt-daemon-system and qemu-kvm for libvirt backends).

How do I speed up CI runs by caching VT assets?

Add a cache step in your CI configuration for the $HOME/.avocado/vt directory, which stores downloaded JeOS images and generated configuration files. In GitHub Actions, use actions/cache with path: ~/.avocado/vt and a key based on your Python version and repository commit. This prevents redundant downloads during subsequent runs while still allowing avocado vt-bootstrap to verify file integrity.

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