ia64/xen-unstable

changeset 9938:39fa9a75d84b

Add a HOWTO to help writing tests, includes domains with networking.

Signed-off-by: Daniel Stekloff <dsteklof@us.ibm.com>
author stekloff@dyn9047022152.beaverton.ibm.com
date Thu May 04 14:22:38 2006 +0100 (2006-05-04)
parents 51908f382f92
children d36ac8bf715e
files tools/xm-test/Writing_Tests_HOWTO
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/tools/xm-test/Writing_Tests_HOWTO	Thu May 04 14:22:38 2006 +0100
     1.3 @@ -0,0 +1,134 @@
     1.4 +
     1.5 +Writing Tests HOWTO
     1.6 +===================
     1.7 +
     1.8 +One goal for xm-test is to make test writing very easy. Xm-test includes
     1.9 +a library in lib/XmTestLib that contains all the necessary methods for
    1.10 +creating and shutting down domains. Include the library in your test by
    1.11 +importing it:
    1.12 +
    1.13 +  from XmTestLib import *
    1.14 +
    1.15 +
    1.16 +Guidelines
    1.17 +==========
    1.18 +
    1.19 +1. Tests should be short and single purposed. This means testing as
    1.20 +   little as possible in a single test. Do not overload tests. The more
    1.21 +   that's in a test the more difficult it is to track down what failed.
    1.22 +
    1.23 +2. Tests should report as much information as possible when calling
    1.24 +   FAIL() or SKIP().
    1.25 +
    1.26 +3. A test should report SKIP() only if it cannot be run on the current
    1.27 +   machine or it makes no sense to run it. SMP tests on an UP system, 
    1.28 +   for example, may not make sense. Or, there are some tests for
    1.29 +   para-virtualized guests that won't work on a fully virtualized 
    1.30 +   guest.
    1.31 +
    1.32 +4. Use the traceCommand() function to run commands on Domain0, the 
    1.33 +   Xen management domain. This function logs everything, which is useful
    1.34 +   in case of failure.
    1.35 +
    1.36 +5. Use the domain's console.runCmd method to run commands on a guest
    1.37 +   domain. This ensures logging and consistency. Please see 'Creating
    1.38 +   and Using Domains' below for an example.
    1.39 +
    1.40 +6. Tests need to capture and handle libary exceptions such as:
    1.41 +
    1.42 + - ConsoleError can be raised when sending a command to a console.
    1.43 + - DomainError can be raised when a domain is started, indicating
    1.44 +   a possible configuration error.
    1.45 + - TimeoutError can be raised when the traceCommand() method is used.
    1.46 +
    1.47 +7. Tests shouldn't depend on where the test is being run from or the
    1.48 +   system on which it is run.
    1.49 +
    1.50 +8. Please use the existing tests for a guide, especially:
    1.51 +
    1.52 + - create/01_create_basic_pos.py
    1.53 + - create/13_create_multinic_pos.py
    1.54 + - memset/01_memset_basic_pos.py
    1.55 + - reboot/01_reboot_basic_pos.py
    1.56 + - migrate/01_migrate_localhost_pos.py
    1.57 +
    1.58 +
    1.59 +Creating and Using Domains
    1.60 +==========================
    1.61 +
    1.62 +Xen domains, both full and para virtualized, are represented by the 
    1.63 +XmTestDomain class. The class contains methods for starting a Xen domain,
    1.64 +shutting it down, or destroying it. Consoles, used to execute commands
    1.65 +on guest test domains, are opened and closed through the XmTestDomain
    1.66 +class. Devices, which are represented by the XenDevice class, are also
    1.67 +added and removed using XmTestDomain methods. 
    1.68 +
    1.69 +Here's a simple example for creating a domain, opening a console, running
    1.70 +a command, and then shutting down the domain:
    1.71 +
    1.72 +1) Create a domain:
    1.73 +
    1.74 +    domain = XmTestDomain()
    1.75 +
    1.76 +2) Start the domain and grab a console:
    1.77 +
    1.78 +    try:
    1.79 +        console = domain.start()
    1.80 +    except DomainError, e:
    1.81 +        if verbose:
    1.82 +            print "Failed to create test domain because:"
    1.83 +            print e.extra
    1.84 +        FAIL(str(e))
    1.85 +
    1.86 +3) Run a command inside the new domain using the console, saving the
    1.87 +   console log if an error is encountered:
    1.88 +
    1.89 +    try:
    1.90 +        # Run 'ls'
    1.91 +        run = console.runCmd("ls")
    1.92 +    except ConsoleError, e:
    1.93 +        saveLog(console.getHistory())
    1.94 +        FAIL(str(e))
    1.95 +
    1.96 +4) Stop the domain, which nicely shuts it down:
    1.97 +
    1.98 +    domain.stop()
    1.99 +
   1.100 +
   1.101 +Writing Tests with Networking
   1.102 +=============================
   1.103 +
   1.104 +The xm-test suite includes the ability to test networking for domains. 
   1.105 +Networking is configured at configuration time. While testing NAT and
   1.106 +routing environments in the future, the current xm-test only supports
   1.107 +a bridging environment. Xm-test currently only supports a range of
   1.108 +IPs, the dhcp feature will be added soon.
   1.109 +
   1.110 +The network tests will need to know what IPs to use. IPs are configured
   1.111 +when you build xm-test. Xm-test uses the zeroconf address range by
   1.112 +default, 169.254.0.1-169.254.255.255. If you'd like to set a new range,
   1.113 +do so at configure time, a netmask and network address must also be defined:
   1.114 +
   1.115 +    # ./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
   1.116 +
   1.117 +The tests will not need to set network information, this is done by 
   1.118 +the library once it's configured.
   1.119 +
   1.120 +As mentioned above, xm-test's goal is to make writing tests easy. Creating
   1.121 +domains with networking should also be easy. To create a domain with
   1.122 +a single network interface, tests can use a XmTestNetDomain object. It
   1.123 +creates a XenNetDevice for the domain automatically using the pre-configured
   1.124 +IP information. Otherwise, a network interface can be added to a domain
   1.125 +prior to starting it (the ability to attach devices will be added):
   1.126 +
   1.127 +    domain = XmTestDomain()
   1.128 +    domain.newDevice(XenNetDevice, "eth0")
   1.129 +    domain.newDevice(XenNetDevice, "eth1")
   1.130 +
   1.131 +Here, the domain is created and then the XenDomain factory newDevice
   1.132 +is called to create a new device of class XenNetDevice to the domain. 
   1.133 +The xm-test library will automatically assign an IP from the configured
   1.134 +list, execute ifconfig on the guest domain console, and create an
   1.135 +alias on Domain0. 
   1.136 +
   1.137 +