1virt-v2v-test-harness(1)    Virtualization Support    virt-v2v-test-harness(1)
2
3
4

NAME

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

SYNOPSIS

9        open V2v_test_harness
10
11        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
17        let () = run ~test ~test_plan ()
18

DESCRIPTION

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
24       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
28       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
35   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
42       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
46       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
51       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
56   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
61   GETTING THE TEST HARNESS
62       To run the test cases you must have the virt-v2v test harness.
63
64       The OCaml module is "V2v_test_harness".
65
66       The easiest way is to compile libguestfs from source (note do not
67       install it).  The test harness will be in "virt-v2v.git/test-harness"
68
69       It is also possible to install test harness as an OCaml module.
70
71   RUNNING THE TEST CASES
72       Once you have checked out the freely redistributed test cases from the
73       repository, do:
74
75        ./configure [--with-test-harness=/path/to/virt-v2v/test-harness]
76        make
77        make check -k
78
79       Using the -k option is recommended so the test doesn't stop at the
80       first failure.
81
82   PARALLEL TESTS
83       You can run test cases in parallel by doing:
84
85        make check -k -j<N>
86
87       (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
91   RUNNING TEST CASES AGAINST UPSTREAM VIRT-V2V
92       Using "make check" picks up whatever "virt-v2v" binary is on your
93       $PATH.
94
95       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
99        ../libguestfs/run make check -k
100

WRITING NEW TEST CASES

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
106       Also you must have the virt-v2v test harness - see "GETTING THE TEST
107       HARNESS" above.
108
109   FILES IN EACH TEST CASE
110       Each test case consists of:
111
112       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
116       test.ova
117           Alternatively, an OVA, exported from VMware, may be used.
118
119       test.xml
120           The libvirt XML used as input to virt-v2v.  See the discussion of
121           -i libvirtxml in virt-v2v(1).
122
123       test.ppm
124           An optional screenshot or screenshots.
125
126           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
132           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
136           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
140       test.ml
141           The test itself - see below.
142
143   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
147        open V2v_test_harness
148
149        let test = "short_name"
150
151        let () = run ~test ()
152
153       That would instruct the test harness to:
154
155       ·   Uncompress short_name.img.xz
156
157       ·   Run "virt-v2v -i libvirtxml short_name.xml [...]"
158
159       ·   Boot the resulting guest and check that it writes to its disk and
160           then the disk becomes idle.
161
162       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
166        open V2v_test_harness
167
168        let test = "short_name"
169        let test_plan = {
170          default_plan with
171            boot_plan = Boot_to_screenshot (test ^ ".ppm")
172        }
173
174        let () = run ~test ~test_plan ()
175
176       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
182   FILES GENERATED BY RUNNING THE TEST
183       When you run each test, the following files can be created:
184
185       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
189           The screenshot format is Portable Pixmap (PPM).
190
191       test.img
192           The uncompressed original disk image (before conversion).
193
194       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
200           The disk image format is qcow2.
201
202       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

FILES

208       $ocamllibdir/v2v_test_harness/v2v_test_harness.mli
209           The test library interface.  Read this for detailed programming
210           documentation.
211
212       "$ocamllibdir/v2v_test_harness/META"
213           The findlib META file allowing you to use the library from
214           ocamlfind(1).
215
216       NB: To find the value of $ocamllibdir, run "ocamlc -where"
217

SEE ALSO

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

AUTHORS

223       Richard W.M. Jones http://people.redhat.com/~rjones/
224
226       Copyright (C) 2014-2020 Red Hat Inc.
227

LICENSE

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
234       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
239       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

BUGS

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
248       To report a new bug against libguestfs, use this link:
249       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
250
251       When reporting a bug, please supply:
252
253       ·   The version of libguestfs.
254
255       ·   Where you got libguestfs (eg. which Linux distro, compiled from
256           source, etc)
257
258       ·   Describe the bug accurately and give a way to reproduce it.
259
260       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
261           into the bug report.
262
263
264
265virt-v2v-1.43.1                   2020-06-19          virt-v2v-test-harness(1)
Impressum