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

> Integrate VT tests with CI/CD using the Avocado framework. Learn to install, bootstrap, and run your tests efficiently for automated workflows.

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

---

**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`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/avocado_vt/plugins/vt_bootstrap.py) (lines 27‑55), this plugin invokes the core bootstrap logic defined in [`virttest/bootstrap.py`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/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`](https://github.com/avocado-framework/avocado-vt/blob/main/.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:

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

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

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

```bash
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.

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

```bash

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