virt-v2v-test-harness(1)

📦 version 1.44.2, in ubuntu jammy

💖 virt-v2v-test-harness 💖

okay bestie, sit down, hydrate, because we're about to get into virt-v2v-test-harness(1), a lil' page from the Virtualization Support corner of the manual-verse. it's giving niche, it's giving powerful, and honestly? it ate. ✨

🌸 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 🦋

so virt-v2v(1) is the icon that converts guests from a foreign hypervisor over to KVM, and KVM is managed by libvirt, OpenStack, oVirt, Red Hat Virtualisation (RHV), or honestly several other targets too. main character energy tbh.

Virt-v2v-test-harness is a small library — the module name is V2v_test_harness — and what it does is run virt-v2v against a set of test cases made of actual real virtual machines. not vibes. real VMs. 💅

it's a test harness, so here's the whole arc: it grabs a test case, runs virt-v2v on it (non-destructively, we're not chaotic), then test-boots the result. it can confirm the test case converts successfully, boots successfully, and reaches a milestone — like a particular screenshot, bestie. it can also check that the conversion created, modified, or deleted the files it was supposed to from inside the guest. no cap.

🌈 GETTING THE TEST CASES 🌈

because the test cases are actual virtual machines, we split them into two groups: ones that are freely redistributable and ones that are proprietary. the free ones are stuff like Fedora or CentOS images, which are free software. the proprietary ones 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 live at:

 http://git.annexia.org/?p=virt-v2v-test-cases-nonfree.git

and heads up — that one does not contain the proprietary images themselves, because those are not made available to the public for licensing reasons. it's giving legally unbothered only in theory.

the test cases consist of disk images that are very large, like from 250 MB all the way through to tens of gigabytes each. so distributing them can be super time-consuming and expensive, fr fr. that's why 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 make sure 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 the test harness as an OCaml module. slay, options. 💅

🌸 RUNNING THE TEST CASES 🌸

once you've 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. because bestie, we keep going. 💪

🦄 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). but be careful about running too many parallel tests, because it can slow down each test enough to cause false failures. don't do too much. 🙈

💖 RUNNING TEST CASES AGAINST UPSTREAM VIRT-V2V 💖

using make check picks up whatever virt-v2v binary is on your $PATH.

if you've compiled libguestfs from source and want to test that version of virt-v2v, use the libguestfs run script (it's in the top-level build directory of the libguestfs sources). eg:

 ../libguestfs/run make check -k

⭐ WRITING NEW TEST CASES ⭐

if you're interested in writing test cases, the suggestion is you start by downloading the freely redistributable test cases, or at minimum 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 it 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. so economical. 💅

💜 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"

🫶 SEE ALSO 🫶

virt-v2v(1), virt-p2v(1), guestfs(3), virsh(1), compare(1), git-annex(1), http://libguestfs.org/.

👑 AUTHORS 👑

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

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. 🙏

and that's the whole page bestie!! this came from virt-v2v-1.44.2, dated 2021-12-25 (a lil christmas gift, iconic), and it's the virt-v2v-test-harness(1) page. go forth and test, you absolute legend 🦋✨💖

📦 where this page comes from