From: Anders Carlsson Date: Sun, 16 Feb 2003 23:35:51 +0000 (+0000) Subject: 2003-02-17 Anders Carlsson X-Git-Tag: dbus-0.4~4 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=014e1be4826b5ea7b1558f23089cd90dcf2cb998;p=platform%2Fupstream%2Fdbus.git 2003-02-17 Anders Carlsson * doc/.cvsignore: * doc/Makefile.am: * doc/dbus-test-plan.sgml: Add test plan document. * test/Makefile.am: Fix distcheck. --- diff --git a/ChangeLog b/ChangeLog index a28ef5e..d0d5814 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,15 @@ 2003-02-17 Anders Carlsson + * doc/.cvsignore: + * doc/Makefile.am: + * doc/dbus-test-plan.sgml: + Add test plan document. + + * test/Makefile.am: + Fix distcheck. + +2003-02-17 Anders Carlsson + * 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 99ff7e7..eded08f 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 0802f61..ff9249f 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 0000000..557080b --- /dev/null +++ b/doc/dbus-test-plan.sgml @@ -0,0 +1,228 @@ + +
+ + D-BUS Test Plan + 14 February 2003 + + + Anders + Carlsson + + CodeFactory AB +
andersca@codefactory.se
+ + + + + + Introduction + + This document tries to explain the details of the test plan for D-BUS + + + The importance of testing + + As with any big library or program, testing is important. It + can help find bugs and regressions and make the code better + overall. + + + 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. + + + D-BUS can be built with support for testing by passing + --enable-tests. to the configure script. It + is recommended that production systems build without testing + since that reduces the D-BUS client library size. + + + + + Testing the D-BUS client library + + 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. + + + Data Structures + + 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. + + + + Message loader + + The message loader is the part of D-BUS that takes messages in + raw character form and parses them, turning them into DBusMessages. + + + This is one of the parts of D-BUS that + must 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. + + + 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. + +
+ Example of a message in string form + + # 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 + +
+ + The file format of messages in string form is documented in + the D-BUS Reference Manual. + + + 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. + + + There is also a test program called + break-loader 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. + + + + Authentication + + 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. + +
+ Example of an authentication script + + ## 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 + +
+ + + + Testing the D-BUS bus daemon + + 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. + + + The debug transport + + In D-BUS, a transport 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. + + + 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. + + + + The bus-test program + + 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. + + + 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. + + + The bus-test program should test all major features of the + bus, such as service registration, notification when things + occurs and message matching. + + + + + Other tests + + + Out-Of-Memory robustness + + 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. + + + In practice, this means that both the client and server code + must be able to handle dbus_malloc returning NULL. + + + To test this, two environment variables + exist. DBUS_MALLOC_FAIL_NTH will make every + nth call to dbus_malloc return NULL, and + DBUS_MALLOC_FAIL_GREATER_THAN will make any + dbus_malloc call with a request for more than the specified + number of bytes fail. + + + + + Memory leaks and code robustness + + 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. + + + Luckily there exists good tools for catching such errors. One + free good tool is Valgrind, which runs the program in a + virtual CPU which makes catching errors easy. All test programs can be run under Valgrind, + + + +
diff --git a/test/Makefile.am b/test/Makefile.am index aeb623f..427a6e3 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 ; \