fix userguide formatting

[i3/i3.github.io] / _docs / testsuite

diff --git a/_docs/testsuite b/_docs/testsuite
index 720ff39475bd5da87eb1786c739e0e25ab8ef687..6c3a36d9c78e9f253a8b0371eee4be55f0f29c31 100644 (file)
--- a/_docs/testsuite
+++ b/_docs/testsuite
@@ -1,7 +1,7 @@
 i3 testsuite
 ============
-Michael Stapelberg <michael+i3@stapelberg.de>
-September 2011
+Michael Stapelberg <michael@i3wm.org>
+September 2012
 
 This document explains how the i3 testsuite works, how to use it and extend it.
 It is targeted at developers who not necessarily have been doing testing before
@@ -33,6 +33,19 @@ able to easily test if the feature is working correctly. Many developers will
 test manually if everything works. Having a testcase not only helps you with
 that, but it will also be useful for every future change.
 
+== Relevant documentation
+
+Apart from this document, you should also have a look at:
+
+1. The "Modern Perl" book, which can be found at
+   http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf
+2. The latest Perl documentation of the "i3test" (general testcase setup) and
+   "i3test::Test" (additional test instructions) modules:
+   http://build.i3wm.org/docs/lib-i3test.html respectively
+   http://build.i3wm.org/docs/lib-i3test-test.html
+3. The latest documentation on i3’s IPC interface:
+   http://build.i3wm.org/docs/ipc.html
+
 == Implementation
 
 For several reasons, the i3 testsuite has been implemented in Perl:
@@ -45,9 +58,40 @@ For several reasons, the i3 testsuite has been implemented in Perl:
 
 2. Perl is widely available and has a well-working package infrastructure.
 3. The author is familiar with Perl :).
+4. It is a good idea to use a different language for the tests than the
+   implementation itself.
 
 Please do not start programming language flamewars at this point.
 
+=== Installing the dependencies
+
+As usual with Perl programs, the testsuite ships with a +Makefile.PL+.
+This file specifies which Perl modules the testsuite depends on and can be used
+to install all of them.
+
+Perl modules are distributed via CPAN, and there is the official, standard CPAN
+client, simply called +cpan+. It comes with every Perl installation and can be
+used to install the testsuite. Many users prefer to use the more modern
++cpanminus+ instead, though (because it asks no questions and just works):
+
+.Installing testsuite dependencies using cpanminus (preferred)
+--------------------------------------------------------------------------------
+$ cd ~/i3/testcases
+$ sudo apt-get install cpanminus
+$ sudo cpanm .
+--------------------------------------------------------------------------------
+
+If you don’t want to use cpanminus for some reason, the same works with cpan:
+
+.Installing testsuite dependencies using cpan
+--------------------------------------------------------------------------------
+$ cd ~/i3/testcases
+$ sudo cpan .
+--------------------------------------------------------------------------------
+
+In case you don’t have root permissions, you can also install into your home
+directory, see http://michael.stapelberg.de/cpan/
+
 === Mechanisms
 
 ==== Script: complete-run
@@ -99,6 +143,16 @@ Result: PASS
 $ less latest/i3-log-for-04-floating.t
 ----------------------------------------
 
+If your attempt to run the tests with a bare call to ./complete-run.pl fails, try this:
+
+---------------------------------------------------
+$ ./complete-run.pl --parallel=1 --keep-xdummy-output
+---------------------------------------------------
+
+One common cause of failures is not having the X dummy server module
+installed.  Under Debian and Ubuntu this is the package
++xserver-xorg-video-dummy+.
+
 ==== IPC interface
 
 The testsuite makes extensive use of the IPC (Inter-Process Communication)