GetStarted

Getting started with the virt test test runner

Pre-requisites

1. A supported host platforms: Red Hat Enterprise Linux (RHEL) or Fedora. OpenSUSE should also work, but currently autotest is still not packaged for it, which means you have to clone autotest and put its path in an env variable so virt tests can find the autotest libs. Debian/Ubuntu now have a new experimental package that allows one to run the virt tests in a failry straight forward way.
2. Install software packages (RHEL/Fedora)
3. Install software packages (Debian/Ubuntu)
4. A copy of the virt test source

For the impatient

1. Clone the virt test repo

git clone git://github.com/autotest/virt-test.git

2. Get into the base dir

cd virt-test

3. Run the [subtest]/get_started.py script. For example, if you want to run the kvm subtest, you will run:

kvm/get_started.py

This script will check if you have the minimum requirements for the test (required commands and includes), and download the JeOS image. You can omit running this script, since the code of this script also gets to run when you call the test runner, but it is discouraged. Explicitly running get_started.py first is iteractive, and gives you a better idea of what is going on.

4. Get root, and execute the run script with appropriate options.

4.1) For kvm subtest users. The default kvm subtest set does not require root. Keep in mind that some tests might fail because of lack of superuser privileges, but we're trying to make as many tests as possible to work as non root. One particularly tricky area is networking testing (requires root due to bridge access requirements), so many of the nw cases will probably fail.

$ ./run -t kvm

4.2) For libvirt test users. Libvirt basic tests still need root as of today (11/28/2012).

# ./run -t libvirt

If you ran get_started.py, the test runner should just run the test. If you didn't, the runner will trigger the environment setup procedure:

1. Create the /var/tmp/libvirt_test dir to hold images and isos
2. Download the JeOS image (180 MB, takes about 3 minutes on a fast connection) and uncompress it (takes about a minute on an HDD laptop). p7ip has to be present.
3. Run a predefined set of tests.

Running different tests

You can list the available tests to run by using the flag --list-tests

$ ./run -t kvm --list-tests
(will print a numbered list of tests, with a paginator)

Then you can pass tests that interest you with --tests "list of tests", for example:

1. KVM

$ ./run -t kvm --tests "migrate timedrift file_transfer"

2) Libvirt: Libvirt has a caveat: Since it's necessary to import the JeOS image into libvirt for it to count as a guest, if you want to run tests that are dependent of guests, you are better of starting the test set with "unattended_install.import.import". Since you want to remove the defined guest at the end of the test sequence, so you don't get a 'vm 'vm1' already exists error, you also want to finish with remove_guest.without_disk.

# ./run -t libvirt --tests "unattended_install.import.import boot reboot remove_guest.without_disk"

Checking the results

The test runner will produce a debug log, that will be useful to debug problems:

[lmr@localhost virt-test.git]$ ./run -t kvm --tests boot_with_usb
SETUP: PASS (1.20 s)
DATA DIR: /path/to/virt_test
DEBUG LOG: /path/to/virt-test.git/logs/run-2012-12-12-01.39.34/debug.log
TESTS: 10
boot_with_usb.ehci: PASS (18.34 s)
boot_with_usb.keyboard.uhci: PASS (21.57 s)
boot_with_usb.keyboard.xhci: PASS (24.56 s)
boot_with_usb.mouse.uhci: PASS (21.59 s)
boot_with_usb.mouse.xhci: PASS (23.11 s)
boot_with_usb.usb_audio: PASS (20.99 s)
boot_with_usb.hub: PASS (22.12 s)
boot_with_usb.storage.uhci: PASS (21.61 s)
boot_with_usb.storage.ehci: PASS (23.27 s)
boot_with_usb.storage.xhci: PASS (25.03 s)

At any moment, in this example you can check /path/to/virt-test.git/logs/run-2012-12-12-01.39.34/debug.log for test details.