doc/dbus-test-plan.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D-Bus Test Plan</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="D-Bus Test Plan"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>D-Bus Test Plan</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Anders</span> <span class="surname">Carlsson</span></h3><div class="affiliation"><span class="orgname">CodeFactory AB<br></span><div class="address"><p><code class="email">&lt;<a class="email" href="mailto:andersca@codefactory.se">andersca@codefactory.se</a>&gt;</code></p></div></div></div></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#importance-of-testing">The importance of testing</a></span></dt></dl></dd><dt><span class="sect1"><a href="#client-library">Testing the D-Bus client library</a></span></dt><dd><dl><dt><span class="sect2"><a href="#data-structures">Data Structures</a></span></dt><dt><span class="sect2"><a href="#message-loader">Message loader</a></span></dt><dt><span class="sect2"><a href="#authentication">Authentication</a></span></dt></dl></dd><dt><span class="sect1"><a href="#daemon">Testing the D-Bus bus daemon</a></span></dt><dd><dl><dt><span class="sect2"><a href="#debug-transport">The debug transport</a></span></dt><dt><span class="sect2"><a href="#bus-test">The bus-test program</a></span></dt></dl></dd><dt><span class="sect1"><a href="#other-tests">Other tests</a></span></dt><dd><dl><dt><span class="sect2"><a href="#oom-robustness">Out-Of-Memory robustness</a></span></dt><dt><span class="sect2"><a href="#leaks-and-other-stuff">Memory leaks and code robustness</a></span></dt></dl></dd></dl></div><div class="sect1" title="Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p>
   2       This document tries to explain the details of the test plan for D-Bus
   3     </p><div class="sect2" title="The importance of testing"><div class="titlepage"><div><div><h3 class="title"><a name="importance-of-testing"></a>The importance of testing</h3></div></div></div><p>
   4         As with any big library or program, testing is important. It
   5         can help find bugs and regressions and make the code better
   6         overall.
   7       </p><p>
   8         D-Bus is a large and complex piece of software (about 25,000
   9         lines of code for the client library, and 2,500 lines of code
  10         for the bus daemon) and it's therefore important to try to make sure
  11         that all parts of the software is functioning correctly.
  12       </p><p>
  13         D-Bus can be built with support for testing by passing
  14         <code class="literal">--enable-tests</code>. to the configure script. It
  15         is recommended that production systems build without testing
  16         since that reduces the D-Bus client library size.
  17       </p></div></div><div class="sect1" title="Testing the D-Bus client library"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="client-library"></a>Testing the D-Bus client library</h2></div></div></div><p>
  18       The tests for the client library consist of the dbus-test
  19       program which is a unit test for all aspects of the client
  20       library. Whenever a bug in the client library is found and
  21       fixed, a test is added to make sure that the bug won't occur again.
  22     </p><div class="sect2" title="Data Structures"><div class="titlepage"><div><div><h3 class="title"><a name="data-structures"></a>Data Structures</h3></div></div></div><p>
  23       The D-Bus client library consists of some data structures that
  24       are used internally; a linked list class, a hashtable class and
  25       a string class. All aspects of those are tested by dbus-test.
  26       </p></div><div class="sect2" title="Message loader"><div class="titlepage"><div><div><h3 class="title"><a name="message-loader"></a>Message loader</h3></div></div></div><p>
  27         The message loader is the part of D-Bus that takes messages in
  28         raw character form and parses them, turning them into DBusMessages.
  29       </p><p>
  30         This is one of the parts of D-Bus that
  31         <span class="emphasis"><em>must</em></span> be absolutely bug-free and
  32         robust. The message loader should be able to handle invalid
  33         and incomplete messages without crashing. Not doing so is a
  34         serious issue and can easily result in D-Bus being exploitable
  35         to DoS attacks.
  36       </p><p>
  37         To solve these problems, there is a testing feature called the
  38         Message Builder. The message builder can take a serialized
  39         message in string-form and convert it into a raw character
  40         string which can then be loaded by the message loader.
  41       </p><div class="figure"><a name="idp3744976"></a><p class="title"><b>Figure 1. Example of a message in string form</b></p><div class="figure-contents"><pre class="programlisting">
  42           # Standard org.freedesktop.DBus.Hello message
  43
  44           VALID_HEADER
  45           FIELD_NAME name
  46           TYPE STRING
  47           STRING 'org.freedesktop.DBus.Hello'
  48           FIELD_NAME srvc
  49           TYPE STRING
  50           STRING 'org.freedesktop.DBus'
  51           ALIGN 8
  52           END_LENGTH Header
  53           START_LENGTH Body
  54           END_LENGTH Body
  55         </pre></div></div><br class="figure-break"><p>
  56         The file format of messages in string form is documented in
  57         the D-Bus Reference Manual.
  58       </p><p>
  59         The message test part of dbus-test is using the message
  60         builder to build different kinds of messages, both valid,
  61         invalid, and invalid ones, to make sure that the loader won't
  62         crash or leak memory of any of those, and that the loader
  63         knows if a message is valid or not.
  64       </p><p>
  65         There is also a test program called
  66         <code class="literal">break-loader</code> that loads a message in
  67         string-form into raw character form using the message
  68         builder. It then randomly changes the message, it can for
  69         example replace single bytes of data or modify the length of
  70         the message. This is to simulate network errors. The
  71         break-loader program saves all the messages leading to errors
  72         so it can easily be run for a long period of time.
  73       </p></div><div class="sect2" title="Authentication"><div class="titlepage"><div><div><h3 class="title"><a name="authentication"></a>Authentication</h3></div></div></div><p>
  74         For testing authentication, there is a testing feature that
  75         can read authentication sequences from a file and play them
  76         back to a dummy server and client to make sure that
  77         authentication is working according to the specification.
  78       </p><div class="figure"><a name="idp3751664"></a><p class="title"><b>Figure 2. Example of an authentication script</b></p><div class="figure-contents"><pre class="programlisting">
  79           ## this tests a successful auth of type EXTERNAL
  80
  81           SERVER
  82           SEND 'AUTH EXTERNAL USERNAME_HEX'
  83           EXPECT_COMMAND OK
  84           EXPECT_STATE WAITING_FOR_INPUT
  85           SEND 'BEGIN'
  86           EXPECT_STATE AUTHENTICATED
  87         </pre></div></div><br class="figure-break"></div></div><div class="sect1" title="Testing the D-Bus bus daemon"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="daemon"></a>Testing the D-Bus bus daemon</h2></div></div></div><p>
  88       Since the D-Bus bus daemon is using the D-Bus client library it
  89       will benefit from all tests done on the client library, but
  90       there is still the issue of testing client-server communication.
  91       This is more complicated since it it may require another process
  92       running.
  93     </p><div class="sect2" title="The debug transport"><div class="titlepage"><div><div><h3 class="title"><a name="debug-transport"></a>The debug transport</h3></div></div></div><p>
  94         In D-Bus, a <span class="emphasis"><em>transport</em></span> is a class that
  95         handles sending and receiving raw data over a certain
  96         medium. The transport that is used most in D-Bus is the UNIX
  97         transport with sends and recevies data over a UNIX socket. A
  98         transport that tunnels data through X11 client messages is
  99         also under development.
 100       </p><p>
 101         The D-Bus debug transport is a specialized transport that
 102         works in-process. This means that a client and server that
 103         exists in the same process can talk to eachother without using
 104         a socket.
 105       </p></div><div class="sect2" title="The bus-test program"><div class="titlepage"><div><div><h3 class="title"><a name="bus-test"></a>The bus-test program</h3></div></div></div><p>
 106         The bus-test program is a program that is used to test various
 107         parts of the D-Bus bus daemon; robustness and that it conforms
 108         to the specifications.
 109       </p><p>
 110         The test program has the necessary code from the bus daemon
 111         linked in, and it uses the debug transport for
 112         communication. This means that the bus daemon code can be
 113         tested without the real bus actually running, which makes
 114         testing easier.
 115       </p><p>
 116         The bus-test program should test all major features of the
 117         bus, such as service registration, notification when things
 118         occurs and message matching.
 119       </p></div></div><div class="sect1" title="Other tests"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="other-tests"></a>Other tests</h2></div></div></div><div class="sect2" title="Out-Of-Memory robustness"><div class="titlepage"><div><div><h3 class="title"><a name="oom-robustness"></a>Out-Of-Memory robustness</h3></div></div></div><p>
 120         Since D-Bus should be able to be used in embedded devices, and
 121         also as a system service, it should be able to cope with
 122         low-memory situations without exiting or crashing.
 123       </p><p>
 124         In practice, this means that both the client and server code
 125         must be able to handle dbus_malloc returning NULL.
 126       </p><p>
 127         To test this, two environment variables
 128         exist. <code class="literal">DBUS_MALLOC_FAIL_NTH</code> will make every
 129         nth call to dbus_malloc return NULL, and
 130         <code class="literal">DBUS_MALLOC_FAIL_GREATER_THAN</code> will make any
 131         dbus_malloc call with a request for more than the specified
 132         number of bytes fail.
 133       </p></div><div class="sect2" title="Memory leaks and code robustness"><div class="titlepage"><div><div><h3 class="title"><a name="leaks-and-other-stuff"></a>Memory leaks and code robustness</h3></div></div></div><p>
 134         Naturally there are some things that tests can't be written
 135         for, for example things like memory leaks and out-of-bounds
 136         memory reading or writing.
 137       </p><p>
 138         Luckily there exists good tools for catching such errors. One
 139         free good tool is <a class="ulink" href="http://devel-home.kde.org/~sewardj/" target="_top">Valgrind</a>, which runs the program in a
 140         virtual CPU which makes catching errors easy. All test programs can be run under Valgrind,
 141       </p></div></div></div></body></html>