From KVM

KVM subtests reference

This is the high level documentation for the KVM test API and the available tests. It's not meant to be an extensive API documentation.

Getting yourself familiar with the KVM subtests

It's recommended to have a copy of the code ready to observe and hack, as explained on the getting started session:

git clone git://github.com/ehabkost/autotest.git

This will fetch a complete checkout of the autotest code, and it does contain all autotest modules. We are specially concerned with the contents of the client/ code, more specifically the kvm test code (client/tests/kvm).

As it was mentioned on the getting started guide presented on this documentation, the KVM test has traits different from most autotest client tests. We have a lot of code involved in controlling qemu instances and creating a high level API to handle virtual machine instances, and as we have a large amount of tests itself. In order to make something modular and easier to maintain and understand, the kvm class, that represents the KVM test inside autotest, it's just a wrapper that loads appropriate functions on the test module, that is in turn a directory full of python source files, each one of them containing one test. This directory is an importable module due to the presence of the file __init__.py in there.

So, a look at this subfolder will show you the tests available at a particular time. If you want to add a new test, there are simple rules:

• A test named foo will have a foo.py file inside the tests dir.
• This file must implement the function run_foo.

That's all. Now, let's take a look at the high level API provided by the libraries kvm_utils.py and kvm_test_utils.py, both provided at the top level of the kvm autotest module (client/tests/kvm/kvm_utils.py and client/tests/kvm/kvm_test_utils.py).

KVM subtest API

The test function calls are plain static (as in not belonging to a class) functions, and the signature for them is nearly identical:

def run_foo(test, params, env):

• test is allways a particular instance of the kvm test (so we can use important attributes and methods from it).
• params is a python dictionary with all the test parameters, that will be distributed as needed inside the function implementation.
• env is the environment file. As the KVM test needs to keep processes (vms) alive across several different tests, an environment file is created and updated every time it's needed with the current objects available, so when other tests do execute they can query this enviroment file to pick objects. In the majority of the times, you will be picking VM objects from the environment file.

So you probably don't need to mess with the signature, you will just get distribute parameters across your function code and manipulate VMs. A VM object is an object that represents a qemu based virtual machine, so it is in a matter of fact a living qemu process being controlled and wrapped on python code.

Most of the KVM tests start with those 2 statements:

vm = kvm_test_utils.get_living_vm(env, params.get("main_vm"))
session = kvm_test_utils.wait_for_login(vm)

The module kvm_test_utils contains very high level functions to manipulate virtual machines:

• get_living_vm will search on the environment file for a VM instance with the particular name, if it doesn't exist, it will be created. This will give you a vm object to play with on your test.
• wait_for_login will try until it manages to log onto the VM in question, so you can use the session object to type commands in it and receive the output accordingly.

Your session object has methods such as the sendline() method, that will type what you provide as an argument, optionally making it possible to receive the output and the return code of the command being typed. Your vm object has methods such as clone() to create a clone vm from your original vm, or send_monitor_cmd, that will allow you to pass commands to the qemu monitor of the VM being executed, allowing you to receive the output of those commands as well. Methods of the vm object can be seen on the client/tests/kvm/kvm_vm.py.