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"><<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> 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="idp56320"></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="idp63008"></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> 142