doc/dbus-test-plan.sgml

   1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   2 ]>
   3 <article id="index">
   4   <artheader>
   5     <title>D-BUS Test Plan</title>
   6     <date>14 February 2003</date>
   7     <authorgroup>
   8       <author>
   9         <firstname>Anders</firstname>
  10         <surname>Carlsson</surname>
  11         <affiliation>
  12           <orgname>CodeFactory AB</orgname>
  13           <address><email>andersca@codefactory.se</email></address>
  14         </affiliation>
  15       </author>
  16     </authorgroup>
  17   </artheader>
  18   <sect1 id="introduction">
  19     <title>Introduction</title>
  20     <para>
  21       This document tries to explain the details of the test plan for D-BUS
  22     </para>
  23     <sect2 id="importance-of-testing">
  24       <title>The importance of testing</title>
  25       <para>
  26         As with any big library or program, testing is important. It
  27         can help find bugs and regressions and make the code better
  28         overall.
  29       </para>
  30       <para>
  31         D-BUS is a large and complex piece of software (about 25,000
  32         lines of code for the client library, and 2,500 lines of code
  33         for the bus daemon) and it's therefore important to try to make sure
  34         that all parts of the software is functioning correctly.
  35       </para>
  36       <para>
  37         D-BUS can be built with support for testing by passing
  38         <literal>--enable-tests</literal>. to the configure script. It
  39         is recommended that production systems build without testing
  40         since that reduces the D-BUS client library size.
  41       </para>
  42     </sect2>
  43   </sect1>
  44   <sect1 id="client-library">
  45     <title>Testing the D-BUS client library</title>
  46     <para>
  47       The tests for the client library consist of the dbus-test
  48       program which is a unit test for all aspects of the client
  49       library. Whenever a bug in the client library is found and
  50       fixed, a test is added to make sure that the bug won't occur again.
  51     </para>
  52     <sect2 id="data-structures">
  53       <title>Data Structures</title>
  54       <para>
  55       The D-BUS client library consists of some data structures that
  56       are used internally; a linked list class, a hashtable class and
  57       a string class. All aspects of those are tested by dbus-test.
  58       </para>
  59     </sect2>
  60     <sect2 id="message-loader">
  61       <title>Message loader</title>
  62       <para>
  63         The message loader is the part of D-BUS that takes messages in
  64         raw character form and parses them, turning them into DBusMessages.
  65       </para>
  66       <para>
  67         This is one of the parts of D-BUS that
  68         <emphasis>must</emphasis> be absolutely bug-free and
  69         robust. The message loader should be able to handle invalid
  70         and incomplete messages without crashing. Not doing so is a
  71         serious issue and can easily result in D-BUS being exploitable
  72         to DoS attacks.
  73       </para>
  74       <para>
  75         To solve these problems, there is a testing feature called the
  76         Message Builder. The message builder can take a serialized
  77         message in string-form and convert it into a raw character
  78         string which can then be loaded by the message loader.
  79       </para>
  80       <figure>
  81         <title>Example of a message in string form</title>
  82         <programlisting>
  83           # Standard org.freedesktop.DBus.Hello message
  84
  85           VALID_HEADER
  86           FIELD_NAME name
  87           TYPE STRING
  88           STRING 'org.freedesktop.DBus.Hello'
  89           FIELD_NAME srvc
  90           TYPE STRING
  91           STRING 'org.freedesktop.DBus'
  92           ALIGN 8
  93           END_LENGTH Header
  94           START_LENGTH Body
  95           END_LENGTH Body
  96         </programlisting>
  97       </figure>
  98       <para>
  99         The file format of messages in string form is documented in
 100         the D-BUS Reference Manual.
 101       </para>
 102       <para>
 103         The message test part of dbus-test is using the message
 104         builder to build different kinds of messages, both valid,
 105         invalid, and invalid ones, to make sure that the loader won't
 106         crash or leak memory of any of those, and that the loader
 107         knows if a message is valid or not.
 108       </para>
 109       <para>
 110         There is also a test program called
 111         <literal>break-loader</literal> that loads a message in
 112         string-form into raw character form using the message
 113         builder. It then randomly changes the message, it can for
 114         example replace single bytes of data or modify the length of
 115         the message. This is to simulate network errors. The
 116         break-loader program saves all the messages leading to errors
 117         so it can easily be run for a long period of time.
 118       </para>
 119     </sect2>
 120     <sect2 id="authentication">
 121       <title>Authentication</title>
 122       <para>
 123         For testing authentication, there is a testing feature that
 124         can read authentication sequences from a file and play them
 125         back to a dummy server and client to make sure that
 126         authentication is working according to the specification.
 127       </para>
 128       <figure>
 129         <title>Example of an authentication script</title>
 130         <programlisting>
 131           ## this tests a successful auth of type EXTERNAL
 132
 133           SERVER
 134           SEND 'AUTH EXTERNAL USERNAME_BASE64'
 135           EXPECT_COMMAND OK
 136           EXPECT_STATE WAITING_FOR_INPUT
 137           SEND 'BEGIN'
 138           EXPECT_STATE AUTHENTICATED
 139         </programlisting>
 140       </figure>
 141     </sect2>
 142   </sect1>
 143   <sect1 id="daemon">
 144     <title>Testing the D-BUS bus daemon</title>
 145     <para>
 146       Since the D-BUS bus daemon is using the D-BUS client library it
 147       will benefit from all tests done on the client library, but
 148       there is still the issue of testing client-server communication.
 149       This is more complicated since it it may require another process
 150       running.
 151     </para>
 152     <sect2 id="debug-transport">
 153       <title>The debug transport</title>
 154       <para>
 155         In D-BUS, a <emphasis>transport</emphasis> is a class that
 156         handles sending and receiving raw data over a certain
 157         medium. The transport that is used most in D-BUS is the UNIX
 158         transport with sends and recevies data over a UNIX socket. A
 159         transport that tunnels data through X11 client messages is
 160         also under development.
 161       </para>
 162       <para>
 163         The D-BUS debug transport is a specialized transport that
 164         works in-process. This means that a client and server that
 165         exists in the same process can talk to eachother without using
 166         a socket.
 167       </para>
 168     </sect2>
 169     <sect2 id="bus-test">
 170       <title>The bus-test program</title>
 171       <para>
 172         The bus-test program is a program that is used to test various
 173         parts of the D-BUS bus daemon; robustness and that it conforms
 174         to the specifications.
 175       </para>
 176       <para>
 177         The test program has the necessary code from the bus daemon
 178         linked in, and it uses the debug transport for
 179         communication. This means that the bus daemon code can be
 180         tested without the real bus actually running, which makes
 181         testing easier.
 182       </para>
 183       <para>
 184         The bus-test program should test all major features of the
 185         bus, such as service registration, notification when things
 186         occurs and message matching.
 187       </para>
 188     </sect2>
 189   </sect1>
 190   <sect1 id="other-tests">
 191     <title>Other tests</title>
 192
 193     <sect2 id="oom-robustness">
 194       <title>Out-Of-Memory robustness</title>
 195       <para>
 196         Since D-BUS should be able to be used in embedded devices, and
 197         also as a system service, it should be able to cope with
 198         low-memory situations without exiting or crashing.
 199       </para>
 200       <para>
 201         In practice, this means that both the client and server code
 202         must be able to handle dbus_malloc returning NULL.
 203       </para>
 204       <para>
 205         To test this, two environment variables
 206         exist. <literal>DBUS_MALLOC_FAIL_NTH</literal> will make every
 207         nth call to dbus_malloc return NULL, and
 208         <literal>DBUS_MALLOC_FAIL_GREATER_THAN</literal> will make any
 209         dbus_malloc call with a request for more than the specified
 210         number of bytes fail.
 211       </para>
 212     </sect2>
 213
 214     <sect2 id="leaks-and-other-stuff">
 215       <title>Memory leaks and code robustness</title>
 216       <para>
 217         Naturally there are some things that tests can't be written
 218         for, for example things like memory leaks and out-of-bounds
 219         memory reading or writing.
 220       </para>
 221       <para>
 222         Luckily there exists good tools for catching such errors. One
 223         free good tool is <ulink url="http://devel-home.kde.org/~sewardj/">Valgrind</ulink>, which runs the program in a
 224         virtual CPU which makes catching errors easy. All test programs can be run under Valgrind,
 225       </para>
 226     </sect2>
 227   </sect1>
 228 </article>