1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
|
<!doctype html>
<html lang="en">
<head>
<link rel="icon" type="image/png" href="/favicon.png">
<meta charset="utf-8">
<meta name="generator" content="Pod::Simple::HTML">
<meta name="description" content="i3 Perl documentation">
<link rel="stylesheet" href="http://i3wm.org/css/style.css" type="text/css" />
<style type="text/css">
.pod pre {
background: #333;
border: 1px solid #555;
border-left: 5px solid #555;
padding: 0.5em;
padding-left: 0;
padding-right: 0.5em;
white-space: pre;
color: white;
}
.pod ul {
list-style-type: none;
}
.pod li {
margin-bottom: 0 !important;
}
tt {
font-family: 'Droid Sans Mono', sans-serif;
font-size: inherit;
}
.pod h1 a, .pod h2 a, .pod h3 a, .pod h4 a {
text-decoration: none;
color: white;
}
</style>
<title>
i3test</title>
</head>
<body>
<div id="main">
<a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>
<ul id="nav">
<li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>
<li><a href="/screenshots">Screens</a></li>
<li><a href="http://faq.i3wm.org/">FAQ</a></li>
<li><a href="/contact">Contact</a></li>
<li><a href="http://bugs.i3wm.org/">Bugs</a></li>
</ul>
<br style="clear: both">
<div id="content" class="pod">
<h1>i3 Perl documentation</h1>
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<li class='indexItem indexItem1'><a href='#EXPORT'>EXPORT</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#wait_for_event(%24timeout%2C_%24callback)'>wait_for_event($timeout, $callback)</a>
<li class='indexItem indexItem2'><a href='#wait_for_map(%24window)'>wait_for_map($window)</a>
<li class='indexItem indexItem2'><a href='#wait_for_unmap(%24window)'>wait_for_unmap($window)</a>
<li class='indexItem indexItem2'><a href='#open_window(%5B_%24args_%5D)'>open_window([ $args ])</a>
<li class='indexItem indexItem2'><a href='#open_floating_window(%5B_%24args_%5D)'>open_floating_window([ $args ])</a>
<li class='indexItem indexItem2'><a href='#get_workspace_names()'>get_workspace_names()</a>
<li class='indexItem indexItem2'><a href='#get_unused_workspace'>get_unused_workspace</a>
<li class='indexItem indexItem2'><a href='#fresh_workspace(%5B_%24args_%5D)'>fresh_workspace([ $args ])</a>
<li class='indexItem indexItem2'><a href='#get_ws(%24workspace)'>get_ws($workspace)</a>
<li class='indexItem indexItem2'><a href='#get_ws_content(%24workspace)'>get_ws_content($workspace)</a>
<li class='indexItem indexItem2'><a href='#get_focused(%24workspace)'>get_focused($workspace)</a>
<li class='indexItem indexItem2'><a href='#get_dock_clients(%5B_%24dockarea_%5D)'>get_dock_clients([ $dockarea ])</a>
<li class='indexItem indexItem2'><a href='#cmd(%24command)'>cmd($command)</a>
<li class='indexItem indexItem2'><a href='#workspace_exists(%24workspace)'>workspace_exists($workspace)</a>
<li class='indexItem indexItem2'><a href='#focused_ws'>focused_ws</a>
<li class='indexItem indexItem2'><a href='#sync_with_i3(%5B_%24args_%5D)'>sync_with_i3([ $args ])</a>
<li class='indexItem indexItem2'><a href='#exit_gracefully(%24pid%2C_%5B_%24socketpath_%5D)'>exit_gracefully($pid, [ $socketpath ])</a>
<li class='indexItem indexItem2'><a href='#get_socket_path(%5B_%24cache_%5D)'>get_socket_path([ $cache ])</a>
<li class='indexItem indexItem2'><a href='#launch_with_config(%24config%2C_%5B_%24args_%5D)'>launch_with_config($config, [ $args ])</a>
<li class='indexItem indexItem2'><a href='#get_i3_log'>get_i3_log</a>
</ul>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>i3test - Testcase setup module</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre><tt> use i3test;
my $ws = fresh_workspace;
is_num_children($ws, 0, 'no containers on this workspace yet');
cmd 'open';
is_num_children($ws, 1, 'one container after "open"');
done_testing;</tt></pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This module is used in every i3 testcase and takes care of automatically starting i3 before any test instructions run. It also saves you typing of lots of boilerplate in every test file.</p>
<p>i3test automatically "use"s <code>Test::More</code>, <code>Data::Dumper</code>, <code>AnyEvent::I3</code>, <code>Time::HiRes</code>’s <code>sleep</code> and <code>i3test::Test</code> so that all of them are available to you in your testcase.</p>
<p>See also <code>i3test::Test</code> (<a href="http://build.i3wm.org/docs/lib-i3test-test.html" class="podlinkurl"
>http://build.i3wm.org/docs/lib-i3test-test.html</a>) which provides additional test instructions (like <code>ok</code> or <code>is</code>).</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="EXPORT"
>EXPORT</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="wait_for_event($timeout,_$callback)"
>wait_for_event($timeout, $callback)</a></h2>
<p>Waits for the next event and calls the given callback for every event to determine if this is the event we are waiting for.</p>
<p>Can be used to wait until a window is mapped, until a ClientMessage is received, etc.</p>
<pre><tt> wait_for_event 0.25, sub { $_[0]->{response_type} == MAP_NOTIFY };</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="wait_for_map($window)"
>wait_for_map($window)</a></h2>
<p>Thin wrapper around wait_for_event which waits for MAP_NOTIFY. Make sure to include 'structure_notify' in the window’s event_mask attribute.</p>
<p>This function is called by <code>open_window</code>, so in most cases, you don’t need to call it on your own. If you need special setup of the window before mapping, you might have to map it on your own and use this function:</p>
<pre><tt> my $window = open_window(dont_map => 1);
# Do something special with the window first
# …
# Now map it and wait until it’s been mapped
$window->map;
wait_for_map($window);</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="wait_for_unmap($window)"
>wait_for_unmap($window)</a></h2>
<p>Wrapper around <code>wait_for_event</code> which waits for UNMAP_NOTIFY. Also calls <code>sync_with_i3</code> to make sure i3 also picked up and processed the UnmapNotify event.</p>
<pre><tt> my $ws = fresh_workspace;
my $window = open_window;
is_num_children($ws, 1, 'one window on workspace');
$window->unmap;
wait_for_unmap;
is_num_children($ws, 0, 'no more windows on this workspace');</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="open_window([_$args_])"
>open_window([ $args ])</a></h2>
<p>Opens a new window (see <code>X11::XCB::Window</code>), maps it, waits until it got mapped and synchronizes with i3.</p>
<p>The following arguments can be passed:</p>
<dl>
<dt><a name="class"
>class</a></dt>
<dd>
<p>The X11 window class (e.g. WINDOW_CLASS_INPUT_OUTPUT), not to be confused with the WM_CLASS!</p>
<dt><a name="rect"
>rect</a></dt>
<dd>
<p>An arrayref with 4 members specifying the initial geometry (position and size) of the window, e.g. <code>[ 0, 100, 70, 50 ]</code> for a window appearing at x=0, y=100 with width=70 and height=50.</p>
<p>Note that this is entirely irrelevant for tiling windows.</p>
<dt><a name="background_color"
>background_color</a></dt>
<dd>
<p>The background pixel color of the window, formatted as "#rrggbb", like HTML color codes (e.g. #c0c0c0). This is useful to tell windows apart when actually watching the testcases.</p>
<dt><a name="event_mask"
>event_mask</a></dt>
<dd>
<p>An arrayref containing strings which describe the X11 event mask we use for that window. The default is <code>[ 'structure_notify' ]</code>.</p>
<dt><a name="name"
>name</a></dt>
<dd>
<p>The window’s <code>_NET_WM_NAME</code> (UTF-8 window title). By default, this is "Window n" with n being replaced by a counter to keep windows apart.</p>
<dt><a name="dont_map"
>dont_map</a></dt>
<dd>
<p>Set to a true value to avoid mapping the window (making it visible).</p>
<dt><a name="before_map"
>before_map</a></dt>
<dd>
<p>A coderef which is called before the window is mapped (unless <code>dont_map</code> is true). The freshly created <code>$window</code> is passed as <code>$_</code> and as the first argument.</p>
</dd>
</dl>
<p>The default values are equivalent to this call:</p>
<pre><tt> open_window(
class => WINDOW_CLASS_INPUT_OUTPUT
rect => [ 0, 0, 30, 30 ]
background_color => '#c0c0c0'
event_mask => [ 'structure_notify' ]
name => 'Window <n>'
);</tt></pre>
<p>Usually, though, calls are simpler:</p>
<pre><tt> my $top_window = open_window;</tt></pre>
<p>To identify the resulting window object in i3 commands, use the id property:</p>
<pre><tt> my $top_window = open_window;
cmd '[id="' . $top_window->id . '"] kill';</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="open_floating_window([_$args_])"
>open_floating_window([ $args ])</a></h2>
<p>Thin wrapper around open_window which sets window_type to <code>_NET_WM_WINDOW_TYPE_UTILITY</code> to make the window floating.</p>
<p>The arguments are the same as those of <code>open_window</code>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_workspace_names()"
>get_workspace_names()</a></h2>
<p>Returns an arrayref containing the name of every workspace (regardless of its output) which currently exists.</p>
<pre><tt> my $workspace_names = get_workspace_names;
is(scalar @$workspace_names, 3, 'three workspaces exist currently');</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_unused_workspace"
>get_unused_workspace</a></h2>
<p>Returns a workspace name which has not yet been used. See also <code>fresh_workspace</code> which directly switches to an unused workspace.</p>
<pre><tt> my $ws = get_unused_workspace;
cmd "workspace $ws";</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="fresh_workspace([_$args_])"
>fresh_workspace([ $args ])</a></h2>
<p>Switches to an unused workspace and returns the name of that workspace.</p>
<p>Optionally switches to the specified output first.</p>
<pre><tt> my $ws = fresh_workspace;
# Get a fresh workspace on the second output.
my $ws = fresh_workspace(output => 1);</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_ws($workspace)"
>get_ws($workspace)</a></h2>
<p>Returns the container (from the i3 layout tree) which represents <code>$workspace</code>.</p>
<pre><tt> my $ws = fresh_workspace;
my $ws_con = get_ws($ws);
ok(!$ws_con->{urgent}, 'fresh workspace not marked urgent');</tt></pre>
<p>Here is an example which counts the number of urgent containers recursively, starting from the workspace container:</p>
<pre><tt> sub count_urgent {
my ($con) = @_;
my @children = (@{$con->{nodes}}, @{$con->{floating_nodes}});
my $urgent = grep { $_->{urgent} } @children;
$urgent += count_urgent($_) for @children;
return $urgent;
}
my $urgent = count_urgent(get_ws($ws));
is($urgent, 3, "three urgent windows on workspace $ws");</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_ws_content($workspace)"
>get_ws_content($workspace)</a></h2>
<p>Returns the content (== tree, starting from the node of a workspace) of a workspace. If called in array context, also includes the focus stack of the workspace.</p>
<pre><tt> my $nodes = get_ws_content($ws);
is(scalar @$nodes, 4, 'there are four containers at workspace-level');</tt></pre>
<p>Or, in array context:</p>
<pre><tt> my $window = open_window;
my ($nodes, $focus) = get_ws_content($ws);
is($focus->[0], $window->id, 'newly opened window focused');</tt></pre>
<p>Note that this function does not do recursion for you! It only returns the containers <b>on workspace level</b>. If you want to work with all containers (even nested ones) on a workspace, you have to use recursion:</p>
<pre><tt> # NB: This function does not count floating windows
sub count_urgent {
my ($nodes) = @_;
my $urgent = 0;
for my $con (@$nodes) {
$urgent++ if $con->{urgent};
$urgent += count_urgent($con->{nodes});
}
return $urgent;
}
my $nodes = get_ws_content($ws);
my $urgent = count_urgent($nodes);
is($urgent, 3, "three urgent windows on workspace $ws");</tt></pre>
<p>If you also want to deal with floating windows, you have to use <code>get_ws</code> instead and access <code>->{nodes}</code> and <code>->{floating_nodes}</code> on your own.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_focused($workspace)"
>get_focused($workspace)</a></h2>
<p>Returns the container ID of the currently focused container on <code>$workspace</code>.</p>
<p>Note that the container ID is <b>not</b> the X11 window ID, so comparing the result of <code>get_focused</code> with a window's <code>->{id}</code> property does <b>not</b> work.</p>
<pre><tt> my $ws = fresh_workspace;
my $first_window = open_window;
my $first_id = get_focused();
my $second_window = open_window;
my $second_id = get_focused();
cmd 'focus left';
is(get_focused($ws), $first_id, 'second window focused');</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_dock_clients([_$dockarea_])"
>get_dock_clients([ $dockarea ])</a></h2>
<p>Returns an array of all dock containers in <code>$dockarea</code> (one of "top" or "bottom"). If <code>$dockarea</code> is not specified, returns an array of all dock containers in any dockarea.</p>
<pre><tt> my @docked = get_dock_clients;
is(scalar @docked, 0, 'no dock clients yet');</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="cmd($command)"
>cmd($command)</a></h2>
<p>Sends the specified command to i3 and returns the output.</p>
<pre><tt> my $ws = unused_workspace;
cmd "workspace $ws";
cmd 'focus right';</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="workspace_exists($workspace)"
>workspace_exists($workspace)</a></h2>
<p>Returns true if <code>$workspace</code> is the name of an existing workspace.</p>
<pre><tt> my $old_ws = focused_ws;
# switch away from where we currently are
fresh_workspace;
ok(workspace_exists($old_ws), 'old workspace still exists');</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="focused_ws"
>focused_ws</a></h2>
<p>Returns the name of the currently focused workspace.</p>
<pre><tt> my $ws = focused_ws;
is($ws, '1', 'i3 starts on workspace 1');</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="sync_with_i3([_$args_])"
>sync_with_i3([ $args ])</a></h2>
<p>Sends an I3_SYNC ClientMessage with a random value to the root window. i3 will reply with the same value, but, due to the order of events it processes, only after all other events are done.</p>
<p>This can be used to ensure the results of a cmd 'focus left' are pushed to X11 and that <code>$x->input_focus</code> returns the correct value afterwards.</p>
<p>See also <a href="http://build.i3wm.org/docs/testsuite.html" class="podlinkurl"
>http://build.i3wm.org/docs/testsuite.html</a> for a longer explanation.</p>
<pre><tt> my $window = open_window;
$window->add_hint('urgency');
# Ensure i3 picked up the change
sync_with_i3;</tt></pre>
<p>The only time when you need to use the <code>no_cache</code> argument is when you just killed your own X11 connection:</p>
<pre><tt> cmd 'kill client';
# We need to re-establish the X11 connection which we just killed :).
$x = i3test::X11->new;
sync_with_i3(no_cache => 1);</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="exit_gracefully($pid,_[_$socketpath_])"
>exit_gracefully($pid, [ $socketpath ])</a></h2>
<p>Tries to exit i3 gracefully (with the 'exit' cmd) or kills the PID if that fails.</p>
<p>If <code>$socketpath</code> is not specified, <code>get_socket_path()</code> will be called.</p>
<p>You only need to use this function if you have launched i3 on your own with <code>launch_with_config</code>. Otherwise, it will be automatically called when the testcase ends.</p>
<pre><tt> use i3test i3_autostart => 0;
my $pid = launch_with_config($config);
# …
exit_gracefully($pid);</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_socket_path([_$cache_])"
>get_socket_path([ $cache ])</a></h2>
<p>Gets the socket path from the <code>I3_SOCKET_PATH</code> atom stored on the X11 root window. After the first call, this function will return a cached version of the socket path unless you specify a false value for <code>$cache</code>.</p>
<pre><tt> my $i3 = i3(get_socket_path());
$i3->command('nop test example')->recv;</tt></pre>
<p>To avoid caching:</p>
<pre><tt> my $i3 = i3(get_socket_path(0));</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="launch_with_config($config,_[_$args_])"
>launch_with_config($config, [ $args ])</a></h2>
<p>Launches a new i3 process with <code>$config</code> as configuration file. Useful for tests which test specific config file directives.</p>
<pre><tt> use i3test i3_autostart => 0;
my $config = <<EOT;
# i3 config file (v4)
for_window [class="borderless"] border none
for_window [title="special borderless title"] border none
EOT
my $pid = launch_with_config($config);
# …
exit_gracefully($pid);</tt></pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_i3_log"
>get_i3_log</a></h2>
<p>Returns the content of the log file for the current test.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Michael Stapelberg <michael@i3wm.org></p>
<!-- end doc -->
</body></html>
|
