ia64/xen-unstable

view tools/xm-test/README @ 8740:3d7ea7972b39

Update patches for linux 2.6.15.

Signed-off-by: Christian Limpach <Christian.Limpach@cl.cam.ac.uk>
author cl349@firebug.cl.cam.ac.uk
date Thu Feb 02 17:16:00 2006 +0000 (2006-02-02)
parents f1b361b05bf3
children b41e19644271
line source
2 xm-test README
4 Copyright (C) International Business Machines Corp., 2005
5 Author(s): Dan Smith <danms@us.ibm.com>
6 Woody Marvel <marvel@us.ibm.com>
8 Overview
9 ========
11 This suite provides a framework for testing the Xen userspace tools.
12 The directory structure is:
14 ./xm-test
15 |
16 +-/lib: Python support libraries
17 |
18 +-/ramdisk: Staging area for building the test ramdisk
19 |
20 +-/tests
21 | |
22 | +-/create: Tests for the 'xm create' command
23 | +-/destroy: Tests for the 'xm destroy' command
24 | . . .
25 |
26 +-/utils: Utility scripts for ramdisk building
28 Reports are posted here:
30 http://xmtest.dague.org
33 Building
34 ========
36 Before the test suite can be used, the ramdisk must be built from
37 source. All source needed for this process is automatically
38 downloaded, extracted, and compiled. Due to the need to create
39 special files, this process must be done as root:
41 # ./autogen
42 # ./configure
43 # make
45 NB: If you have the initrd.img from another installation of xm-test,
46 you can copy it into the ramdisk directory to eliminate the need to
47 rebuild it. If you do this, there is no need to run 'make' again.
48 Simply copy the initrd-X.Y.img file into ramdisk/ and then run:
50 # make existing
52 This will set up the link so that xm-test will use the existing
53 ramdisk. Next, just run "runtest.sh" normally. Note that in general,
54 you should not attempt to use a ramdisk from a previous minor version
55 of xm-test (i.e., don't use a ramdisk from 0.4.0 with 0.5.0. 0.5.0
56 should work for 0.5.3 though)
59 BUILDING with HVM Support
60 =========================
62 If you'd like to build and run this with hardware virtual machine assist
63 (HVM) support to test fully virtualized disk images on VMX/SVM hardware,
64 please add the --enable-hvm-support option to configure:
66 # ./autogen
67 # ./configure --enable-hvm-support
68 # make
70 The ramdisk/bin/create_disk_image script, which builds the full virt
71 disk.img, requires Lilo 22.7+ to be installed on the system. Lilo is
72 used to install the bootloader on the disk.img.
74 If HVM support is enabled, the ramdisk/bin/create_disk_image script
75 will be run to create a full virt disk.img in the ramdisk directory. The
76 script, by default, will look in /boot for the first non-Xen kernel it
77 runs across. If you'd like to set xm-test to use a specific kernel,
78 rather than the first one it finds in /boot, you can configure it in
79 with the "--with-hvm-kernel=KERNEL" option:
81 # ./autogen
82 # ./configure --enable-hvm-support --with-hvm-kernel=KERNEL
83 # make
85 Otherwise, you can always rerun the create script using the -k option
86 to use a specific kernel.
88 The disk.img created for HVM testing must contain a pcnet32 driver for
89 network tests. The ramdisk/bin/create_disk_image script will, by default,
90 look in the /lib/modules directory associated with the kernel being
91 used. If you'd like to specify a different location for the driver or
92 want to tell the script that the driver is built into the kernel, please
93 use the "--with-driver-dir=DRVDIR" configure option. If built into
94 the kernel, please use the key word "builtin" with the option:
96 # ./autogen
97 # ./configure --enable-hvm-support --with-driver-dir=builtin
98 - or -
99 # ./configure --enable-hvm-support --with-driver-dir=/driver/directory
100 # make
102 Xm-test will look for disk.img in the ramdisk directory when run by
103 default.
106 Running
107 =======
109 To run the full test suite, do the following as root:
111 # ./runtest.sh <logfile>
113 This will run all tests, as well as generate and submit a report at
114 the end. All output files will begin with "<logfile>." If you wish to
115 prevent submission of a report, add "-d" to the command line like this:
117 # ./runtest.sh -d <logfile>
119 It may be useful to run tests without submission as above, and then
120 submit the report at a later time. To do so, run runtest.sh with the
121 -s flag and the name of the previously-generated report:
123 # ./runtest.sh -s <logfile>
125 For people needing a quick test run instead the full suite, a quick
126 mode has been added that will attempt to run a representative subset
127 of tests. This is not a substitute for the whole suite, but will
128 verify that some of the major functions of xen and xm are working:
130 # ./runtest.sh -q <logfile>
132 Because of the current structure of the reporting software, submission
133 of quick test run results is not supported.
135 It may be desirable to run a specific test group. This can be
136 accomplished by doing the following:
138 # cd tests/create
139 # TEST_VERBOSE=1 make check
141 When developing or debugging a specific feature, a single test can be
142 run to avoid having to run even a whole test group:
144 # cd tests/create
145 # TEST_VERBOSE=1 make check TESTS=01_create_basic_pos.test
147 The runtest.sh script will create several files, including a .report
148 file, which is the cleaned up, email-friendly report of failures.
149 Additionally, the script will submit your results to the development
150 team for trend analysis. This helps us determine the level of success
151 people "out there" are having with different versions of Xen.
153 Note: you should generally run xm-test with a minimum of memory
154 allocated to Dom0. More memory available for allocation to DomUs
155 means a more rigorous test.
157 BIG FAT WARNING: The test framework assumes it is running on a
158 dedicated machine. As such, the library automatically destroys any
159 running DomUs on the system to provide each test with a "clean slate".
162 Extending
163 =========
165 Additional tests may be added in existing groups to test additional
166 cases for a given xm subcommand. Test programs should be named
167 according to the following scheme:
169 XY_group_name_{pos,neg}.py
171 Where:
172 XY is the next number in line
173 group is the name of the subcommand being tested
174 name is the short name of the test
175 {pos,neg} denotes whether this is a positive or negative test case
177 New subcommand groups should be added as directories named after the
178 subcommand itself. The "Makefile.am.template" should be copied into
179 the new group directory as "Makefile.am".
181 See the Writing_Tests_HOWTO file for more detailed information on
182 adding tests to the suite.
185 Developer Notes
186 ===============
188 Our library provides a DomU console abstraction for automated
189 execution of commands. Please note that this is relatively fragile,
190 and is intended for use only with the ramdisk built by the framework.
191 Because the console experiences some occasional corruption, this
192 method is not completely perfect at the moment, although the authors
193 use it with relatively few problems.
196 Known Issues
197 ============
200 Reporting Bugs
201 ==============
203 If you find a bug in the test framework, report it to:
205 Dan Smith <danms@us.ibm.com>
207 If you find a bug in a specific test case, contact the author of the
208 test case first.