2 # vim:ts=4:sw=4:expandtab
3 use strict; use warnings;
5 use File::Temp qw(tmpnam tempfile tempdir);
11 use List::Util qw(first);
12 use Time::HiRes qw(sleep);
14 use Scalar::Util qw(blessed);
16 use i3test::Util qw(slurp);
52 i3test - Testcase setup module
60 my $ws = fresh_workspace;
61 is_num_children($ws, 0, 'no containers on this workspace yet');
63 is_num_children($ws, 1, 'one container after "open"');
69 This module is used in every i3 testcase and takes care of automatically
70 starting i3 before any test instructions run. It also saves you typing of lots
71 of boilerplate in every test file.
74 i3test automatically "use"s C<Test::More>, C<Data::Dumper>, C<AnyEvent::I3>,
75 C<Time::HiRes>’s C<sleep> and C<i3test::Test> so that all of them are available
76 to you in your testcase.
78 See also C<i3test::Test> (L<http://build.i3wm.org/docs/lib-i3test-test.html>)
79 which provides additional test instructions (like C<ok> or C<is>).
83 my $tester = Test::Builder->new();
84 my $_cached_socket_path = undef;
85 my $_sync_window = undef;
86 my $tmp_socket_path = undef;
93 return $window_count++;
102 # testcases which start i3 manually should always call exit_gracefully
103 # on their own. Let’s see, whether they really did.
104 if (! $i3_autostart) {
105 return unless $i3_pid;
107 $tester->ok(undef, 'testcase called exit_gracefully()');
110 # don't trigger SIGCHLD handler
113 # From perldoc -v '$?':
114 # Inside an "END" subroutine $? contains the value
115 # that is going to be given to "exit()".
117 # Since waitpid sets $?, we need to localize it,
118 # otherwise TAP would be misinterpreted our return status
121 # When measuring code coverage, try to exit i3 cleanly (otherwise, .gcda
122 # files are not written)
123 if ($ENV{COVERAGE} || $ENV{VALGRIND}) {
124 exit_gracefully($i3_pid, "/tmp/nested-$ENV{DISPLAY}");
128 or $tester->BAIL_OUT("could not kill i3");
135 my ($class, %args) = @_;
138 $i3_autostart = delete($args{i3_autostart}) // 1;
140 my $cv = launch_with_config('-default', dont_block => 1)
143 my $test_more_args = '';
144 $test_more_args = join(' ', 'qw(', %args, ')') if keys %args;
148 use Test::More $test_more_args;
151 use Time::HiRes qw(sleep);
154 $tester->BAIL_OUT("$@") if $@;
155 feature->import(":5.10");
159 $x ||= i3test::X11->new;
160 # set the pointer to a predictable position in case a previous test has
162 $x->root->warp_pointer(0, 0);
163 $cv->recv if $i3_autostart;
166 goto \&Exporter::import;
171 =head2 wait_for_event($timeout, $callback)
173 Waits for the next event and calls the given callback for every event to
174 determine if this is the event we are waiting for.
176 Can be used to wait until a window is mapped, until a ClientMessage is
179 wait_for_event 0.25, sub { $_[0]->{response_type} == MAP_NOTIFY };
183 my ($timeout, $cb) = @_;
189 # unfortunately, there is no constant for this
192 my $guard = AE::io $x->get_file_descriptor, $ae_read, sub {
193 while (defined(my $event = $x->poll_for_event)) {
201 # Trigger timeout after $timeout seconds (can be fractional)
202 my $t = AE::timer $timeout, 0, sub { warn "timeout ($timeout secs)"; $cv->send(0) };
204 my $result = $cv->recv;
210 =head2 wait_for_map($window)
212 Thin wrapper around wait_for_event which waits for MAP_NOTIFY.
213 Make sure to include 'structure_notify' in the window’s event_mask attribute.
215 This function is called by C<open_window>, so in most cases, you don’t need to
216 call it on your own. If you need special setup of the window before mapping,
217 you might have to map it on your own and use this function:
219 my $window = open_window(dont_map => 1);
220 # Do something special with the window first
223 # Now map it and wait until it’s been mapped
225 wait_for_map($window);
230 my $id = (blessed($win) && $win->isa('X11::XCB::Window')) ? $win->id : $win;
231 wait_for_event 4, sub {
232 $_[0]->{response_type} == MAP_NOTIFY and $_[0]->{window} == $id
236 =head2 wait_for_unmap($window)
238 Wrapper around C<wait_for_event> which waits for UNMAP_NOTIFY. Also calls
239 C<sync_with_i3> to make sure i3 also picked up and processed the UnmapNotify
242 my $ws = fresh_workspace;
243 my $window = open_window;
244 is_num_children($ws, 1, 'one window on workspace');
247 is_num_children($ws, 0, 'no more windows on this workspace');
252 # my $id = (blessed($win) && $win->isa('X11::XCB::Window')) ? $win->id : $win;
253 wait_for_event 4, sub {
254 $_[0]->{response_type} == UNMAP_NOTIFY # and $_[0]->{window} == $id
259 =head2 open_window([ $args ])
261 Opens a new window (see C<X11::XCB::Window>), maps it, waits until it got mapped
262 and synchronizes with i3.
264 The following arguments can be passed:
270 The X11 window class (e.g. WINDOW_CLASS_INPUT_OUTPUT), not to be confused with
275 An arrayref with 4 members specifying the initial geometry (position and size)
276 of the window, e.g. C<< [ 0, 100, 70, 50 ] >> for a window appearing at x=0, y=100
277 with width=70 and height=50.
279 Note that this is entirely irrelevant for tiling windows.
281 =item background_color
283 The background pixel color of the window, formatted as "#rrggbb", like HTML
284 color codes (e.g. #c0c0c0). This is useful to tell windows apart when actually
285 watching the testcases.
289 An arrayref containing strings which describe the X11 event mask we use for that
290 window. The default is C<< [ 'structure_notify' ] >>.
294 The window’s C<_NET_WM_NAME> (UTF-8 window title). By default, this is "Window
295 n" with n being replaced by a counter to keep windows apart.
299 Set to a true value to avoid mapping the window (making it visible).
303 A coderef which is called before the window is mapped (unless C<dont_map> is
304 true). The freshly created C<$window> is passed as C<$_> and as the first
309 The default values are equivalent to this call:
312 class => WINDOW_CLASS_INPUT_OUTPUT
313 rect => [ 0, 0, 30, 30 ]
314 background_color => '#c0c0c0'
315 event_mask => [ 'structure_notify' ]
319 Usually, though, calls are simpler:
321 my $top_window = open_window;
323 To identify the resulting window object in i3 commands, use the id property:
325 my $top_window = open_window;
326 cmd '[id="' . $top_window->id . '"] kill';
330 my %args = @_ == 1 ? %{$_[0]} : @_;
332 my $dont_map = delete $args{dont_map};
333 my $before_map = delete $args{before_map};
335 $args{class} //= WINDOW_CLASS_INPUT_OUTPUT;
336 $args{rect} //= [ 0, 0, 30, 30 ];
337 $args{background_color} //= '#c0c0c0';
338 $args{event_mask} //= [ 'structure_notify' ];
339 $args{name} //= 'Window ' . counter_window();
341 my $window = $x->root->create_child(%args);
342 $window->add_hint('input');
345 # TODO: investigate why _create is not needed
347 $before_map->($window) for $window;
350 return $window if $dont_map;
353 wait_for_map($window);
357 =head2 open_floating_window([ $args ])
359 Thin wrapper around open_window which sets window_type to
360 C<_NET_WM_WINDOW_TYPE_UTILITY> to make the window floating.
362 The arguments are the same as those of C<open_window>.
365 sub open_floating_window {
366 my %args = @_ == 1 ? %{$_[0]} : @_;
368 $args{window_type} = $x->atom(name => '_NET_WM_WINDOW_TYPE_UTILITY');
370 return open_window(\%args);
376 my $reply = $i3->command('open')->recv;
377 return $reply->[0]->{id};
380 =head2 get_workspace_names()
382 Returns an arrayref containing the name of every workspace (regardless of its
383 output) which currently exists.
385 my $workspace_names = get_workspace_names;
386 is(scalar @$workspace_names, 3, 'three workspaces exist currently');
389 sub get_workspace_names {
390 my $i3 = i3(get_socket_path());
391 my $tree = $i3->get_tree->recv;
392 my @outputs = @{$tree->{nodes}};
394 for my $output (@outputs) {
395 next if $output->{name} eq '__i3';
396 # get the first CT_CON of each output
397 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
398 @cons = (@cons, @{$content->{nodes}});
400 [ map { $_->{name} } @cons ]
403 =head2 get_unused_workspace
405 Returns a workspace name which has not yet been used. See also
406 C<fresh_workspace> which directly switches to an unused workspace.
408 my $ws = get_unused_workspace;
412 sub get_unused_workspace {
413 my @names = get_workspace_names();
415 do { $tmp = tmpnam() } while ((scalar grep { $_ eq $tmp } @names) > 0);
419 =head2 fresh_workspace([ $args ])
421 Switches to an unused workspace and returns the name of that workspace.
423 Optionally switches to the specified output first.
425 my $ws = fresh_workspace;
427 # Get a fresh workspace on the second output.
428 my $ws = fresh_workspace(output => 1);
431 sub fresh_workspace {
433 if (exists($args{output})) {
434 my $i3 = i3(get_socket_path());
435 my $tree = $i3->get_tree->recv;
436 my $output = first { $_->{name} eq "fake-$args{output}" }
438 die "BUG: Could not find output $args{output}" unless defined($output);
439 # Get the focused workspace on that output and switch to it.
440 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
441 my $focused = $content->{focus}->[0];
442 my $workspace = first { $_->{id} == $focused } @{$content->{nodes}};
443 $workspace = $workspace->{name};
444 cmd("workspace $workspace");
447 my $unused = get_unused_workspace;
448 cmd("workspace $unused");
452 =head2 get_ws($workspace)
454 Returns the container (from the i3 layout tree) which represents C<$workspace>.
456 my $ws = fresh_workspace;
457 my $ws_con = get_ws($ws);
458 ok(!$ws_con->{urgent}, 'fresh workspace not marked urgent');
460 Here is an example which counts the number of urgent containers recursively,
461 starting from the workspace container:
466 my @children = (@{$con->{nodes}}, @{$con->{floating_nodes}});
467 my $urgent = grep { $_->{urgent} } @children;
468 $urgent += count_urgent($_) for @children;
471 my $urgent = count_urgent(get_ws($ws));
472 is($urgent, 3, "three urgent windows on workspace $ws");
478 my $i3 = i3(get_socket_path());
479 my $tree = $i3->get_tree->recv;
481 my @outputs = @{$tree->{nodes}};
483 for my $output (@outputs) {
484 # get the first CT_CON of each output
485 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
486 @workspaces = (@workspaces, @{$content->{nodes}});
489 # as there can only be one workspace with this name, we can safely
490 # return the first entry
491 return first { $_->{name} eq $name } @workspaces;
494 =head2 get_ws_content($workspace)
496 Returns the content (== tree, starting from the node of a workspace)
497 of a workspace. If called in array context, also includes the focus
498 stack of the workspace.
500 my $nodes = get_ws_content($ws);
501 is(scalar @$nodes, 4, 'there are four containers at workspace-level');
503 Or, in array context:
505 my $window = open_window;
506 my ($nodes, $focus) = get_ws_content($ws);
507 is($focus->[0], $window->id, 'newly opened window focused');
509 Note that this function does not do recursion for you! It only returns the
510 containers B<on workspace level>. If you want to work with all containers (even
511 nested ones) on a workspace, you have to use recursion:
513 # NB: This function does not count floating windows
518 for my $con (@$nodes) {
519 $urgent++ if $con->{urgent};
520 $urgent += count_urgent($con->{nodes});
525 my $nodes = get_ws_content($ws);
526 my $urgent = count_urgent($nodes);
527 is($urgent, 3, "three urgent windows on workspace $ws");
529 If you also want to deal with floating windows, you have to use C<get_ws>
530 instead and access C<< ->{nodes} >> and C<< ->{floating_nodes} >> on your own.
535 my $con = get_ws($name);
536 return wantarray ? ($con->{nodes}, $con->{focus}) : $con->{nodes};
539 =head2 get_focused($workspace)
541 Returns the container ID of the currently focused container on C<$workspace>.
543 Note that the container ID is B<not> the X11 window ID, so comparing the result
544 of C<get_focused> with a window's C<< ->{id} >> property does B<not> work.
546 my $ws = fresh_workspace;
547 my $first_window = open_window;
548 my $first_id = get_focused();
550 my $second_window = open_window;
551 my $second_id = get_focused();
555 is(get_focused($ws), $first_id, 'second window focused');
560 my $con = get_ws($ws);
562 my @focused = @{$con->{focus}};
564 while (@focused > 0) {
566 last unless defined($con->{focus});
567 @focused = @{$con->{focus}};
568 my @cons = grep { $_->{id} == $lf } (@{$con->{nodes}}, @{$con->{'floating_nodes'}});
575 =head2 get_dock_clients([ $dockarea ])
577 Returns an array of all dock containers in C<$dockarea> (one of "top" or
578 "bottom"). If C<$dockarea> is not specified, returns an array of all dock
579 containers in any dockarea.
581 my @docked = get_dock_clients;
582 is(scalar @docked, 0, 'no dock clients yet');
585 sub get_dock_clients {
588 my $tree = i3(get_socket_path())->get_tree->recv;
589 my @outputs = @{$tree->{nodes}};
590 # Children of all dockareas
592 for my $output (@outputs) {
593 if (!defined($which)) {
594 @docked = (@docked, map { @{$_->{nodes}} }
595 grep { $_->{type} eq 'dockarea' }
596 @{$output->{nodes}});
597 } elsif ($which eq 'top') {
598 my $first = first { $_->{type} eq 'dockarea' } @{$output->{nodes}};
599 @docked = (@docked, @{$first->{nodes}}) if defined($first);
600 } elsif ($which eq 'bottom') {
601 my @matching = grep { $_->{type} eq 'dockarea' } @{$output->{nodes}};
602 my $last = $matching[-1];
603 @docked = (@docked, @{$last->{nodes}}) if defined($last);
611 Sends the specified command to i3 and returns the output.
613 my $ws = unused_workspace;
619 i3(get_socket_path())->command(@_)->recv
622 =head2 workspace_exists($workspace)
624 Returns true if C<$workspace> is the name of an existing workspace.
626 my $old_ws = focused_ws;
627 # switch away from where we currently are
630 ok(workspace_exists($old_ws), 'old workspace still exists');
633 sub workspace_exists {
635 (scalar grep { $_ eq $name } @{get_workspace_names()}) > 0;
640 Returns the name of the currently focused workspace.
643 is($ws, '1', 'i3 starts on workspace 1');
647 my $i3 = i3(get_socket_path());
648 my $tree = $i3->get_tree->recv;
649 my $focused = $tree->{focus}->[0];
650 my $output = first { $_->{id} == $focused } @{$tree->{nodes}};
651 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
652 my $first = first { $_->{fullscreen_mode} == 1 } @{$content->{nodes}};
653 return $first->{name}
656 =head2 sync_with_i3([ $args ])
658 Sends an I3_SYNC ClientMessage with a random value to the root window.
659 i3 will reply with the same value, but, due to the order of events it
660 processes, only after all other events are done.
662 This can be used to ensure the results of a cmd 'focus left' are pushed to
663 X11 and that C<< $x->input_focus >> returns the correct value afterwards.
665 See also L<http://build.i3wm.org/docs/testsuite.html> for a longer explanation.
667 my $window = open_window;
668 $window->add_hint('urgency');
669 # Ensure i3 picked up the change
672 The only time when you need to use the C<no_cache> argument is when you just
673 killed your own X11 connection:
676 # We need to re-establish the X11 connection which we just killed :).
677 $x = i3test::X11->new;
678 sync_with_i3(no_cache => 1);
682 my %args = @_ == 1 ? %{$_[0]} : @_;
684 # Since we need a (mapped) window for receiving a ClientMessage, we create
685 # one on the first call of sync_with_i3. It will be re-used in all
687 if (!exists($args{window_id}) &&
688 (!defined($_sync_window) || exists($args{no_cache}))) {
689 $_sync_window = open_window(
690 rect => [ -15, -15, 10, 10 ],
691 override_redirect => 1,
695 my $window_id = delete $args{window_id};
696 $window_id //= $_sync_window->id;
698 my $root = $x->get_root_window();
699 # Generate a random number to identify this particular ClientMessage.
700 my $myrnd = int(rand(255)) + 1;
702 # Generate a ClientMessage, see xcb_client_message_t
703 my $msg = pack "CCSLLLLLLL",
704 CLIENT_MESSAGE, # response_type
707 $root, # destination window
708 $x->atom(name => 'I3_SYNC')->id,
710 $window_id, # data[0]: our own window id
711 $myrnd, # data[1]: a random value to identify the request
716 # Send it to the root window -- since i3 uses the SubstructureRedirect
717 # event mask, it will get the ClientMessage.
718 $x->send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);
720 return $myrnd if $args{dont_wait_for_event};
722 # now wait until the reply is here
723 return wait_for_event 4, sub {
726 return 0 unless $event->{response_type} == 161;
728 my ($win, $rnd) = unpack "LL", $event->{data};
729 return ($rnd == $myrnd);
733 =head2 exit_gracefully($pid, [ $socketpath ])
735 Tries to exit i3 gracefully (with the 'exit' cmd) or kills the PID if that fails.
737 If C<$socketpath> is not specified, C<get_socket_path()> will be called.
739 You only need to use this function if you have launched i3 on your own with
740 C<launch_with_config>. Otherwise, it will be automatically called when the
743 use i3test i3_autostart => 0;
744 my $pid = launch_with_config($config);
746 exit_gracefully($pid);
749 sub exit_gracefully {
750 my ($pid, $socketpath) = @_;
751 $socketpath ||= get_socket_path();
755 say "Exiting i3 cleanly...";
756 i3($socketpath)->command('exit')->recv;
762 or $tester->BAIL_OUT("could not kill i3");
765 if ($socketpath =~ m,^/tmp/i3-test-socket-,) {
773 =head2 get_socket_path([ $cache ])
775 Gets the socket path from the C<I3_SOCKET_PATH> atom stored on the X11 root
776 window. After the first call, this function will return a cached version of the
777 socket path unless you specify a false value for C<$cache>.
779 my $i3 = i3(get_socket_path());
780 $i3->command('nop test example')->recv;
784 my $i3 = i3(get_socket_path(0));
787 sub get_socket_path {
791 if ($cache && defined($_cached_socket_path)) {
792 return $_cached_socket_path;
795 my $atom = $x->atom(name => 'I3_SOCKET_PATH');
796 my $cookie = $x->get_property(0, $x->get_root_window(), $atom->id, GET_PROPERTY_TYPE_ANY, 0, 256);
797 my $reply = $x->get_property_reply($cookie->{sequence});
798 my $socketpath = $reply->{value};
799 if ($socketpath eq "/tmp/nested-$ENV{DISPLAY}") {
800 $socketpath .= '-activation';
802 $_cached_socket_path = $socketpath;
806 =head2 launch_with_config($config, [ $args ])
808 Launches a new i3 process with C<$config> as configuration file. Useful for
809 tests which test specific config file directives.
811 use i3test i3_autostart => 0;
814 # i3 config file (v4)
815 for_window [class="borderless"] border none
816 for_window [title="special borderless title"] border none
819 my $pid = launch_with_config($config);
823 exit_gracefully($pid);
826 sub launch_with_config {
827 my ($config, %args) = @_;
829 $tmp_socket_path = "/tmp/nested-$ENV{DISPLAY}";
831 $args{dont_create_temp_dir} //= 0;
832 $args{validate_config} //= 0;
834 my ($fh, $tmpfile) = tempfile("i3-cfg-for-$ENV{TESTNAME}-XXXXX", UNLINK => 1);
836 if ($config ne '-default') {
839 open(my $conf_fh, '<', './i3-test.config')
840 or $tester->BAIL_OUT("could not open default config: $!");
842 say $fh scalar <$conf_fh>;
845 say $fh "ipc-socket $tmp_socket_path"
846 unless $args{dont_add_socket_path};
850 my $cv = AnyEvent->condvar;
851 $i3_pid = activate_i3(
852 unix_socket_path => "$tmp_socket_path-activation",
853 display => $ENV{DISPLAY},
854 configfile => $tmpfile,
855 outdir => $ENV{OUTDIR},
856 testname => $ENV{TESTNAME},
857 valgrind => $ENV{VALGRIND},
858 strace => $ENV{STRACE},
859 xtrace => $ENV{XTRACE},
860 restart => $ENV{RESTART},
862 dont_create_temp_dir => $args{dont_create_temp_dir},
863 validate_config => $args{validate_config},
866 # If we called i3 with -C, we wait for it to exit and then return as
867 # there's nothing else we need to do.
868 if ($args{validate_config}) {
872 # We need this since exit_gracefully will not be called in this case.
875 return ${^CHILD_ERROR_NATIVE};
878 # force update of the cached socket path in lib/i3test
879 # as soon as i3 has started
880 $cv->cb(sub { get_socket_path(0) });
882 return $cv if $args{dont_block};
884 # blockingly wait until i3 is ready
892 Returns the content of the log file for the current test.
896 my $logfile = "$ENV{OUTDIR}/i3-log-for-$ENV{TESTNAME}";
897 return slurp($logfile);
902 Michael Stapelberg <michael@i3wm.org>
907 use parent 'X11::XCB::Connection';
911 i3test::sync_with_i3();
913 return $self->SUPER::input_focus(@_);