]> git.sur5r.net Git - i3/i3/blob - docs/testsuite
Bugfix: Make generate-command-parser.pl compatible with perl 5.10
[i3/i3] / docs / testsuite
1 i3 testsuite
2 ============
3 Michael Stapelberg <michael+i3@stapelberg.de>
4 September 2011
5
6 This document explains how the i3 testsuite works, how to use it and extend it.
7 It is targeted at developers who not necessarily have been doing testing before
8 or have not been testing in Perl before. In general, the testsuite is not of
9 interest for end users.
10
11
12 == Introduction
13
14 The i3 testsuite is a collection of files which contain testcases for various
15 i3 features. Some of them test if a certain workflow works correctly (moving
16 windows, focus behaviour, …). Others are regression tests and contain code
17 which previously made i3 crash or lead to unexpected behaviour. They then check
18 if i3 still runs (meaning it did not crash) and if it handled everything
19 correctly.
20
21 The goal of having these tests is to automatically find problems and to
22 automatically get a feel for whether a change in the source code breaks any
23 existing feature. After every modification of the i3 sourcecode, the developer
24 should run the full testsuite. If one of the tests fails, the corresponding
25 problem should be fixed (or, in some cases, the testcase has to be modified).
26 For every bugreport, a testcase should be written to test the correct
27 behaviour. Initially, it will fail, but after fixing the bug, it will pass.
28 This ensures (or increases the chance) that bugs which have been fixed once
29 will never be found again.
30
31 Also, when implementing a new feature, a testcase might be a good way to be
32 able to easily test if the feature is working correctly. Many developers will
33 test manually if everything works. Having a testcase not only helps you with
34 that, but it will also be useful for every future change.
35
36 == Implementation
37
38 For several reasons, the i3 testsuite has been implemented in Perl:
39
40 1. Perl has a long tradition of testing. Every popular/bigger Perl module which
41    you can find on CPAN will not only come with documentation, but also with
42    tests. Therefore, the available infrastructure for tests is comprehensive.
43    See for example the excellent http://search.cpan.org/perldoc?Test::More
44    and the referenced http://search.cpan.org/perldoc?Test::Tutorial.
45
46 2. Perl is widely available and has a well-working package infrastructure.
47 3. The author is familiar with Perl :).
48
49 Please do not start programming language flamewars at this point.
50
51 === Mechanisms
52
53 ==== Script: complete-run
54
55 The testcases are run by a script called +complete-run.pl+. It runs all
56 testcases by default, but you can be more specific and let it only run one or
57 more testcases. Also, it takes care of starting up a separate instance of i3
58 with an appropriate configuration file and creates a folder for each run
59 containing the appropriate i3 logfile for each testcase. The latest folder can
60 always be found under the symlink +latest/+. Unless told differently, it will
61 run the tests on a separate X server instance (using the Xdummy script).
62
63 .Example invocation of complete-run.pl+
64 ---------------------------------------
65 $ cd ~/i3/testcases
66
67 $ ./complete-run.pl
68 # output omitted because it is very long
69 All tests successful.
70 Files=78, Tests=734, 27 wallclock secs ( 0.38 usr  0.48 sys + 17.65 cusr  3.21 csys = 21.72 CPU)
71 Result: PASS
72
73 $ ./complete-run.pl t/04-floating.t
74 [:3] i3 startup: took 0.07s, status = 1
75 [:3] Running t/04-floating.t with logfile testsuite-2011-09-24-16-06-04-4.0.2-226-g1eb011a/i3-log-for-04-floating.t
76 [:3] t/04-floating.t finished
77 [:3] killing i3
78 output for t/04-floating.t:
79 ok 1 - use X11::XCB::Window;
80 ok 2 - The object isa X11::XCB::Window
81 ok 3 - Window is mapped
82 ok 4 - i3 raised the width to 75
83 ok 5 - i3 raised the height to 50
84 ok 6 - i3 did not map it to (0x0)
85 ok 7 - The object isa X11::XCB::Window
86 ok 8 - i3 let the width at 80
87 ok 9 - i3 let the height at 90
88 ok 10 - i3 mapped it to x=1
89 ok 11 - i3 mapped it to y=18
90 ok 12 - The object isa X11::XCB::Window
91 ok 13 - i3 let the width at 80
92 ok 14 - i3 let the height at 90
93 1..14
94
95 All tests successful.
96 Files=1, Tests=14,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.19 cusr  0.03 csys =  0.23 CPU)
97 Result: PASS
98
99 $ less latest/i3-log-for-04-floating.t
100 ----------------------------------------
101
102 ==== IPC interface
103
104 The testsuite makes extensive use of the IPC (Inter-Process Communication)
105 interface which i3 provides. It is used for the startup process of i3, for
106 terminating it cleanly and (most importantly) for modifying and getting the
107 current state (layout tree).
108
109 See [http://i3wm.org/docs/ipc.html] for documentation on the IPC interface.
110
111 ==== X11::XCB
112
113 In order to open new windows, change attributes, get events, etc., the
114 testsuite uses X11::XCB, a new (and quite specific to i3 at the moment) Perl
115 module which uses the XCB protocol description to generate Perl bindings to
116 X11. They work in a very similar way to libxcb (which i3 uses) and provide
117 relatively high-level interfaces (objects such as +X11::XCB::Window+) aswell as
118 access to the low-level interface, which is very useful when testing a window
119 manager.
120
121 === Filesystem structure
122
123 In the git root of i3, the testcases live in the folder +testcases+. This
124 folder contains the +complete-run.pl+ and +Xdummy+ scripts and a base
125 configuration file which will be used for the tests. The different testcases
126 (their file extension is .t, not .pl) themselves can be found in the
127 conventionally named subfolder +t+:
128
129 .Filesystem structure
130 --------------------------------------------
131 ├── testcases
132 │   ├── complete-run.pl
133 │   ├── i3-test.config
134 │   ├── lib
135 │   │   ├── i3test.pm
136 │   │   ├── SocketActivation.pm
137 │   │   └── StartXDummy.pm
138 │   ├── t
139 │   │   ├── 00-load.t
140 │   │   ├── 01-tile.t
141 │   │   ├── 02-fullscreen.t
142 │   │   ├── ...
143 │   │   ├── omitted for brevity
144 │   │   ├── ...
145 │   │   └── 74-regress-focus-toggle.t
146 │   └── Xdummy
147 --------------------------------------------
148
149 == Anatomy of a testcase
150
151 Learning by example is definitely a good strategy when you are wondering how to
152 write a testcase. Let's take +t/11-goto.t+ as an easy example and go through it
153 step by step:
154
155 .t/11-goto.t: Boilerplate
156 ----------------------
157 #!perl
158 # vim:ts=4:sw=4:expandtab
159
160 use i3test;
161 use File::Temp;
162
163 my $x = X11::XCB::Connection->new;
164 -----------------------
165
166 This is what we call boilerplate. It exists at the top of every test file (to
167 some extent). The first line is the shebang, which specifies that this file is
168 a Perl script. The second line contains VIM specific settings on how to
169 edit/format this file (use spaces instead of tabs, indent using 4 spaces).
170 Afterwards, the +i3test+ module is used. This module contains i3 testsuite
171 specific functions which you are strongly encouraged to use. They make writing
172 testcases a lot easier and will make it easier for other people to read your
173 tests.
174
175 The next line uses the +File::Temp+ module. This is specific to this testcase,
176 because it needs to generate a temporary name during the test. Many testcases
177 use only the +i3test+ module.
178
179 The last line opens a connection to X11. You might or might not need this in
180 your testcase, depending on whether you are going to open windows (etc.) or
181 only use i3 commands.
182
183 .t/11-goto.t: Setup
184 ----------------------
185 my $tmp = fresh_workspace;
186
187 cmd 'split h';
188 ----------------------
189
190 The first line calls i3test's +fresh_workspace+ function which looks for a
191 currently unused workspace, switches to it, and returns its name. The variable
192 +$tmp+ will end up having a value such as +"/tmp/87kBVcHbA9"+. Note that this
193 is not (necessarily) a valid path, it's just a random workspace name.
194
195 So, now that we are on a new workspace, we ensure that the workspace uses
196 horizontal orientation by issuing the +split h+ command (see the i3 User's
197 Guide for a list of commands). This is not strictly necessary, but good style.
198 In general, the +cmd+ function executes the specified i3 command by using the
199 IPC interface and returns once i3 acknowledged the command.
200
201 .t/11-goto.t: Setup
202 ----------------------
203 #####################################################################
204 # Create two windows and make sure focus switching works
205 #####################################################################
206
207 my $top = open_window($x);
208 my $mid = open_window($x);
209 my $bottom = open_window($x);
210 ----------------------
211
212 In every major section of a testcase, you should put a comment like the one
213 above. This makes it immediately clear how the file is structured.
214
215 The +open_window+ function opens a standard window, which will then be put into
216 tiling mode by i3. If you want a floating window, use the
217 +open_floating_window+ function. These functions accept the same parameters as
218 +X11::XCB::Window->new+, see the i3test documentation at TODO.
219
220 .t/11-goto.t: Helper function
221 ----------------------
222 #
223 # Returns the input focus after sending the given command to i3 via IPC
224 # and syncing with i3
225 #
226 sub focus_after {
227     my $msg = shift;
228
229     cmd $msg;
230     sync_with_i3 $x;
231     return $x->input_focus;
232 }
233 ----------------------
234
235 This section defines a helper function which will be used over and over in this
236 testcase. If you have code which gets executed more than once or twice
237 (depending on the length of your test, use your best judgement), please put it
238 in a function. Tests should be short, concise and clear.
239
240 The +focus_after+ function executes a command and returns the X11 focus after
241 the command was executed. The +sync_with_i3+ command makes sure that i3 could
242 push its state to X11. See <<i3_sync>> to learn how this works exactly.
243
244 .t/11-goto.t: Test assumptions
245 ----------------------
246 $focus = $x->input_focus;
247 is($focus, $bottom->id, "Latest window focused");
248
249 $focus = focus_after('focus left');
250 is($focus, $mid->id, "Middle window focused");
251 ----------------------
252
253 Now, we run the first two real tests. They use +Test::More+'s +is+ function,
254 which compares two values and prints the differences if they are not the same.
255 After the arguments, we supply a short comment to indicate what we are testing
256 here. This makes it vastly more easy for the developer to spot which testcase
257 is the problem in case one fails.
258
259 The first test checks that the most recently opened window is focused.
260 Afterwards, the command +focus left+ is issued and it is verified that the
261 middle window now has focus.
262
263 Note that this is not a comprehensive test of the +focus+ command -- we would
264 have to test wrapping, focus when using a more complex layout, focusing the
265 parent/child containers, etc. But that is not the point of this testcase.
266 Instead, we just want to know if +$x->input_focus+ corresponds with what we are
267 expecting. If not, something is completely wrong with the test environment and
268 this trivial test will fail.
269
270 .t/11-goto.t: Test that the feature does not work (yet)
271 ----------------------
272 #####################################################################
273 # Now goto a mark which does not exist
274 #####################################################################
275
276 my $random_mark = mktemp('mark.XXXXXX');
277
278 $focus = focus_after(qq|[con_mark="$random_mark"] focus|);
279 is($focus, $mid->id, "focus unchanged");
280 ----------------------
281
282 Syntax hint: The qq keyword is the interpolating quote operator. It lets you
283 chose a quote character (in this case the +|+ character, a pipe). This makes
284 having double quotes in our string easy.
285
286 In this new major section, a random mark (mark is an identifier for a window,
287 see "VIM-like marks" in the i3 User’s Guide) will be generated. Afterwards, we
288 test that trying to focus that mark will not do anything. This is important: Do
289 not only test that using a feature has the expected outcome, but also test that
290 using it without properly initializing it does no harm. This command could for
291 example have changed focus anyways (a bug) or crash i3 (obviously a bug).
292
293 .t/11-goto.t: Test that the feature does work
294 ----------------------
295 cmd "mark $random_mark";
296
297 $focus = focus_after('focus left');
298 is($focus, $top->id, "Top window focused");
299
300 $focus = focus_after(qq|[con_mark="$random_mark"] focus|);
301 is($focus, $mid->id, "goto worked");
302 ----------------------
303
304 Remember: Focus was on the middle window (we verified that earlier in "Test
305 assumptions"). We now mark the middle window with our randomly generated mark.
306 Afterwards, we switch focus away from the middle window to be able to tell if
307 focusing it via its mark will work. If the test works, the goto command seems
308 to be working.
309
310 .t/11-goto.t: Test corner case
311 ----------------------
312 # check that we can specify multiple criteria
313
314 $focus = focus_after('focus left');
315 is($focus, $top->id, "Top window focused");
316
317 $focus = focus_after(qq|[con_mark="$random_mark" con_mark="$random_mark"] focus|);
318 is($focus, $mid->id, "goto worked");
319 ----------------------
320
321 Now we test the same feature, but specifying the mark twice in the command.
322 This should have no effect, but let’s be sure: test it and see if things go
323 wrong.
324
325 .t/11-goto.t: Test second code path
326 ----------------------
327 #####################################################################
328 # Check whether the focus command will switch to a different
329 # workspace if necessary
330 #####################################################################
331
332 my $tmp2 = fresh_workspace;
333
334 is(focused_ws(), $tmp2, 'tmp2 now focused');
335
336 cmd qq|[con_mark="$random_mark"] focus|;
337
338 is(focused_ws(), $tmp, 'tmp now focused');
339 ----------------------
340
341 This part of the test checks that focusing windows by mark works across
342 workspaces. It uses i3test's +focused_ws+ function to get the current
343 workspace.
344
345 .t/11-goto.t: Test second code path
346 ----------------------
347 done_testing;
348 ----------------------
349
350 The end of every testcase has to contain the +done_testing+ line. This tells
351 +complete-run.pl+ that the test was finished successfully. If it does not
352 occur, the test might have crashed during execution -- some of the reasons why
353 that could happen are bugs in the used modules, bugs in the testcase itself or
354 an i3 crash resulting in the testcase being unable to communicate with i3 via
355 IPC anymore.
356
357 [[i3_sync]]
358 == Appendix A: The i3 sync protocol
359
360 Consider the following situation: You open two windows in your testcase, then
361 you use +focus left+ and want to verify that the X11 focus has been updated
362 properly. Sounds simple, right? Let’s assume you use this straight-forward
363 implementation:
364
365 .Racey focus testcase
366 -----------
367 my $left = open_window($x);
368 my $right = open_window($x);
369 cmd 'focus left';
370 is($x->input_focus, $left->id, 'left window focused');
371 ----------
372
373 However, the test fails. Sometimes. Apparantly, there is a race condition in
374 your test. If you think about it, this is because you are using two different
375 pieces of software: You tell i3 to update focus, i3 confirms that, and then you
376 ask X11 to give you the current focus. There is a certain time i3 needs to
377 update the X11 state. If the testcase gets CPU time before X11 processed i3's
378 requests, the test will fail.
379
380 image::i3-sync.png["Diagram of the race condition", title="Diagram of the race condition"]
381
382 One way to "solve" this would be to add +sleep 0.5;+ after the +cmd+ call.
383 After 0.5 seconds it should be safe to assume that focus has been updated,
384 right?
385
386 In practice, this usually works. However, it has several problems:
387
388 1. This is obviously not a clean solution, but a workaround. Ugly.
389 2. On very slow machines, this might not work. Unlikely, but in different
390    situations (a delay to wait for i3 to startup) the necessary time is much
391    harder to guess, even for fast machines.
392 3. This *wastes a lot of time*. Usually, your computer is much faster than 0.5s
393    to update the status. However, sometimes, it might take 0.4s, so we can’t
394    make it +sleep 0.1+.
395
396 To illustrate how grave the problem with wasting time actually is: Before
397 removing all sleeps from the testsuite, a typical run using 4 separate X
398 servers took around 50 seconds on my machine. After removing all the sleeps,
399 we achieved times of about 25 seconds. This is very significant and influences
400 the way you think about tests -- the faster they are, the more likely you are
401 to check whether everything still works quite often (which you should).
402
403 What I am trying to say is: Delays adds up quickly and make the test suite
404 less robust.
405
406 The real solution for this problem is a mechanism which I call "the i3 sync
407 protocol". The idea is to send a request (which does not modify state) via X11
408 to i3 which will then be answered. Due to the request's position in the event
409 queue (*after* all previous events), you can be sure that by the time you
410 receive the reply, all other events have been dealt with by i3 (and, more
411 importantly, X11).
412
413 image::i3-sync-working.png["Diagram of the i3 sync solution", title="Diagram of the i3 sync solution"]
414
415 === Implementation details
416
417 The client which wants to sync with i3 initiates the protocol by sending a
418 ClientMessage to the X11 root window:
419
420 .Send ClientMessage
421 -------------------
422 # Generate a ClientMessage, see xcb_client_message_t
423 my $msg = pack "CCSLLLLLLL",
424     CLIENT_MESSAGE, # response_type
425     32,     # format
426     0,      # sequence
427     $root,  # destination window
428     $x->atom(name => 'I3_SYNC')->id,
429
430     $_sync_window->id,    # data[0]: our own window id
431     $myrnd, # data[1]: a random value to identify the request
432     0,
433     0,
434     0;
435
436 # Send it to the root window -- since i3 uses the SubstructureRedirect
437 # event mask, it will get the ClientMessage.
438 $x->send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);
439 -------------------
440
441 i3 will then reply with the same ClientMessage, sent to the window specified in
442 +data[0]+. In the reply, +data[0]+ and +data[1]+ are exactly the same as in the
443 request. You should use a random value in +data[1]+ and check that you received
444 the same one when getting the reply.
445
446 == Appendix B: Socket activation
447
448 Socket activation is a mechanism which was made popular by systemd, an init
449 replacement. It basically describes creating a listening socket before starting
450 a program.  systemd will invoke the program only when an actual connection to
451 the socket is made, hence the term socket activation.
452
453 The interesting part of this (in the i3 context) is that you can very precisely
454 detect when the program is ready (finished its initialization).
455
456 === Preparing the listening socket
457
458 +complete-run.pl+ will create a listening UNIX socket which it will then pass
459 to i3. This socket will be used by i3 as an additional IPC socket, just like
460 the one it will create on its own. Passing the socket happens implicitly
461 because children will inherit the parent’s sockets when fork()ing and sockets
462 will continue to exist after an exec() call (unless CLOEXEC is set of course).
463
464 The only explicit things +complete-run.pl+ has to do is setting the +LISTEN_FDS+
465 environment variable to the number of sockets which exist (1 in our case) and
466 setting the +LISTEN_PID+ environment variable to the current process ID. Both
467 variables are necessary so that the program (i3) knows how many sockets it
468 should use and if the environment variable is actually intended for it. i3 will
469 then start looking for sockets at file descriptor 3 (since 0, 1 and 2 are used
470 for stdin, stdout and stderr, respectively).
471
472 The actual Perl code which sets up the socket, fork()s, makes sure the socket
473 has file descriptor 3 and sets up the environment variables follows (shortened
474 a bit):
475
476
477 .Setup socket and environment
478 -----------------------------
479 my $socket = IO::Socket::UNIX->new(
480     Listen => 1,
481     Local => $args{unix_socket_path},
482 );
483
484 my $pid = fork;
485 if ($pid == 0) {
486     $ENV{LISTEN_PID} = $$;
487     $ENV{LISTEN_FDS} = 1;
488
489     # Only pass file descriptors 0 (stdin), 1 (stdout),
490     # 2 (stderr) and 3 (socket) to the child.
491     $^F = 3;
492
493     # If the socket does not use file descriptor 3 by chance
494     # already, we close fd 3 and dup2() the socket to 3.
495     if (fileno($socket) != 3) {
496         POSIX::close(3);
497         POSIX::dup2(fileno($socket), 3);
498     }
499
500     exec "/usr/bin/i3";
501 }
502 -----------------------------
503
504 === Waiting for a reply
505
506 In the parent process, we want to know when i3 is ready to answer our IPC
507 requests and handle our windows. Therefore, after forking, we immediately close
508 the listening socket (i3 will handle this side of the socket) and connect to it
509 (remember, we are talking about a named UNIX socket) as a client. This connect
510 call will immediately succeed because the kernel buffers it. Then, we send a
511 request (of type GET_TREE, but that is not really relevant). Writing data to
512 the socket will also succeed immediately because, again, the kernel buffers it
513 (only up to a certain amount of data of course).
514
515 Afterwards, we just blockingly wait until we get an answer. In the child
516 process, i3 will setup the listening socket in its event loop. Immediately
517 after actually starting the event loop, it will notice a new client connecting
518 (the parent process) and handle its request. Since all initialization has been
519 completed successfully by the time the event loop is entered, we can now assume
520 that i3 is ready.
521
522 === Timing and conclusion
523
524 A beautiful feature of this mechanism is that it does not depend on timing. It
525 does not matter when the child process gets CPU time or when the parent process
526 gets CPU time. On heavily loaded machines (or machines with multiple CPUs,
527 cores or unreliable schedulers), this makes waiting for i3 much more robust.
528
529 Before using socket activation, we typically used a +sleep(1)+ and hoped that
530 i3 was initialized by that time. Of course, this breaks on some (slow)
531 computers and wastes a lot of time on faster computers. By using socket
532 activation, we decreased the total amount of time necessary to run all tests
533 (72 files at the time of writing) from > 100 seconds to 16 seconds. This makes
534 it significantly more attractive to run the test suite more often (or at all)
535 during development.
536
537 An alternative approach to using socket activation is polling for the existance
538 of the IPC socket and connecting to it. While this might be slightly easier to
539 implement, it wastes CPU time and is considerably uglier than this solution
540 :). After all, +lib/SocketActivation.pm+ contains only 54 SLOC.