1virt-v2v-test-harness(1) Virtualization Support virt-v2v-test-harness(1)
2
6 virt-v2v-test-harness - Used to test virt-v2v against real test cases
7
9 open V2v_test_harness
10 let test = "rhel_45_i386_fv"
12 let test_plan = {
13 default_plan with
14 boot_plan = Boot_to_screenshot (test ^ "-login.ppm")
15 }
16 let () = run ~test ~test_plan ()
18
20 virt-v2v(1) converts guests from a foreign hypervisor to run on KVM,
21 managed by libvirt, OpenStack, oVirt, Red Hat Virtualisation (RHV) or
22 several other targets.
23 Virt-v2v-test-harness is a small library (module name:
25 "V2v_test_harness") used to run virt-v2v against a set of test cases
26 consisting of real virtual machines.
27 It acts as a test harness, taking a test case, running virt-v2v on it
29 (non-destructively), then test-booting the result. It can ensure that
30 the test case converts successfully, boots successfully, and reaches a
31 milestone (such as a particular screenshot). It can also test that the
32 conversion created, modified or deleted the expected files from within
33 the guest.
34 GETTING THE TEST CASES
36 Because the test cases are actual virtual machines, we split them into
37 two groups: test cases which are freely redistributable and those which
38 are proprietary. The former are things like Fedora or CentOS images,
39 which are free software. The latter are things like Windows or Red Hat
40 Enterprise Linux.
41 The freely redistributable test cases can be downloaded from:
43 http://git.annexia.org/?p=virt-v2v-test-cases-free.git not available
44 yet
45 The proprietary test cases are available at
47 http://git.annexia.org/?p=virt-v2v-test-cases-nonfree.git This does not
48 contain the proprietary images themselves, which are not made available
49 to the public for licensing reasons.
50 The test cases consist of disk images which are very large, from 250 MB
52 through to tens of gigabytes each. This means that distributing test
53 cases can be very time-consuming and expensive. We use git-annex(1) to
54 distribute the test images.
55 REQUIREMENTS
57 It’s recommended to use an idle machine for testing. You will need a
58 lot of disk space to run the tests, in excess of 100 GB. You should
59 also ensure the test machine has plenty of RAM, at least 16 GB.
60 GETTING THE TEST HARNESS
62 To run the test cases you must have the virt-v2v test harness.
63 The OCaml module is "V2v_test_harness".
65 The easiest way is to compile libguestfs from source (note do not
67 install it). The test harness will be in "libguestfs/v2v/test-harness"
68 It is also possible to install test harness as an OCaml module.
70 RUNNING THE TEST CASES
72 Once you have checked out the freely redistributed test cases from the
73 repository, do:
74 ./configure [--with-test-harness=/path/to/libguestfs/v2v/test-harness]
76 make
77 make check -k
78 Using the -k option is recommended so the test doesn't stop at the
80 first failure.
81 PARALLEL TESTS
83 You can run test cases in parallel by doing:
84 make check -k -j<N>
86 (eg. -j2 for running up to 2 tests in parallel). Be careful about
88 running too many parallel tests, as it can slow down each test enough
89 to cause false failures.
90 RUNNING TEST CASES AGAINST UPSTREAM VIRT-V2V
92 Using "make check" picks up whatever "virt-v2v" binary is on your
93 $PATH.
94 If you have compiled libguestfs from source and want to test that
96 version of virt-v2v, use the libguestfs "run" script (in the top-level
97 build directory of the libguestfs sources). eg:
98 ../libguestfs/run make check -k
100
102 If you are interested in writing test cases, it is suggested that you
103 start by downloading the freely redistributable test cases, or at least
104 look at them online.
105 Also you must have the virt-v2v test harness - see "GETTING THE TEST
107 HARNESS" above.
108 FILES IN EACH TEST CASE
110 Each test case consists of:
111 test.img.xz
113 The disk image of the virtual machine before conversion. Usually
114 this should be converted to raw format and xz-compressed.
115 test.ova
117 Alternatively, an OVA, exported from VMware, may be used.
118 test.xml
120 The libvirt XML used as input to virt-v2v. See the discussion of
121 -i libvirtxml in virt-v2v(1).
122 test.ppm
124 An optional screenshot or screenshots.
125 You can supply zero or more "known good" screenshots which
127 represent intermediate steps where the guest is booting. This is
128 useful where a guest sits for some time doing something, and lets
129 the test harness know that it should allow the guest to continue to
130 boot.
131 You can supply zero or one "final" screenshot. This is often a
133 screenshot of the login page which indicates that the guest booted
134 successfully.
135 The screenshots are captured using virsh(1). Comparison of
137 screenshots against the test images is done using the ImageMagick
138 compare(1) program.
139 test.ml
141 The test itself - see below.
142 WRITING THE TEST
144 The test file (*.ml) is used to control the test harness, and minimally
145 it would look something like this:
146 open V2v_test_harness
148 let test = "short_name"
150 let () = run ~test ()
152 That would instruct the test harness to:
154 · Uncompress short_name.img.xz
156 · Run "virt-v2v -i libvirtxml short_name.xml [...]"
158 · Boot the resulting guest and check that it writes to its disk and
160 then the disk becomes idle.
161 The above is a rather simplistic test. A more realistic test is to
163 ensure the guest reaches a final milestone (screenshot), eg. a login
164 page. To do that you have to supply a "~test_plan" parameter:
165 open V2v_test_harness
167 let test = "short_name"
169 let test_plan = {
170 default_plan with
171 boot_plan = Boot_to_screenshot (test ^ ".ppm")
172 }
173 let () = run ~test ~test_plan ()
175 For an even better test, you can supply post-conversion and post-boot
177 test cases which examine the disk image (using libguestfs) to verify
178 that files have been created, modified or deleted as expected within
179 the disk image. See V2v_test_harness.mli for more information on how
180 to do that.
181 FILES GENERATED BY RUNNING THE TEST
183 When you run each test, the following files can be created:
184 test-yyyymmdd-hhmmss.scrn
186 Screenshot(s) of the guest’s graphical console. These are helpful
187 when writing tests or debugging test failures.
188 The screenshot format is Portable Pixmap (PPM).
190 test.img
192 The uncompressed original disk image (before conversion).
193 test-converted-sda
195 test-converted.xml
196 The result of conversion, ie. after running virt-v2v but before
197 test-booting the guest. See the virt-v2v(1) manual page
198 description of -o local.
199 The disk image format is qcow2.
201 test-booted-sda
203 The disk image after test-booting. This is a qcow2 file which uses
204 the test-converted-sda file as a backing disk, in order to save
205 disk space.
206
208 $ocamllibdir/v2v_test_harness/v2v_test_harness.mli
209 The test library interface. Read this for detailed programming
210 documentation.
211 "$ocamllibdir/v2v_test_harness/META"
213 The findlib META file allowing you to use the library from
214 ocamlfind(1).
215 NB: To find the value of $ocamllibdir, run "ocamlc -where"
217
219 virt-v2v(1), virt-p2v(1), guestfs(3), virsh(1), compare(1),
220 git-annex(1), http://libguestfs.org/.
221
223 Richard W.M. Jones http://people.redhat.com/~rjones/
224
226 Copyright (C) 2014-2019 Red Hat Inc.
227
229 This library is free software; you can redistribute it and/or modify it
230 under the terms of the GNU Lesser General Public License as published
231 by the Free Software Foundation; either version 2 of the License, or
232 (at your option) any later version.
233 This library is distributed in the hope that it will be useful, but
235 WITHOUT ANY WARRANTY; without even the implied warranty of
236 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
237 Lesser General Public License for more details.
238 You should have received a copy of the GNU Lesser General Public
240 License along with this library; if not, write to the Free Software
241 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
242 02110-1301 USA
243
245 To get a list of bugs against libguestfs, use this link:
246 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
247 To report a new bug against libguestfs, use this link:
249 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
250 When reporting a bug, please supply:
252 · The version of libguestfs.
254 · Where you got libguestfs (eg. which Linux distro, compiled from
256 source, etc)
257 · Describe the bug accurately and give a way to reproduce it.
259 · Run libguestfs-test-tool(1) and paste the complete, unedited output
261 into the bug report.
262libguestfs-1.40.1 2019-01-17 virt-v2v-test-harness(1)