diff options
| author | Simon McVittie <smcv@debian.org> | 2011-01-31 17:37:59 +0000 |
|---|---|---|
| committer | Simon McVittie <smcv@debian.org> | 2011-01-31 17:37:59 +0000 |
| commit | 24fbe571516161d48b499d587f9adb3e683dbf88 (patch) | |
| tree | 7d70909156dcf587d91f693b8e1216eb4e0465e1 /doc/dbus-test-plan.html | |
| parent | 9b72896b3730a9fceb961be28bb95762a7b4e9d6 (diff) | |
| download | dbus-24fbe571516161d48b499d587f9adb3e683dbf88.tar.gz | |
Imported Upstream version 1.2.24upstream/1.2.24
Diffstat (limited to 'doc/dbus-test-plan.html')
| -rw-r--r-- | doc/dbus-test-plan.html | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/doc/dbus-test-plan.html b/doc/dbus-test-plan.html new file mode 100644 index 00000000..e9e70a11 --- /dev/null +++ b/doc/dbus-test-plan.html @@ -0,0 +1,141 @@ +<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.75.2"></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"><<a class="email" href="mailto:andersca@codefactory.se">andersca@codefactory.se</a>></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> + This document tries to explain the details of the test plan for D-Bus + </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> + As with any big library or program, testing is important. It + can help find bugs and regressions and make the code better + overall. + </p><p> + D-Bus is a large and complex piece of software (about 25,000 + lines of code for the client library, and 2,500 lines of code + for the bus daemon) and it's therefore important to try to make sure + that all parts of the software is functioning correctly. + </p><p> + D-Bus can be built with support for testing by passing + <code class="literal">--enable-tests</code>. to the configure script. It + is recommended that production systems build without testing + since that reduces the D-Bus client library size. + </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> + The tests for the client library consist of the dbus-test + program which is a unit test for all aspects of the client + library. Whenever a bug in the client library is found and + fixed, a test is added to make sure that the bug won't occur again. + </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> + The D-Bus client library consists of some data structures that + are used internally; a linked list class, a hashtable class and + a string class. All aspects of those are tested by dbus-test. + </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> + The message loader is the part of D-Bus that takes messages in + raw character form and parses them, turning them into DBusMessages. + </p><p> + This is one of the parts of D-Bus that + <span class="emphasis"><em>must</em></span> be absolutely bug-free and + robust. The message loader should be able to handle invalid + and incomplete messages without crashing. Not doing so is a + serious issue and can easily result in D-Bus being exploitable + to DoS attacks. + </p><p> + To solve these problems, there is a testing feature called the + Message Builder. The message builder can take a serialized + message in string-form and convert it into a raw character + string which can then be loaded by the message loader. + </p><div class="figure"><a name="id528362"></a><p class="title"><b>Figure 1. Example of a message in string form</b></p><div class="figure-contents"><pre class="programlisting"> + # Standard org.freedesktop.DBus.Hello message + + VALID_HEADER + FIELD_NAME name + TYPE STRING + STRING 'org.freedesktop.DBus.Hello' + FIELD_NAME srvc + TYPE STRING + STRING 'org.freedesktop.DBus' + ALIGN 8 + END_LENGTH Header + START_LENGTH Body + END_LENGTH Body + </pre></div></div><br class="figure-break"><p> + The file format of messages in string form is documented in + the D-Bus Reference Manual. + </p><p> + The message test part of dbus-test is using the message + builder to build different kinds of messages, both valid, + invalid, and invalid ones, to make sure that the loader won't + crash or leak memory of any of those, and that the loader + knows if a message is valid or not. + </p><p> + There is also a test program called + <code class="literal">break-loader</code> that loads a message in + string-form into raw character form using the message + builder. It then randomly changes the message, it can for + example replace single bytes of data or modify the length of + the message. This is to simulate network errors. The + break-loader program saves all the messages leading to errors + so it can easily be run for a long period of time. + </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> + For testing authentication, there is a testing feature that + can read authentication sequences from a file and play them + back to a dummy server and client to make sure that + authentication is working according to the specification. + </p><div class="figure"><a name="id524894"></a><p class="title"><b>Figure 2. Example of an authentication script</b></p><div class="figure-contents"><pre class="programlisting"> + ## this tests a successful auth of type EXTERNAL + + SERVER + SEND 'AUTH EXTERNAL USERNAME_HEX' + EXPECT_COMMAND OK + EXPECT_STATE WAITING_FOR_INPUT + SEND 'BEGIN' + EXPECT_STATE AUTHENTICATED + </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> + Since the D-Bus bus daemon is using the D-Bus client library it + will benefit from all tests done on the client library, but + there is still the issue of testing client-server communication. + This is more complicated since it it may require another process + running. + </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> + In D-Bus, a <span class="emphasis"><em>transport</em></span> is a class that + handles sending and receiving raw data over a certain + medium. The transport that is used most in D-Bus is the UNIX + transport with sends and recevies data over a UNIX socket. A + transport that tunnels data through X11 client messages is + also under development. + </p><p> + The D-Bus debug transport is a specialized transport that + works in-process. This means that a client and server that + exists in the same process can talk to eachother without using + a socket. + </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> + The bus-test program is a program that is used to test various + parts of the D-Bus bus daemon; robustness and that it conforms + to the specifications. + </p><p> + The test program has the necessary code from the bus daemon + linked in, and it uses the debug transport for + communication. This means that the bus daemon code can be + tested without the real bus actually running, which makes + testing easier. + </p><p> + The bus-test program should test all major features of the + bus, such as service registration, notification when things + occurs and message matching. + </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> + Since D-Bus should be able to be used in embedded devices, and + also as a system service, it should be able to cope with + low-memory situations without exiting or crashing. + </p><p> + In practice, this means that both the client and server code + must be able to handle dbus_malloc returning NULL. + </p><p> + To test this, two environment variables + exist. <code class="literal">DBUS_MALLOC_FAIL_NTH</code> will make every + nth call to dbus_malloc return NULL, and + <code class="literal">DBUS_MALLOC_FAIL_GREATER_THAN</code> will make any + dbus_malloc call with a request for more than the specified + number of bytes fail. + </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> + Naturally there are some things that tests can't be written + for, for example things like memory leaks and out-of-bounds + memory reading or writing. + </p><p> + Luckily there exists good tools for catching such errors. One + free good tool is <a class="ulink" href="http://devel-home.kde.org/~sewardj/" target="_top">Valgrind</a>, which runs the program in a + virtual CPU which makes catching errors easy. All test programs can be run under Valgrind, + </p></div></div></div></body></html> |