.\" Automatically generated by Podwrapper::Man 1.40.2 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "virt-v2v-test-harness 1"
.TH virt-v2v-test-harness 1 "2019-02-07" "libguestfs-1.40.2" "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "名前"
.IX Header "名前"
virt\-v2v\-test\-harness \- Used to test virt\-v2v against real test cases
.SH "書式"
.IX Header "書式"
.Vb 1
\& 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 ()
.Ve
.SH "説明"
.IX Header "説明"
\&\fBvirt\-v2v\fR\|(1) converts guests from a foreign hypervisor to run on \s-1KVM,\s0
managed by libvirt, OpenStack, oVirt, Red Hat Virtualisation (\s-1RHV\s0) or
several other targets.
.PP
Virt\-v2v\-test\-harness is a small library (module name: \f(CW\*(C`V2v_test_harness\*(C'\fR)
used to run virt\-v2v against a set of test cases consisting of real virtual
machines.
.PP
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.
.SS "\s-1GETTING THE TEST CASES\s0"
.IX Subsection "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.
.PP
The freely redistributable test cases can be downloaded from:
http://git.annexia.org/?p=virt\-v2v\-test\-cases\-free.git \fI\f(BInot available
yet\fI\fR
.PP
The proprietary test cases are available at
http://git.annexia.org/?p=virt\-v2v\-test\-cases\-nonfree.git This \fIdoes
not\fR contain the proprietary images themselves, which are not made available
to the public for licensing reasons.
.PP
The test cases consist of disk images which are very large, from 250 \s-1MB\s0
through to tens of gigabytes \fIeach\fR.  This means that distributing test
cases can be very time-consuming and expensive.  We use \fBgit\-annex\fR\|(1) to
distribute the test images.
.SS "\s-1REQUIREMENTS\s0"
.IX Subsection "REQUIREMENTS"
It’s recommended to use an idle machine for testing.  You will need \fBa lot
of disk space\fR to run the tests, in excess of 100 \s-1GB.\s0  You should also
ensure the test machine has plenty of \s-1RAM,\s0 at least 16 \s-1GB.\s0
.SS "\s-1GETTING THE TEST HARNESS\s0"
.IX Subsection "GETTING THE TEST HARNESS"
To run the test cases you must have the virt\-v2v test harness.
.PP
The OCaml module is \f(CW\*(C`V2v_test_harness\*(C'\fR.
.PP
The easiest way is to compile libguestfs from source (\fInote\fR do not install
it).  The test harness will be in \f(CW\*(C`libguestfs/v2v/test\-harness\*(C'\fR
.PP
It is also possible to install test harness as an OCaml module.
.SS "\s-1RUNNING THE TEST CASES\s0"
.IX Subsection "RUNNING THE TEST CASES"
Once you have checked out the freely redistributed test cases from the
repository, do:
.PP
.Vb 3
\& ./configure [\-\-with\-test\-harness=/path/to/libguestfs/v2v/test\-harness]
\& make
\& make check \-k
.Ve
.PP
Using the \fI\-k\fR option is recommended so the test doesn't stop at the first
failure.
.SS "\s-1PARALLEL TESTS\s0"
.IX Subsection "PARALLEL TESTS"
You can run test cases in parallel by doing:
.PP
.Vb 1
\& make check \-k \-j<N>
.Ve
.PP
(eg. \fI\-j2\fR 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.
.SS "\s-1RUNNING TEST CASES AGAINST UPSTREAM VIRT\-V2V\s0"
.IX Subsection "RUNNING TEST CASES AGAINST UPSTREAM VIRT-V2V"
Using \f(CW\*(C`make check\*(C'\fR picks up whatever \f(CW\*(C`virt\-v2v\*(C'\fR binary is on your
\&\f(CW$PATH\fR.
.PP
If you have compiled libguestfs from source and want to test that version of
virt\-v2v, use the libguestfs \f(CW\*(C`run\*(C'\fR script (in the top-level build directory
of the libguestfs sources).  eg:
.PP
.Vb 1
\& ../libguestfs/run make check \-k
.Ve
.SH "WRITING NEW TEST CASES"
.IX Header "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.
.PP
Also you must have the virt\-v2v test harness \- see \*(L"\s-1GETTING THE TEST
HARNESS\*(R"\s0 above.
.SS "\s-1FILES IN EACH TEST CASE\s0"
.IX Subsection "FILES IN EACH TEST CASE"
Each test case consists of:
.IP "\fItest\fR.img.xz" 4
.IX Item "test.img.xz"
The disk image of the virtual machine before conversion.  Usually this
should be converted to raw format and xz-compressed.
.IP "\fItest\fR.ova" 4
.IX Item "test.ova"
Alternatively, an \s-1OVA,\s0 exported from VMware, may be used.
.IP "\fItest\fR.xml" 4
.IX Item "test.xml"
The libvirt \s-1XML\s0 used as input to virt\-v2v.  See the discussion of \fI\-i
libvirtxml\fR in \fBvirt\-v2v\fR\|(1).
.IP "\fItest\fR.ppm" 4
.IX Item "test.ppm"
An optional screenshot or screenshots.
.Sp
You can supply zero or more \*(L"known good\*(R" 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.
.Sp
You can supply zero or one \*(L"final\*(R" screenshot.  This is often a screenshot
of the login page which indicates that the guest booted successfully.
.Sp
The screenshots are captured using \fBvirsh\fR\|(1).  Comparison of screenshots
against the test images is done using the ImageMagick \fBcompare\fR\|(1) program.
.IP "\fItest\fR.ml" 4
.IX Item "test.ml"
The test itself \- see below.
.SS "\s-1WRITING THE TEST\s0"
.IX Subsection "WRITING THE TEST"
The test file (\fI*.ml\fR) is used to control the test harness, and minimally
it would look something like this:
.PP
.Vb 1
\& open V2v_test_harness
\& 
\& let test = "short_name"
\& 
\& let () = run ~test ()
.Ve
.PP
That would instruct the test harness to:
.IP "\(bu" 4
Uncompress \fI\fIshort_name\fI.img.xz\fR
.IP "\(bu" 4
Run \f(CW\*(C`virt\-v2v \-i libvirtxml \f(CIshort_name\f(CW.xml [...]\*(C'\fR
.IP "\(bu" 4
Boot the resulting guest and check that it writes to its disk and then the
disk becomes idle.
.PP
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 \f(CW\*(C`~test_plan\*(C'\fR parameter:
.PP
.Vb 1
\& 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 ()
.Ve
.PP
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 \fIV2v_test_harness.mli\fR for more information on how to do that.
.SS "\s-1FILES GENERATED BY RUNNING THE TEST\s0"
.IX Subsection "FILES GENERATED BY RUNNING THE TEST"
When you run each test, the following files can be created:
.IP "\fItest\fR\-\fIyyyymmdd-hhmmss\fR.scrn" 4
.IX Item "test-yyyymmdd-hhmmss.scrn"
Screenshot(s) of the guest’s graphical console.  These are helpful when
writing tests or debugging test failures.
.Sp
The screenshot format is Portable Pixmap (\s-1PPM\s0).
.IP "\fItest\fR.img" 4
.IX Item "test.img"
The uncompressed original disk image (before conversion).
.IP "\fItest\fR\-converted\-sda" 4
.IX Item "test-converted-sda"
.PD 0
.IP "\fItest\fR\-converted.xml" 4
.IX Item "test-converted.xml"
.PD
The result of conversion, ie. after running virt\-v2v but before test-booting
the guest.  See the \fBvirt\-v2v\fR\|(1) manual page description of \fI\-o local\fR.
.Sp
The disk image format is qcow2.
.IP "\fItest\fR\-booted\-sda" 4
.IX Item "test-booted-sda"
The disk image after test-booting.  This is a qcow2 file which uses the
\&\fItest\fR\-converted\-sda file as a backing disk, in order to save disk space.
.SH "ファイル"
.IX Header "ファイル"
.IP "\fI\f(CI$ocamllibdir\fI/v2v_test_harness/v2v_test_harness.mli\fR" 4
.IX Item "$ocamllibdir/v2v_test_harness/v2v_test_harness.mli"
The test library interface.  Read this for detailed programming
documentation.
.ie n .IP """$ocamllibdir/v2v_test_harness/META""" 4
.el .IP "\f(CW$ocamllibdir/v2v_test_harness/META\fR" 4
.IX Item "$ocamllibdir/v2v_test_harness/META"
The findlib \s-1META\s0 file allowing you to use the library from \fBocamlfind\fR\|(1).
.PP
\&\s-1NB:\s0 To find the value of \f(CW$ocamllibdir\fR, run \f(CW\*(C`ocamlc \-where\*(C'\fR
.SH "関連項目"
.IX Header "関連項目"
\&\fBvirt\-v2v\fR\|(1), \fBvirt\-p2v\fR\|(1), \fBguestfs\fR\|(3), \fBvirsh\fR\|(1), \fBcompare\fR\|(1),
\&\fBgit\-annex\fR\|(1), http://libguestfs.org/.
.SH "著者"
.IX Header "著者"
Richard W.M. Jones http://people.redhat.com/~rjones/
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2014\-2019 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
.SH "BUGS"
.IX Header "BUGS"
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
When reporting a bug, please supply:
.IP "\(bu" 4
The version of libguestfs.
.IP "\(bu" 4
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
.IP "\(bu" 4
Describe the bug accurately and give a way to reproduce it.
.IP "\(bu" 4
Run \fBlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR
output into the bug report.