view tools/xm-test/README @ 8405:fd1488b1132c

Added information for running xm-test in HVM / VMX mode.

Signed-off-by: Daniel Stekloff <dsteklof@us.ibm.com>
author stekloff@elm3b216.beaverton.ibm.com
date Fri Dec 16 11:50:27 2005 +0000 (2005-12-16)
parents ab845d97de72
children cd68f36807f9
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)
58 If you'd like to build and run this with hardware virtual machine assist
59 (HVM) support to test fully virtualized disk images on VMX hardware,
60 please add the --enable-vmx-support option to configure:
62 # ./autogen
63 # ./configure --enable-vmx-support
64 # make
66 The ramdisk/bin/create_disk_image script, which builds the full virt
67 disk.img, requires Lilo 22.7+ to be installed on the system. Lilo is
68 used to install the bootloader on the disk.img.
70 If HVM / VMX support is enabled, the ramdisk/bin/create_disk_image script
71 will be run to create a full virt disk.img in the ramdisk directory. The
72 script, by default, will look in /boot for the first non-Xen kernel it
73 runs across. If you wish to use a different kernel or the script fails
74 to find a kernel, please run the script manually to make a disk.img
75 using the -k option. Xm-test will look for disk.img in the ramdisk
76 directory when run by default.
79 Running
80 =======
82 To run the full test suite, do the following as root:
84 # ./runtest.sh <logfile>
86 This will run all tests, as well as generate and submit a report at
87 the end. All output files will begin with "<logfile>." If you wish to
88 prevent submission of a report, add "-d" to the command line like this:
90 # ./runtest.sh -d <logfile>
92 It may be useful to run tests without submission as above, and then
93 submit the report at a later time. To do so, run runtest.sh with the
94 -s flag and the name of the previously-generated report:
96 # ./runtest.sh -s <logfile>
98 For people needing a quick test run instead the full suite, a quick
99 mode has been added that will attempt to run a representative subset
100 of tests. This is not a substitute for the whole suite, but will
101 verify that some of the major functions of xen and xm are working:
103 # ./runtest.sh -q <logfile>
105 Because of the current structure of the reporting software, submission
106 of quick test run results is not supported.
108 It may be desirable to run a specific test group. This can be
109 accomplished by doing the following:
111 # cd tests/create
112 # TEST_VERBOSE=1 make check
114 When developing or debugging a specific feature, a single test can be
115 run to avoid having to run even a whole test group:
117 # cd tests/create
118 # TEST_VERBOSE=1 make check TESTS=01_create_basic_pos.test
120 The runtest.sh script will create several files, including a .report
121 file, which is the cleaned up, email-friendly report of failures.
122 Additionally, the script will submit your results to the development
123 team for trend analysis. This helps us determine the level of success
124 people "out there" are having with different versions of Xen.
126 Note: you should generally run xm-test with a minimum of memory
127 allocated to Dom0. More memory available for allocation to DomUs
128 means a more rigorous test.
130 BIG FAT WARNING: The test framework assumes it is running on a
131 dedicated machine. As such, the library automatically destroys any
132 running DomUs on the system to provide each test with a "clean slate".
135 Extending
136 =========
138 Additional tests may be added in existing groups to test additional
139 cases for a given xm subcommand. Test programs should be named
140 according to the following scheme:
142 XY_group_name_{pos,neg}.py
144 Where:
145 XY is the next number in line
146 group is the name of the subcommand being tested
147 name is the short name of the test
148 {pos,neg} denotes whether this is a positive or negative test case
150 New subcommand groups should be added as directories named after the
151 subcommand itself. The "Makefile.am.template" should be copied into
152 the new group directory as "Makefile.am".
154 See the Writing_Tests_HOWTO file for more detailed information on
155 adding tests to the suite.
158 Developer Notes
159 ===============
161 Our library provides a DomU console abstraction for automated
162 execution of commands. Please note that this is relatively fragile,
163 and is intended for use only with the ramdisk built by the framework.
164 Because the console experiences some occasional corruption, this
165 method is not completely perfect at the moment, although the authors
166 use it with relatively few problems.
169 Known Issues
170 ============
173 Reporting Bugs
174 ==============
176 If you find a bug in the test framework, report it to:
178 Dan Smith <danms@us.ibm.com>
180 If you find a bug in a specific test case, contact the author of the
181 test case first.