1 | |
---|
2 | Writing Tests HOWTO |
---|
3 | =================== |
---|
4 | |
---|
5 | One goal for xm-test is to make test writing very easy. Xm-test includes |
---|
6 | a library in lib/XmTestLib that contains all the necessary methods for |
---|
7 | creating and shutting down domains. Include the library in your test by |
---|
8 | importing it: |
---|
9 | |
---|
10 | from XmTestLib import * |
---|
11 | |
---|
12 | |
---|
13 | Guidelines |
---|
14 | ========== |
---|
15 | |
---|
16 | 1. Tests should be short and single purposed. This means testing as |
---|
17 | little as possible in a single test. Do not overload tests. The more |
---|
18 | that's in a test the more difficult it is to track down what failed. |
---|
19 | |
---|
20 | 2. Tests should report as much information as possible when calling |
---|
21 | FAIL() or SKIP(). |
---|
22 | |
---|
23 | 3. A test should report SKIP() only if it cannot be run on the current |
---|
24 | machine or it makes no sense to run it. SMP tests on an UP system, |
---|
25 | for example, may not make sense. Or, there are some tests for |
---|
26 | para-virtualized guests that won't work on a fully virtualized |
---|
27 | guest. |
---|
28 | |
---|
29 | 4. Use the traceCommand() function to run commands on Domain0, the |
---|
30 | Xen management domain. This function logs everything, which is useful |
---|
31 | in case of failure. |
---|
32 | |
---|
33 | 5. Use the domain's console.runCmd method to run commands on a guest |
---|
34 | domain. This ensures logging and consistency. Please see 'Creating |
---|
35 | and Using Domains' below for an example. |
---|
36 | |
---|
37 | 6. Tests need to capture and handle libary exceptions such as: |
---|
38 | |
---|
39 | - ConsoleError can be raised when sending a command to a console. |
---|
40 | - DomainError can be raised when a domain is started, indicating |
---|
41 | a possible configuration error. |
---|
42 | - TimeoutError can be raised when the traceCommand() method is used. |
---|
43 | |
---|
44 | 7. Tests shouldn't depend on where the test is being run from or the |
---|
45 | system on which it is run. |
---|
46 | |
---|
47 | 8. Please use the existing tests for a guide, especially: |
---|
48 | |
---|
49 | - create/01_create_basic_pos.py |
---|
50 | - create/13_create_multinic_pos.py |
---|
51 | - memset/01_memset_basic_pos.py |
---|
52 | - reboot/01_reboot_basic_pos.py |
---|
53 | - migrate/01_migrate_localhost_pos.py |
---|
54 | |
---|
55 | |
---|
56 | Creating and Using Domains |
---|
57 | ========================== |
---|
58 | |
---|
59 | Xen domains, both full and para virtualized, are represented by the |
---|
60 | XmTestDomain class. The class contains methods for starting a Xen domain, |
---|
61 | shutting it down, or destroying it. Consoles, used to execute commands |
---|
62 | on guest test domains, are opened and closed through the XmTestDomain |
---|
63 | class. Devices, which are represented by the XenDevice class, are also |
---|
64 | added and removed using XmTestDomain methods. |
---|
65 | |
---|
66 | Here's a simple example for creating a domain, opening a console, running |
---|
67 | a command, and then shutting down the domain: |
---|
68 | |
---|
69 | 1) Create a domain: |
---|
70 | |
---|
71 | domain = XmTestDomain() |
---|
72 | |
---|
73 | 2) Start the domain and grab a console: |
---|
74 | |
---|
75 | try: |
---|
76 | console = domain.start() |
---|
77 | except DomainError, e: |
---|
78 | if verbose: |
---|
79 | print "Failed to create test domain because:" |
---|
80 | print e.extra |
---|
81 | FAIL(str(e)) |
---|
82 | |
---|
83 | 3) Run a command inside the new domain using the console, saving the |
---|
84 | console log if an error is encountered: |
---|
85 | |
---|
86 | try: |
---|
87 | # Run 'ls' |
---|
88 | run = console.runCmd("ls") |
---|
89 | except ConsoleError, e: |
---|
90 | saveLog(console.getHistory()) |
---|
91 | FAIL(str(e)) |
---|
92 | |
---|
93 | 4) Stop the domain, which nicely shuts it down: |
---|
94 | |
---|
95 | domain.stop() |
---|
96 | |
---|
97 | |
---|
98 | Writing Tests with Networking |
---|
99 | ============================= |
---|
100 | |
---|
101 | The xm-test suite includes the ability to test networking for domains. |
---|
102 | Networking is configured at configuration time. While testing NAT and |
---|
103 | routing environments in the future, the current xm-test only supports |
---|
104 | a bridging environment. Xm-test currently only supports a range of |
---|
105 | IPs, the dhcp feature will be added soon. |
---|
106 | |
---|
107 | The network tests will need to know what IPs to use. IPs are configured |
---|
108 | when you build xm-test. Xm-test uses the zeroconf address range by |
---|
109 | default, 169.254.0.1-169.254.255.255. If you'd like to set a new range, |
---|
110 | do so at configure time, a netmask and network address must also be defined: |
---|
111 | |
---|
112 | # ./configure --with-net-ip-range=192.168.1.1-192.168.1.100 --with-network-address=192.168.1.0 --with-netmask=255.255.255.0 |
---|
113 | |
---|
114 | The tests will not need to set network information, this is done by |
---|
115 | the library once it's configured. |
---|
116 | |
---|
117 | As mentioned above, xm-test's goal is to make writing tests easy. Creating |
---|
118 | domains with networking should also be easy. To create a domain with |
---|
119 | a single network interface, tests can use a XmTestNetDomain object. It |
---|
120 | creates a XenNetDevice for the domain automatically using the pre-configured |
---|
121 | IP information. Otherwise, a network interface can be added to a domain |
---|
122 | prior to starting it (the ability to attach devices will be added): |
---|
123 | |
---|
124 | domain = XmTestDomain() |
---|
125 | domain.newDevice(XenNetDevice, "eth0") |
---|
126 | domain.newDevice(XenNetDevice, "eth1") |
---|
127 | |
---|
128 | Here, the domain is created and then the XenDomain factory newDevice |
---|
129 | is called to create a new device of class XenNetDevice to the domain. |
---|
130 | The xm-test library will automatically assign an IP from the configured |
---|
131 | list, execute ifconfig on the guest domain console, and create an |
---|
132 | alias on Domain0. |
---|
133 | |
---|
134 | |
---|