summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog10
-rw-r--r--doc/.cvsignore3
-rw-r--r--doc/Makefile.am12
-rw-r--r--doc/dbus-test-plan.sgml228
-rw-r--r--test/Makefile.am2
5 files changed, 252 insertions, 3 deletions
diff --git a/ChangeLog b/ChangeLog
index a28ef5ed..d0d5814a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
2003-02-17 Anders Carlsson <andersca@codefactory.se>
+ * doc/.cvsignore:
+ * doc/Makefile.am:
+ * doc/dbus-test-plan.sgml:
+ Add test plan document.
+
+ * test/Makefile.am:
+ Fix distcheck.
+
+2003-02-17 Anders Carlsson <andersca@codefactory.se>
+
* dbus/dbus-message.c: (decode_header_data),
(_dbus_message_loader_return_buffer):
Set the header padding amount when loading a message.
diff --git a/doc/.cvsignore b/doc/.cvsignore
index 99ff7e75..eded08f0 100644
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -6,4 +6,5 @@ Makefile.in
*.la
*.o
api
-dbus-specification.html \ No newline at end of file
+dbus-specification.html
+dbus-test-plan.html
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0802f617..ff9249f6 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,11 +1,13 @@
EXTRA_DIST= \
dbus-specification.html \
dbus-specification.sgml \
+ dbus-test-plan.html \
+ dbus-test-plan.sgml \
dcop-howto.txt \
file-boilerplate.c
if MAINTAINER_MODE
-all-local: dbus-specification.html
+all-local: dbus-specification.html dbus-test-plan.html
endif
dbus-specification.html: dbus-specification.sgml
@@ -13,7 +15,15 @@ dbus-specification.html: dbus-specification.sgml
rm -r dbus-specification/stylesheet-images && \
rmdir dbus-specification
+dbus-test-plan.html: dbus-test-plan.sgml
+ db2html -o . --nochunks dbus-test-plan.sgml && \
+ rm -r dbus-test-plan/stylesheet-images && \
+ rmdir dbus-test-plan
+
maintainer-clean-local:
+ rm -f dbus-test-plan.html
+ rm -rf dbus-test-plan/stylesheet-images
+ test -d dbus-test-plan && rmdir dbus-test-plan
rm -f dbus-specification.html
rm -rf dbus-specification/stylesheet-images
test -d dbus-specification && rmdir dbus-specification
diff --git a/doc/dbus-test-plan.sgml b/doc/dbus-test-plan.sgml
new file mode 100644
index 00000000..557080b5
--- /dev/null
+++ b/doc/dbus-test-plan.sgml
@@ -0,0 +1,228 @@
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+]>
+<article id="indesx">
+ <artheader>
+ <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>
+ </artheader>
+ <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_BASE64'
+ 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>
diff --git a/test/Makefile.am b/test/Makefile.am
index aeb623fb..427a6e3e 100644
--- a/test/Makefile.am
+++ b/test/Makefile.am
@@ -45,7 +45,7 @@ break_loader_LDADD= $(TEST_LIBS)
bus_test_LDADD=$(TEST_LIBS) $(top_builddir)/bus/libdbus-daemon.la
spawn_test_LDADD=$(TEST_LIBS)
-dist-hook: \
+dist-hook:
DIRS="data data/valid-messages data/invalid-messages data/incomplete-messages data/auth" ; \
for D in $$DIRS; do \
test -d $(distdir)/$$D || mkdir $(distdir)/$$D ; \