README.rst

======================================
Linux Virtualization Tests (virt-test)
======================================

Really quick start guide
------------------------

The most convenient distro to run virt-test on is Fedora,
since we have autotest libs officially packaged on this distro [1].

It is similarly easy to set things up on a RHEL box, but then
you need to enable the EPEL repos [2] to install the needed packages.

The most recent addition to this list is Ubuntu/Debian. New repos were
set with a new autotest package. Learn how to add the proper repos and
install your packages on [3].


Install dependencies
--------------------

Install the p7zip file archiver so you can uncompress the JeOS [4] image.

Red Hat based:

# yum install p7zip

Debian based:

# apt-get install p7zip-full

Install the autotest-framework package, to provide the needed autotest libs.

Red Hat based:

# yum install autotest-framework

Debian based (needs to enable repo, see [3]):

# apt-get install autotest

Some tests might need some other dependencies, such as the migrate
using file descriptors, that requires a working toolchain and python-devel,
and generating VM videos, that requires python-gstreamer.

For such cases, it is best that you refer to the more complete documentation:

https://github.com/autotest/virt-test/wiki/InstallPrerequesitePackages

https://github.com/autotest/virt-test/wiki/InstallPrerequesitePackagesDebian


Execute the bootstrap script
------------------------

Let's say you're interested in the qemu tests:

qemu/get_started.py

The script can help you to setup a data dir, copy the sample config files
to actual config files, and download the JeOS image.

Execute the runner script
-------------------------

You can execute the main runner script, called run. The script offers you
some options, all explained in the script help. A really really simple execution
of the script for qemu tests is:

./run -t qemu

This will execute a subset of the tests available.

Note: If you execute the runner before the bootstrap, things will work,
but then you won't get prompted and the runner will download the JeOS
automatically.

[1] If you want to use it without the packaged rpm, you need to have a clone
of the autotest code (git://github.com/autotest/autotest.git) and set the
env variable AUTOTEST_PATH pointing to the path of the clone. We do have
plans to package the libs to more distributions.

[2] http://fedoraproject.org/wiki/EPEL/FAQ#How_can_I_install_the_packages_from_the_EPEL_software_repository.3F

[3] https://github.com/autotest/virt-test/wiki/InstallPrerequesitePackagesDebian

[4] JeOS: Minimal guest OS image (x86_64)

Actual documentation website
----------------------------

https://github.com/autotest/virt-test/wiki

Description
-----------

virt-test is a Linux virtualization test suite, intended to be used in
conjunction with the autotest framework [1], although it can be also used
separately, on a virt developer's machine, to run tests quicker and smaller
in scope, as an auxiliary tool of the development process.

This test suite aims to have test tools for a wide range of testing scenarios:

-  Guest OS install, for both Windows (WinXP - Win7) and Linux (RHEL,
   Fedora, OpenSUSE) and any generic one, through a 'step engine' mechanism.
-  Serial output for Linux guests
-  Migration, networking, timedrift and other types of tests
-  Monitor control for both human and QMP protocols
-  Build and use qemu using various methods (source tarball, git repo,
   rpm)
-  Performance testing
-  Call other kvm test projects, such as kvm-unit-tests

We support x86\_64 hosts with hardware virtualization support (AMD and
Intel), and Intel 32 and 64 bit guest operating systems, and work is underway
to support PPC hosts.

[1] http://autotest.github.com/ - Autotest is a project that aims to
provide tools and libraries to perform automated testing on the linux
platform. Autotest is a modular framework, and this suite can be used as
a submodule of the client module. If you do not want to use or know about
autotest, this is fine too, and we'll provide documentation and tools to
perform development style testing with it.


Basic Troubleshooting
---------------------

If you have problems with the basic usage described here, it's possible
that there's some local change in your working copy of virt-test. These
changes can come in (at least) two different categories:

- Code changes, which you can check with the git tools (try "git diff"
  and "git branch" first)
- Configuration changes that can you reset with "update_config.py"

If you find that you have local changes in the code, please try to reset
your checked out copy to upstream's master by running::

$ git checkout master
$ git pull


And then, reset you configuration. If you're going to run qemu tests, run::

$ qemu/update_config.py


If you're still having problems after these basic troubleshoot steps,
please contact us!