2 # vim:ts=4:sw=4:expandtab
3 use strict; use warnings;
5 use File::Temp qw(tmpnam tempfile tempdir);
10 use lib qw(@abs_top_srcdir@/AnyEvent-I3/blib/lib);
12 use List::Util qw(first);
13 use Time::HiRes qw(sleep);
15 use Scalar::Util qw(blessed);
17 use i3test::Util qw(slurp);
56 i3test - Testcase setup module
64 my $ws = fresh_workspace;
65 is_num_children($ws, 0, 'no containers on this workspace yet');
67 is_num_children($ws, 1, 'one container after "open"');
73 This module is used in every i3 testcase and takes care of automatically
74 starting i3 before any test instructions run. It also saves you typing of lots
75 of boilerplate in every test file.
78 i3test automatically "use"s C<Test::More>, C<Data::Dumper>, C<AnyEvent::I3>,
79 C<Time::HiRes>’s C<sleep> and C<i3test::Test> so that all of them are available
80 to you in your testcase.
82 See also C<i3test::Test> (L<https://build.i3wm.org/docs/lib-i3test-test.html>)
83 which provides additional test instructions (like C<ok> or C<is>).
87 my $tester = Test::Builder->new();
88 my $_cached_socket_path = undef;
89 my $_sync_window = undef;
90 my $tmp_socket_path = undef;
97 return $window_count++;
105 # Skip the remaining cleanup for testcases which set i3_autostart => 0:
106 return if !defined($i3_pid) && !$i3_autostart;
108 # don't trigger SIGCHLD handler
111 # From perldoc -v '$?':
112 # Inside an "END" subroutine $? contains the value
113 # that is going to be given to "exit()".
115 # Since waitpid sets $?, we need to localize it,
116 # otherwise TAP would be misinterpreted our return status
119 # When measuring code coverage, try to exit i3 cleanly (otherwise, .gcda
120 # files are not written)
121 if ($ENV{COVERAGE} || $ENV{VALGRIND}) {
122 exit_gracefully($i3_pid, "/tmp/nested-$ENV{DISPLAY}");
126 or $tester->BAIL_OUT("could not kill i3");
133 my ($class, %args) = @_;
136 $i3_autostart = delete($args{i3_autostart}) // 1;
137 my $i3_config = delete($args{i3_config}) // '-default';
139 my $cv = launch_with_config($i3_config, dont_block => 1)
142 my $test_more_args = '';
143 $test_more_args = join(' ', 'qw(', %args, ')') if keys %args;
147 use Test::More $test_more_args;
150 use Time::HiRes qw(sleep);
153 $tester->BAIL_OUT("$@") if $@;
154 feature->import(":5.10");
158 $x ||= i3test::X11->new;
159 # set the pointer to a predictable position in case a previous test has
161 $x->root->warp_pointer(0, 0);
162 $cv->recv if $i3_autostart;
165 goto \&Exporter::import;
170 =head2 wait_for_event($timeout, $callback)
172 Waits for the next event and calls the given callback for every event to
173 determine if this is the event we are waiting for.
175 Can be used to wait until a window is mapped, until a ClientMessage is
178 wait_for_event 0.25, sub { $_[0]->{response_type} == MAP_NOTIFY };
182 my ($timeout, $cb) = @_;
188 # unfortunately, there is no constant for this
191 my $guard = AE::io $x->get_file_descriptor, $ae_read, sub {
192 while (defined(my $event = $x->poll_for_event)) {
200 # Trigger timeout after $timeout seconds (can be fractional)
201 my $t = AE::timer $timeout, 0, sub { warn "timeout ($timeout secs)"; $cv->send(0) };
203 my $result = $cv->recv;
209 =head2 wait_for_map($window)
211 Thin wrapper around wait_for_event which waits for MAP_NOTIFY.
212 Make sure to include 'structure_notify' in the window’s event_mask attribute.
214 This function is called by C<open_window>, so in most cases, you don’t need to
215 call it on your own. If you need special setup of the window before mapping,
216 you might have to map it on your own and use this function:
218 my $window = open_window(dont_map => 1);
219 # Do something special with the window first
222 # Now map it and wait until it’s been mapped
224 wait_for_map($window);
229 my $id = (blessed($win) && $win->isa('X11::XCB::Window')) ? $win->id : $win;
230 wait_for_event 4, sub {
231 $_[0]->{response_type} == MAP_NOTIFY and $_[0]->{window} == $id
235 =head2 wait_for_unmap($window)
237 Wrapper around C<wait_for_event> which waits for UNMAP_NOTIFY. Also calls
238 C<sync_with_i3> to make sure i3 also picked up and processed the UnmapNotify
241 my $ws = fresh_workspace;
242 my $window = open_window;
243 is_num_children($ws, 1, 'one window on workspace');
246 is_num_children($ws, 0, 'no more windows on this workspace');
251 # my $id = (blessed($win) && $win->isa('X11::XCB::Window')) ? $win->id : $win;
252 wait_for_event 4, sub {
253 $_[0]->{response_type} == UNMAP_NOTIFY # and $_[0]->{window} == $id
258 =head2 open_window([ $args ])
260 Opens a new window (see C<X11::XCB::Window>), maps it, waits until it got mapped
261 and synchronizes with i3.
263 The following arguments can be passed:
269 The X11 window class (e.g. WINDOW_CLASS_INPUT_OUTPUT), not to be confused with
274 An arrayref with 4 members specifying the initial geometry (position and size)
275 of the window, e.g. C<< [ 0, 100, 70, 50 ] >> for a window appearing at x=0, y=100
276 with width=70 and height=50.
278 Note that this is entirely irrelevant for tiling windows.
280 =item background_color
282 The background pixel color of the window, formatted as "#rrggbb", like HTML
283 color codes (e.g. #c0c0c0). This is useful to tell windows apart when actually
284 watching the testcases.
288 An arrayref containing strings which describe the X11 event mask we use for that
289 window. The default is C<< [ 'structure_notify' ] >>.
293 The window’s C<_NET_WM_NAME> (UTF-8 window title). By default, this is "Window
294 n" with n being replaced by a counter to keep windows apart.
298 Set to a true value to avoid mapping the window (making it visible).
302 A coderef which is called before the window is mapped (unless C<dont_map> is
303 true). The freshly created C<$window> is passed as C<$_> and as the first
308 The default values are equivalent to this call:
311 class => WINDOW_CLASS_INPUT_OUTPUT
312 rect => [ 0, 0, 30, 30 ]
313 background_color => '#c0c0c0'
314 event_mask => [ 'structure_notify' ]
318 Usually, though, calls are simpler:
320 my $top_window = open_window;
322 To identify the resulting window object in i3 commands, use the id property:
324 my $top_window = open_window;
325 cmd '[id="' . $top_window->id . '"] kill';
329 my %args = @_ == 1 ? %{$_[0]} : @_;
331 my $dont_map = delete $args{dont_map};
332 my $before_map = delete $args{before_map};
334 $args{class} //= WINDOW_CLASS_INPUT_OUTPUT;
335 $args{rect} //= [ 0, 0, 30, 30 ];
336 $args{background_color} //= '#c0c0c0';
337 $args{event_mask} //= [ 'structure_notify' ];
338 $args{name} //= 'Window ' . counter_window();
340 my $window = $x->root->create_child(%args);
341 $window->add_hint('input');
344 # TODO: investigate why _create is not needed
346 $before_map->($window) for $window;
349 return $window if $dont_map;
352 wait_for_map($window);
354 # MapWindow is sent before i3 even starts rendering: the window is placed at
355 # temporary off-screen coordinates first, and x_push_changes() sends further
356 # X11 requests to set focus etc. Hence, we sync with i3 before continuing.
362 =head2 open_floating_window([ $args ])
364 Thin wrapper around open_window which sets window_type to
365 C<_NET_WM_WINDOW_TYPE_UTILITY> to make the window floating.
367 The arguments are the same as those of C<open_window>.
370 sub open_floating_window {
371 my %args = @_ == 1 ? %{$_[0]} : @_;
373 $args{window_type} = $x->atom(name => '_NET_WM_WINDOW_TYPE_UTILITY');
375 return open_window(\%args);
381 my $reply = $i3->command('open')->recv;
382 return $reply->[0]->{id};
385 =head2 get_workspace_names()
387 Returns an arrayref containing the name of every workspace (regardless of its
388 output) which currently exists.
390 my $workspace_names = get_workspace_names;
391 is(scalar @$workspace_names, 3, 'three workspaces exist currently');
394 sub get_workspace_names {
395 my $i3 = i3(get_socket_path());
396 my $tree = $i3->get_tree->recv;
397 my @outputs = @{$tree->{nodes}};
399 for my $output (@outputs) {
400 next if $output->{name} eq '__i3';
401 # get the first CT_CON of each output
402 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
403 @cons = (@cons, @{$content->{nodes}});
405 [ map { $_->{name} } @cons ]
408 =head2 get_unused_workspace
410 Returns a workspace name which has not yet been used. See also
411 C<fresh_workspace> which directly switches to an unused workspace.
413 my $ws = get_unused_workspace;
417 sub get_unused_workspace {
418 my @names = get_workspace_names();
420 do { $tmp = tmpnam() } while ((scalar grep { $_ eq $tmp } @names) > 0);
424 =head2 fresh_workspace([ $args ])
426 Switches to an unused workspace and returns the name of that workspace.
428 Optionally switches to the specified output first.
430 my $ws = fresh_workspace;
432 # Get a fresh workspace on the second output.
433 my $ws = fresh_workspace(output => 1);
436 sub fresh_workspace {
438 if (exists($args{output})) {
439 my $i3 = i3(get_socket_path());
440 my $tree = $i3->get_tree->recv;
441 my $output = first { $_->{name} eq "fake-$args{output}" }
443 die "BUG: Could not find output $args{output}" unless defined($output);
444 # Get the focused workspace on that output and switch to it.
445 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
446 my $focused = $content->{focus}->[0];
447 my $workspace = first { $_->{id} == $focused } @{$content->{nodes}};
448 $workspace = $workspace->{name};
449 cmd("workspace $workspace");
452 my $unused = get_unused_workspace;
453 cmd("workspace $unused");
457 =head2 get_ws($workspace)
459 Returns the container (from the i3 layout tree) which represents C<$workspace>.
461 my $ws = fresh_workspace;
462 my $ws_con = get_ws($ws);
463 ok(!$ws_con->{urgent}, 'fresh workspace not marked urgent');
465 Here is an example which counts the number of urgent containers recursively,
466 starting from the workspace container:
471 my @children = (@{$con->{nodes}}, @{$con->{floating_nodes}});
472 my $urgent = grep { $_->{urgent} } @children;
473 $urgent += count_urgent($_) for @children;
476 my $urgent = count_urgent(get_ws($ws));
477 is($urgent, 3, "three urgent windows on workspace $ws");
483 my $i3 = i3(get_socket_path());
484 my $tree = $i3->get_tree->recv;
486 my @outputs = @{$tree->{nodes}};
488 for my $output (@outputs) {
489 # get the first CT_CON of each output
490 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
491 @workspaces = (@workspaces, @{$content->{nodes}});
494 # as there can only be one workspace with this name, we can safely
495 # return the first entry
496 return first { $_->{name} eq $name } @workspaces;
499 =head2 get_ws_content($workspace)
501 Returns the content (== tree, starting from the node of a workspace)
502 of a workspace. If called in array context, also includes the focus
503 stack of the workspace.
505 my $nodes = get_ws_content($ws);
506 is(scalar @$nodes, 4, 'there are four containers at workspace-level');
508 Or, in array context:
510 my $window = open_window;
511 my ($nodes, $focus) = get_ws_content($ws);
512 is($focus->[0], $window->id, 'newly opened window focused');
514 Note that this function does not do recursion for you! It only returns the
515 containers B<on workspace level>. If you want to work with all containers (even
516 nested ones) on a workspace, you have to use recursion:
518 # NB: This function does not count floating windows
523 for my $con (@$nodes) {
524 $urgent++ if $con->{urgent};
525 $urgent += count_urgent($con->{nodes});
530 my $nodes = get_ws_content($ws);
531 my $urgent = count_urgent($nodes);
532 is($urgent, 3, "three urgent windows on workspace $ws");
534 If you also want to deal with floating windows, you have to use C<get_ws>
535 instead and access C<< ->{nodes} >> and C<< ->{floating_nodes} >> on your own.
540 my $con = get_ws($name);
541 return wantarray ? ($con->{nodes}, $con->{focus}) : $con->{nodes};
544 =head2 get_focused($workspace)
546 Returns the container ID of the currently focused container on C<$workspace>.
548 Note that the container ID is B<not> the X11 window ID, so comparing the result
549 of C<get_focused> with a window's C<< ->{id} >> property does B<not> work.
551 my $ws = fresh_workspace;
552 my $first_window = open_window;
553 my $first_id = get_focused();
555 my $second_window = open_window;
556 my $second_id = get_focused();
560 is(get_focused($ws), $first_id, 'second window focused');
565 my $con = get_ws($ws);
567 my @focused = @{$con->{focus}};
569 while (@focused > 0) {
571 last unless defined($con->{focus});
572 @focused = @{$con->{focus}};
573 my @cons = grep { $_->{id} == $lf } (@{$con->{nodes}}, @{$con->{'floating_nodes'}});
580 =head2 get_dock_clients([ $dockarea ])
582 Returns an array of all dock containers in C<$dockarea> (one of "top" or
583 "bottom"). If C<$dockarea> is not specified, returns an array of all dock
584 containers in any dockarea.
586 my @docked = get_dock_clients;
587 is(scalar @docked, 0, 'no dock clients yet');
590 sub get_dock_clients {
593 my $tree = i3(get_socket_path())->get_tree->recv;
594 my @outputs = @{$tree->{nodes}};
595 # Children of all dockareas
597 for my $output (@outputs) {
598 if (!defined($which)) {
599 @docked = (@docked, map { @{$_->{nodes}} }
600 grep { $_->{type} eq 'dockarea' }
601 @{$output->{nodes}});
602 } elsif ($which eq 'top') {
603 my $first = first { $_->{type} eq 'dockarea' } @{$output->{nodes}};
604 @docked = (@docked, @{$first->{nodes}}) if defined($first);
605 } elsif ($which eq 'bottom') {
606 my @matching = grep { $_->{type} eq 'dockarea' } @{$output->{nodes}};
607 my $last = $matching[-1];
608 @docked = (@docked, @{$last->{nodes}}) if defined($last);
616 Sends the specified command to i3 and returns the output.
618 my $ws = unused_workspace;
624 i3(get_socket_path())->command(@_)->recv
627 =head2 workspace_exists($workspace)
629 Returns true if C<$workspace> is the name of an existing workspace.
631 my $old_ws = focused_ws;
632 # switch away from where we currently are
635 ok(workspace_exists($old_ws), 'old workspace still exists');
638 sub workspace_exists {
640 (scalar grep { $_ eq $name } @{get_workspace_names()}) > 0;
645 Returns the name of the currently focused workspace.
648 is($ws, '1', 'i3 starts on workspace 1');
652 my $i3 = i3(get_socket_path());
653 my $tree = $i3->get_tree->recv;
654 my $focused = $tree->{focus}->[0];
655 my $output = first { $_->{id} == $focused } @{$tree->{nodes}};
656 my $content = first { $_->{type} eq 'con' } @{$output->{nodes}};
657 my $first = first { $_->{fullscreen_mode} == 1 } @{$content->{nodes}};
658 return $first->{name}
661 =head2 sync_with_i3([ $args ])
663 Sends an I3_SYNC ClientMessage with a random value to the root window.
664 i3 will reply with the same value, but, due to the order of events it
665 processes, only after all other events are done.
667 This can be used to ensure the results of a cmd 'focus left' are pushed to
668 X11 and that C<< $x->input_focus >> returns the correct value afterwards.
670 See also L<https://build.i3wm.org/docs/testsuite.html> for a longer explanation.
672 my $window = open_window;
673 $window->add_hint('urgency');
674 # Ensure i3 picked up the change
677 The only time when you need to use the C<no_cache> argument is when you just
678 killed your own X11 connection:
681 # We need to re-establish the X11 connection which we just killed :).
682 $x = i3test::X11->new;
683 sync_with_i3(no_cache => 1);
687 my %args = @_ == 1 ? %{$_[0]} : @_;
689 # Since we need a (mapped) window for receiving a ClientMessage, we create
690 # one on the first call of sync_with_i3. It will be re-used in all
692 if (!exists($args{window_id}) &&
693 (!defined($_sync_window) || exists($args{no_cache}))) {
694 $_sync_window = open_window(
695 rect => [ -15, -15, 10, 10 ],
696 override_redirect => 1,
701 my $window_id = delete $args{window_id};
702 $window_id //= $_sync_window->id;
704 my $root = $x->get_root_window();
705 # Generate a random number to identify this particular ClientMessage.
706 my $myrnd = int(rand(255)) + 1;
708 # Generate a ClientMessage, see xcb_client_message_t
709 my $msg = pack "CCSLLLLLLL",
710 CLIENT_MESSAGE, # response_type
713 $root, # destination window
714 $x->atom(name => 'I3_SYNC')->id,
716 $window_id, # data[0]: our own window id
717 $myrnd, # data[1]: a random value to identify the request
722 # Send it to the root window -- since i3 uses the SubstructureRedirect
723 # event mask, it will get the ClientMessage.
724 $x->send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);
726 return $myrnd if $args{dont_wait_for_event};
728 # now wait until the reply is here
729 return wait_for_event 4, sub {
732 return 0 unless $event->{response_type} == 161;
734 my ($win, $rnd) = unpack "LL", $event->{data};
735 return ($rnd == $myrnd);
739 =head2 exit_gracefully($pid, [ $socketpath ])
741 Tries to exit i3 gracefully (with the 'exit' cmd) or kills the PID if that fails.
743 If C<$socketpath> is not specified, C<get_socket_path()> will be called.
745 You only need to use this function if you have launched i3 on your own with
746 C<launch_with_config>. Otherwise, it will be automatically called when the
749 use i3test i3_autostart => 0;
750 my $pid = launch_with_config($config);
752 exit_gracefully($pid);
755 sub exit_gracefully {
756 my ($pid, $socketpath) = @_;
757 $socketpath ||= get_socket_path();
761 say "Exiting i3 cleanly...";
762 i3($socketpath)->command('exit')->recv;
768 or $tester->BAIL_OUT("could not kill i3");
771 if ($socketpath =~ m,^/tmp/i3-test-socket-,) {
779 =head2 get_socket_path([ $cache ])
781 Gets the socket path from the C<I3_SOCKET_PATH> atom stored on the X11 root
782 window. After the first call, this function will return a cached version of the
783 socket path unless you specify a false value for C<$cache>.
785 my $i3 = i3(get_socket_path());
786 $i3->command('nop test example')->recv;
790 my $i3 = i3(get_socket_path(0));
793 sub get_socket_path {
797 if ($cache && defined($_cached_socket_path)) {
798 return $_cached_socket_path;
800 my $socketpath = i3test::Util::get_socket_path($x);
801 $_cached_socket_path = $socketpath;
805 =head2 launch_with_config($config, [ $args ])
807 Launches a new i3 process with C<$config> as configuration file. Useful for
808 tests which test specific config file directives.
810 use i3test i3_autostart => 0;
813 # i3 config file (v4)
814 for_window [class="borderless"] border none
815 for_window [title="special borderless title"] border none
818 my $pid = launch_with_config($config);
822 exit_gracefully($pid);
825 sub launch_with_config {
826 my ($config, %args) = @_;
828 $tmp_socket_path = "/tmp/nested-$ENV{DISPLAY}";
830 $args{dont_create_temp_dir} //= 0;
831 $args{validate_config} //= 0;
833 my ($fh, $tmpfile) = tempfile("i3-cfg-for-$ENV{TESTNAME}-XXXXX", UNLINK => 1);
835 say $fh "ipc-socket $tmp_socket_path"
836 unless $args{dont_add_socket_path};
838 if ($config ne '-default') {
841 open(my $conf_fh, '<', '@abs_top_srcdir@/testcases/i3-test.config')
842 or $tester->BAIL_OUT("could not open default config: $!");
844 say $fh scalar <$conf_fh>;
849 my $cv = AnyEvent->condvar;
850 $i3_pid = activate_i3(
851 unix_socket_path => "$tmp_socket_path-activation",
852 display => $ENV{DISPLAY},
853 configfile => $tmpfile,
854 outdir => $ENV{OUTDIR},
855 testname => $ENV{TESTNAME},
856 valgrind => $ENV{VALGRIND},
857 strace => $ENV{STRACE},
858 xtrace => $ENV{XTRACE},
859 restart => $ENV{RESTART},
861 dont_create_temp_dir => $args{dont_create_temp_dir},
862 validate_config => $args{validate_config},
863 inject_randr15 => $args{inject_randr15},
864 inject_randr15_outputinfo => $args{inject_randr15_outputinfo},
867 # If we called i3 with -C, we wait for it to exit and then return as
868 # there's nothing else we need to do.
869 if ($args{validate_config}) {
873 # We need this since exit_gracefully will not be called in this case.
876 return ${^CHILD_ERROR_NATIVE};
879 # force update of the cached socket path in lib/i3test
880 # as soon as i3 has started
881 $cv->cb(sub { get_socket_path(0) });
883 return $cv if $args{dont_block};
885 # blockingly wait until i3 is ready
893 Returns the content of the log file for the current test.
897 my $logfile = "$ENV{OUTDIR}/i3-log-for-$ENV{TESTNAME}";
898 return slurp($logfile);
901 =head2 kill_all_windows
903 Kills all windows to clean up between tests.
906 sub kill_all_windows {
907 # Sync in case not all windows are managed by i3 just yet.
909 cmd '[title=".*"] kill';
912 =head2 events_for($subscribecb, [ $rettype ], [ $eventcbs ])
914 Helper function which returns an array containing all events of type $rettype
915 which were generated by i3 while $subscribecb was running.
917 Set $eventcbs to subscribe to multiple event types and/or perform your own event
922 my ($subscribecb, $rettype, $eventcbs) = @_;
926 if (defined($rettype)) {
927 $eventcbs->{$rettype} = sub { push @events, shift };
929 my $subscribed = AnyEvent->condvar;
930 my $flushed = AnyEvent->condvar;
931 $eventcbs->{tick} = sub {
933 if ($event->{first}) {
934 $subscribed->send($event);
936 $flushed->send($event);
939 my $i3 = i3(get_socket_path(0));
941 $i3->subscribe($eventcbs)->recv;
943 # Subscription established, run the callback.
945 # Now generate a tick event, which we know we’ll receive (and at which point
946 # all other events have been received).
947 my $nonce = int(rand(255)) + 1;
948 $i3->send_tick($nonce);
950 my $tick = $flushed->recv;
951 $tester->is_eq($tick->{payload}, $nonce, 'tick nonce received');
955 =head2 listen_for_binding($cb)
957 Helper function to evaluate whether sending KeyPress/KeyRelease events via XTEST
958 triggers an i3 key binding or not. Expects key bindings to be configured in the
959 form “bindsym <binding> nop <binding>”, e.g. “bindsym Mod4+Return nop
962 is(listen_for_binding(
964 xtest_key_press(133); # Super_L
965 xtest_key_press(36); # Return
966 xtest_key_release(36); # Return
967 xtest_key_release(133); # Super_L
972 'triggered the "Mod4+Return" keybinding');
976 sub listen_for_binding {
978 my $triggered = AnyEvent->condvar;
979 my @events = events_for(
983 $tester->is_eq(scalar @events, 1, 'Received precisely one event');
984 $tester->is_eq($events[0]->{change}, 'run', 'change is "run"');
985 # We look at the command (which is “nop <binding>”) because that is easier
986 # than re-assembling the string representation of $event->{binding}.
987 my $command = $events[0]->{binding}->{command};
988 $command =~ s/^nop //g;
994 Michael Stapelberg <michael@i3wm.org>
999 use parent 'X11::XCB::Connection';
1003 i3test::sync_with_i3();
1005 return $self->SUPER::input_focus(@_);