232 lines
8.7 KiB
XML
232 lines
8.7 KiB
XML
<?xml version="1.0" standalone="no"?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
|
|
[
|
|
]>
|
|
|
|
<article id="index">
|
|
<articleinfo>
|
|
<title>D-Bus Test Plan</title>
|
|
<date>14 February 2003</date>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Anders</firstname>
|
|
<surname>Carlsson</surname>
|
|
<affiliation>
|
|
<orgname>CodeFactory AB</orgname>
|
|
<address><email>andersca@codefactory.se</email></address>
|
|
</affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
</articleinfo>
|
|
<sect1 id="introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This document tries to explain the details of the test plan for D-Bus
|
|
</para>
|
|
<sect2 id="importance-of-testing">
|
|
<title>The importance of testing</title>
|
|
<para>
|
|
As with any big library or program, testing is important. It
|
|
can help find bugs and regressions and make the code better
|
|
overall.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
D-Bus can be built with support for testing by passing
|
|
<literal>--enable-tests</literal>. to the configure script. It
|
|
is recommended that production systems build without testing
|
|
since that reduces the D-Bus client library size.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="client-library">
|
|
<title>Testing the D-Bus client library</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<sect2 id="data-structures">
|
|
<title>Data Structures</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="message-loader">
|
|
<title>Message loader</title>
|
|
<para>
|
|
The message loader is the part of D-Bus that takes messages in
|
|
raw character form and parses them, turning them into DBusMessages.
|
|
</para>
|
|
<para>
|
|
This is one of the parts of D-Bus that
|
|
<emphasis>must</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<figure>
|
|
<title>Example of a message in string form</title>
|
|
<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
|
|
</programlisting>
|
|
</figure>
|
|
<para>
|
|
The file format of messages in string form is documented in
|
|
the D-Bus Reference Manual.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
There is also a test program called
|
|
<literal>break-loader</literal> 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.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="authentication">
|
|
<title>Authentication</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<figure>
|
|
<title>Example of an authentication script</title>
|
|
<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
|
|
</programlisting>
|
|
</figure>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="daemon">
|
|
<title>Testing the D-Bus bus daemon</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<sect2 id="debug-transport">
|
|
<title>The debug transport</title>
|
|
<para>
|
|
In D-Bus, a <emphasis>transport</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="bus-test">
|
|
<title>The bus-test program</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The bus-test program should test all major features of the
|
|
bus, such as service registration, notification when things
|
|
occurs and message matching.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="other-tests">
|
|
<title>Other tests</title>
|
|
|
|
<sect2 id="oom-robustness">
|
|
<title>Out-Of-Memory robustness</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
In practice, this means that both the client and server code
|
|
must be able to handle dbus_malloc returning NULL.
|
|
</para>
|
|
<para>
|
|
To test this, two environment variables
|
|
exist. <literal>DBUS_MALLOC_FAIL_NTH</literal> will make every
|
|
nth call to dbus_malloc return NULL, and
|
|
<literal>DBUS_MALLOC_FAIL_GREATER_THAN</literal> will make any
|
|
dbus_malloc call with a request for more than the specified
|
|
number of bytes fail.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="leaks-and-other-stuff">
|
|
<title>Memory leaks and code robustness</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Luckily there exists good tools for catching such errors. One
|
|
free good tool is <ulink url="http://devel-home.kde.org/~sewardj/">Valgrind</ulink>, which runs the program in a
|
|
virtual CPU which makes catching errors easy. All test programs can be run under Valgrind,
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</article>
|