Ubuntu Manpage: virt-v2v-test-harness - Used to test virt-v2v against real test cases

NAME

       virt-v2v-test-harness - Used to test virt-v2v against real test cases

SYNOPSIS

        open V2v_test_harness

        let test = "rhel_45_i386_fv"
        let test_plan = {
          default_plan with
            boot_plan = Boot_to_screenshot (test ^ "-login.ppm")
        }

        let () = run ~test ~test_plan ()

DESCRIPTION

virt-v2v(1) converts guests from a foreign hypervisor to run on KVM, managed by libvirt,
OpenStack, oVirt, Red Hat Virtualisation (RHV) or several other targets.

Virt-v2v-test-harness is a small library (module name: "V2v_test_harness") used to run
virt-v2v against a set of test cases consisting of real virtual machines.

It acts as a test harness, taking a test case, running virt-v2v on it (non-destructively),
then test-booting the result. It can ensure that the test case converts successfully,
boots successfully, and reaches a milestone (such as a particular screenshot). It can
also test that the conversion created, modified or deleted the expected files from within
the guest.

GETTING THE TEST CASES
Because the test cases are actual virtual machines, we split them into two groups: test
cases which are freely redistributable and those which are proprietary. The former are
things like Fedora or CentOS images, which are free software. The latter are things like
Windows or Red Hat Enterprise Linux.

The freely redistributable test cases can be downloaded from:
http://git.annexia.org/?p=virt-v2v-test-cases-free.git not available yet

The proprietary test cases are available at
http://git.annexia.org/?p=virt-v2v-test-cases-nonfree.git This does not contain the
proprietary images themselves, which are not made available to the public for licensing
reasons.

The test cases consist of disk images which are very large, from 250 MB through to tens of
gigabytes each. This means that distributing test cases can be very time-consuming and
expensive. We use git-annex(1) to distribute the test images.

REQUIREMENTS
It’s recommended to use an idle machine for testing. You will need a lot of disk space to
run the tests, in excess of 100 GB. You should also ensure the test machine has plenty of
RAM, at least 16 GB.

GETTING THE TEST HARNESS
To run the test cases you must have the virt-v2v test harness.

The OCaml module is "V2v_test_harness".

The easiest way is to compile libguestfs from source (note do not install it). The test
harness will be in "virt-v2v.git/test-harness"

It is also possible to install test harness as an OCaml module.

RUNNING THE TEST CASES
Once you have checked out the freely redistributed test cases from the repository, do:

./configure [--with-test-harness=/path/to/virt-v2v/test-harness]
make
make check -k

Using the -k option is recommended so the test doesn't stop at the first failure.

PARALLEL TESTS
You can run test cases in parallel by doing:

make check -k -j<N>

(eg. -j2 for running up to 2 tests in parallel). Be careful about running too many
parallel tests, as it can slow down each test enough to cause false failures.

RUNNING TEST CASES AGAINST UPSTREAM VIRT-V2V
Using "make check" picks up whatever "virt-v2v" binary is on your $PATH.

If you have compiled libguestfs from source and want to test that version of virt-v2v, use
the libguestfs "run" script (in the top-level build directory of the libguestfs sources).
eg:

../libguestfs/run make check -k

WRITING NEW TEST CASES

       If you are interested in writing test cases, it is suggested that you start by downloading
       the freely redistributable test cases, or at least look at them online.

       Also you must have the virt-v2v test harness - see "GETTING THE TEST HARNESS" above.

   FILES IN EACH TEST CASE
       Each test case consists of:

       test.img.xz
           The disk image of the virtual machine before conversion.  Usually this should be
           converted to raw format and xz-compressed.

       test.ova
           Alternatively, an OVA, exported from VMware, may be used.

       test.xml
           The libvirt XML used as input to virt-v2v.  See the discussion of -i libvirtxml in
           virt-v2v(1).

       test.ppm
           An optional screenshot or screenshots.

           You can supply zero or more "known good" screenshots which represent intermediate
           steps where the guest is booting.  This is useful where a guest sits for some time
           doing something, and lets the test harness know that it should allow the guest to
           continue to boot.

           You can supply zero or one "final" screenshot.  This is often a screenshot of the
           login page which indicates that the guest booted successfully.

           The screenshots are captured using virsh(1).  Comparison of screenshots against the
           test images is done using the ImageMagick compare(1) program.

       test.ml
           The test itself - see below.

   WRITING THE TEST
       The test file (*.ml) is used to control the test harness, and minimally it would look
       something like this:

        open V2v_test_harness

        let test = "short_name"

        let () = run ~test ()

       That would instruct the test harness to:

       •   Uncompress short_name.img.xz

       •   Run "virt-v2v -i libvirtxml short_name.xml [...]"

       •   Boot the resulting guest and check that it writes to its disk and then the disk
           becomes idle.

       The above is a rather simplistic test.  A more realistic test is to ensure the guest
       reaches a final milestone (screenshot), eg. a login page.  To do that you have to supply a
       "~test_plan" parameter:

        open V2v_test_harness

        let test = "short_name"
        let test_plan = {
          default_plan with
            boot_plan = Boot_to_screenshot (test ^ ".ppm")
        }

        let () = run ~test ~test_plan ()

       For an even better test, you can supply post-conversion and post-boot test cases which
       examine the disk image (using libguestfs) to verify that files have been created, modified
       or deleted as expected within the disk image.  See V2v_test_harness.mli for more
       information on how to do that.

   FILES GENERATED BY RUNNING THE TEST
       When you run each test, the following files can be created:

       test-yyyymmdd-hhmmss.scrn
           Screenshot(s) of the guest’s graphical console.  These are helpful when writing tests
           or debugging test failures.

           The screenshot format is Portable Pixmap (PPM).

       test.img
           The uncompressed original disk image (before conversion).

       test-converted-sda
       test-converted.xml
           The result of conversion, ie. after running virt-v2v but before test-booting the
           guest.  See the virt-v2v(1) manual page description of -o local.

           The disk image format is qcow2.

       test-booted-sda
           The disk image after test-booting.  This is a qcow2 file which uses the
           test-converted-sda file as a backing disk, in order to save disk space.

FILES

       $ocamllibdir/v2v_test_harness/v2v_test_harness.mli
           The test library interface.  Read this for detailed programming documentation.

       "$ocamllibdir/v2v_test_harness/META"
           The findlib META file allowing you to use the library from ocamlfind(1).

       NB: To find the value of $ocamllibdir, run "ocamlc -where"

AUTHORS

       Richard W.M. Jones http://people.redhat.com/~rjones/

COPYRIGHT

       Copyright (C) 2014-2020 Red Hat Inc.

LICENSE

       This library is free software; you can redistribute it and/or modify it under the terms of
       the GNU Lesser General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU Lesser General Public License for more details.

       You should have received a copy of the GNU Lesser General Public License along with this
       library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
       Floor, Boston, MA 02110-1301 USA

BUGS

       To get a list of bugs against libguestfs, use this link:
       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

       To report a new bug against libguestfs, use this link:
       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

       When reporting a bug, please supply:

       •   The version of libguestfs.

       •   Where you got libguestfs (eg. which Linux distro, compiled from source, etc)

       •   Describe the bug accurately and give a way to reproduce it.

       •   Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug
           report.