tests: document each and every i3test function

testcases/lib/i3test.pm

@@ -45,6 +45,39 @@ our @EXPORT = qw(
     $x
 );
 
+=head1 NAME
+
+i3test - Testcase setup module
+
+=encoding utf-8
+
+=head1 SYNOPSIS
+
+  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;
+
+=head1 DESCRIPTION
+
+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.
+
+
+i3test automatically "use"s C<Test::More>, C<Data::Dumper>, C<AnyEvent::I3>,
+C<Time::HiRes>’s C<sleep> and C<i3test::Test> so that all of them are available
+to you in your testcase.
+
+See also C<i3test::Test> (L<http://build.i3wm.org/docs/lib-i3test-test.html>)
+which provides additional test instructions (like C<ok> or C<is>).
+
+=cut
+
 my $tester = Test::Builder->new();
 my $_cached_socket_path = undef;
 my $_sync_window = undef;
@@ -128,15 +161,19 @@ __
     goto \&Exporter::import;
 }
 
-#
+=head1 EXPORT
-# Waits for the next event and calls the given callback for every event to
+
-# determine if this is the event we are waiting for.
+=head2 wait_for_event($timeout, $callback)
-#
+
-# Can be used to wait until a window is mapped, until a ClientMessage is
+Waits for the next event and calls the given callback for every event to
-# received, etc.
+determine if this is the event we are waiting for.
-#
+
-# wait_for_event $x, 0.25, sub { $_[0]->{response_type} == MAP_NOTIFY };
+Can be used to wait until a window is mapped, until a ClientMessage is
-#
+received, etc.
+
+  wait_for_event 0.25, sub { $_[0]->{response_type} == MAP_NOTIFY };
+
+=cut
 sub wait_for_event {
     my ($timeout, $cb) = @_;
 
@@ -165,8 +202,24 @@ sub wait_for_event {
     return $result;
 }
 
-# thin wrapper around wait_for_event which waits for MAP_NOTIFY
+=head2 wait_for_map($window)
-# make sure to include 'structure_notify' in the window’s event_mask attribute
+
+Thin wrapper around wait_for_event which waits for MAP_NOTIFY.
+Make sure to include 'structure_notify' in the window’s event_mask attribute.
+
+This function is called by C<open_window>, 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:
+
+  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);
+
+=cut
 sub wait_for_map {
     my ($win) = @_;
     my $id = (blessed($win) && $win->isa('X11::XCB::Window')) ? $win->id : $win;
@@ -175,9 +228,20 @@ sub wait_for_map {
     };
 }
 
-# Wrapper around wait_for_event which waits for UNMAP_NOTIFY. Also calls
+=head2 wait_for_unmap($window)
-# sync_with_i3 to make sure i3 also picked up and processed the UnmapNotify
+
-# event.
+Wrapper around C<wait_for_event> which waits for UNMAP_NOTIFY. Also calls
+C<sync_with_i3> to make sure i3 also picked up and processed the UnmapNotify
+event.
+
+  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');
+
+=cut
 sub wait_for_unmap {
     my ($win) = @_;
     # my $id = (blessed($win) && $win->isa('X11::XCB::Window')) ? $win->id : $win;
@@ -187,25 +251,71 @@ sub wait_for_unmap {
     sync_with_i3();
 }
 
-#
+=head2 open_window([ $args ])
-# Opens a new window (see X11::XCB::Window), maps it, waits until it got mapped
+
-# and synchronizes with i3.
+Opens a new window (see C<X11::XCB::Window>), maps it, waits until it got mapped
-#
+and synchronizes with i3.
-# set dont_map to a true value to avoid mapping
+
-#
+The following arguments can be passed:
-# if you want to change aspects of your window before it would be mapped,
+
-# set before_map to a coderef. $window gets passed as $_ and as first argument.
+=over 4
-#
+
-# if you set both dont_map and before_map, the coderef will be called nevertheless
+=item class
-#
+
-#
+The X11 window class (e.g. WINDOW_CLASS_INPUT_OUTPUT), not to be confused with
-# default values:
+the WM_CLASS!
-#     class => WINDOW_CLASS_INPUT_OUTPUT
+
-#     rect => [ 0, 0, 30, 30 ]
+=item rect
-#     background_color => '#c0c0c0'
+
-#     event_mask => [ 'structure_notify' ]
+An arrayref with 4 members specifying the initial geometry (position and size)
-#     name => 'Window <n>'
+of the window, e.g. C<< [ 0, 100, 70, 50 ] >> for a window appearing at x=0, y=100
-#
+with width=70 and height=50.
+
+Note that this is entirely irrelevant for tiling windows.
+
+=item background_color
+
+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.
+
+=item event_mask
+
+An arrayref contining strings which describe the X11 event mask we use for that
+window. The default is C<< [ 'structure_notify' ] >>.
+
+=item name
+
+The window’s C<_NET_WM_NAME> (UTF-8 window title). By default, this is "Window
+n" with n being replaced by a counter to keep windows apart.
+
+=item dont_map
+
+Set to a true value to avoid mapping the window (making it visible).
+
+=item before_map
+
+A coderef which is called before the window is mapped (unless C<dont_map> is
+true). The freshly created C<$window> is passed as C<$_> and as the first
+argument.
+
+=back
+
+The default values are equivalent to this call:
+
+  open_window(
+    class => WINDOW_CLASS_INPUT_OUTPUT
+    rect => [ 0, 0, 30, 30 ]
+    background_color => '#c0c0c0'
+    event_mask => [ 'structure_notify' ]
+    name => 'Window <n>'
+  );
+
+Usually, though, calls are simpler:
+
+  my $top_window = open_window;
+
+=cut
 sub open_window {
     my %args = @_ == 1 ? %{$_[0]} : @_;
 
@@ -233,8 +343,14 @@ sub open_window {
     return $window;
 }
 
-# Thin wrapper around open_window which sets window_type to
+=head2 open_floating_window([ $args ])
-# _NET_WM_WINDOW_TYPE_UTILITY to make the window floating.
+
+Thin wrapper around open_window which sets window_type to
+C<_NET_WM_WINDOW_TYPE_UTILITY> to make the window floating.
+
+The arguments are the same as those of C<open_window>.
+
+=cut
 sub open_floating_window {
     my %args = @_ == 1 ? %{$_[0]} : @_;
 
@@ -250,6 +366,15 @@ sub open_empty_con {
     return $reply->[0]->{id};
 }
 
+=head2 get_workspace_names()
+
+Returns an arrayref containing the name of every workspace (regardless of its
+output) which currently exists.
+
+  my $workspace_names = get_workspace_names;
+  is(scalar @$workspace_names, 3, 'three workspaces exist currently');
+
+=cut
 sub get_workspace_names {
     my $i3 = i3(get_socket_path());
     my $tree = $i3->get_tree->recv;
@@ -264,6 +389,15 @@ sub get_workspace_names {
     [ map { $_->{name} } @cons ]
 }
 
+=head2 get_unused_workspace
+
+Returns a workspace name which has not yet been used. See also
+C<fresh_workspace> which directly switches to an unused workspace.
+
+  my $ws = get_unused_workspace;
+  cmd "workspace $ws";
+
+=cut
 sub get_unused_workspace {
     my @names = get_workspace_names();
     my $tmp;
@@ -271,7 +405,7 @@ sub get_unused_workspace {
     $tmp
 }
 
-=head2 fresh_workspace(...)
+=head2 fresh_workspace([ $args ])
 
 Switches to an unused workspace and returns the name of that workspace.
 
@@ -304,6 +438,30 @@ sub fresh_workspace {
     $unused
 }
 
+=head2 get_ws($workspace)
+
+Returns the container (from the i3 layout tree) which represents C<$workspace>.
+
+  my $ws = fresh_workspace;
+  my $ws_con = get_ws($ws);
+  ok(!$ws_con->{urgent}, 'fresh workspace not marked urgent');
+
+Here is an example which counts the number of urgent containers recursively,
+starting from the workspace container:
+
+  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");
+
+
+=cut
 sub get_ws {
     my ($name) = @_;
     my $i3 = i3(get_socket_path());
@@ -322,17 +480,61 @@ sub get_ws {
     return first { $_->{name} eq $name } @workspaces;
 }
 
-#
+=head2 get_ws_content($workspace)
-# returns the content (== tree, starting from the node of a workspace)
+
-# of a workspace. If called in array context, also includes the focus
+Returns the content (== tree, starting from the node of a workspace)
-# stack of the workspace
+of a workspace. If called in array context, also includes the focus
-#
+stack of the workspace.
+
+  my $nodes = get_ws_content($ws);
+  is(scalar @$nodes, 4, 'there are four containers at workspace-level');
+
+Or, in array context:
+
+  my $window = open_window;
+  my ($nodes, $focus) = get_ws_content($ws);
+  is($focus->[0], $window->id, 'newly opened window focused');
+
+Note that this function does not do recursion for you! It only returns the
+containers B<on workspace level>. If you want to work with all containers (even
+nested ones) on a workspace, you have to use recursion:
+
+  # 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");
+
+If you also want to deal with floating windows, you have to use C<get_ws>
+instead and access C<< ->{nodes} >> and C<< ->{floating_nodes} >> on your own.
+
+=cut
 sub get_ws_content {
     my ($name) = @_;
     my $con = get_ws($name);
     return wantarray ? ($con->{nodes}, $con->{focus}) : $con->{nodes};
 }
 
+=head2 get_focused($workspace)
+
+Returns the container ID of the currently focused container on C<$workspace>.
+
+  my $ws = fresh_workspace;
+  my $first_window = open_window;
+  my $second_window = open_window;
+  is(get_focused($ws), $second_window, 'second window focused');
+
+=cut
 sub get_focused {
     my ($ws) = @_;
     my $con = get_ws($ws);
@@ -350,6 +552,16 @@ sub get_focused {
     return $lf;
 }
 
+=head2 get_dock_clients([ $dockarea ])
+
+Returns an array of all dock containers in C<$dockarea> (one of "top" or
+"bottom"). If C<$dockarea> is not specified, returns an array of all dock
+containers in any dockarea.
+
+  my @docked = get_dock_clients;
+  is(scalar @docked, 0, 'no dock clients yet');
+
+=cut
 sub get_dock_clients {
     my $which = shift;
 
@@ -374,10 +586,30 @@ sub get_dock_clients {
     return @docked;
 }
 
+=head2 cmd($command)
+
+Sends the specified command to i3.
+
+  my $ws = unused_workspace;
+  cmd "workspace $ws";
+  cmd 'focus right';
+
+=cut
 sub cmd {
     i3(get_socket_path())->command(@_)->recv
 }
 
+=head2 workspace_exists($workspace)
+
+Returns true if C<$workspace> is the name of an existing workspace.
+
+  my $old_ws = focused_ws;
+  # switch away from where we currently are
+  fresh_workspace;
+
+  ok(workspace_exists($old_ws), 'old workspace still exists');
+
+=cut
 sub workspace_exists {
     my ($name) = @_;
     ($name ~~ @{get_workspace_names()})
@@ -387,6 +619,9 @@ sub workspace_exists {
 
 Returns the name of the currently focused workspace.
 
+  my $ws = focused_ws;
+  is($ws, '1', 'i3 starts on workspace 1');
+
 =cut
 sub focused_ws {
     my $i3 = i3(get_socket_path());
@@ -398,16 +633,31 @@ sub focused_ws {
     return $first->{name}
 }
 
-#
+=head2 sync_with_i3([ $args ])
-# 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
+Sends an I3_SYNC ClientMessage with a random value to the root window.
-# processes, only after all other events are done.
+i3 will reply with the same value, but, due to the order of events it
-#
+processes, only after all other events are done.
-# This can be used to ensure the results of a cmd 'focus left' are pushed to
+
-# X11 and that $x->input_focus returns the correct value afterwards.
+This can be used to ensure the results of a cmd 'focus left' are pushed to
-#
+X11 and that C<< $x->input_focus >> returns the correct value afterwards.
-# See also docs/testsuite for a long explanation
+
-#
+See also L<http://build.i3wm.org/docs/testsuite.html> for a longer explanation.
+
+  my $window = open_window;
+  $window->add_hint('urgency');
+  # Ensure i3 picked up the change
+  sync_with_i3;
+
+The only time when you need to use the C<no_cache> argument is when you just
+killed your own X11 connection:
+
+  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);
+
+=cut
 sub sync_with_i3 {
     my %args = @_ == 1 ? %{$_[0]} : @_;
 
@@ -458,8 +708,22 @@ sub sync_with_i3 {
     };
 }
 
+=head2 exit_gracefully($pid, [ $socketpath ])
 
-# Tries to exit i3 gracefully (with the 'exit' cmd) or kills the PID if that fails
+Tries to exit i3 gracefully (with the 'exit' cmd) or kills the PID if that fails.
+
+If C<$socketpath> is not specified, C<get_socket_path()> will be called.
+
+You only need to use this function if you have launched i3 on your own with
+C<launch_with_config>. Otherwise, it will be automatically called when the
+testcase ends.
+
+  use i3test i3_autostart => 0;
+  my $pid = launch_with_config($config);
+  # …
+  exit_gracefully($pid);
+
+=cut
 sub exit_gracefully {
     my ($pid, $socketpath) = @_;
     $socketpath ||= get_socket_path();
@@ -484,7 +748,20 @@ sub exit_gracefully {
     undef $i3_pid;
 }
 
-# Gets the socket path from the I3_SOCKET_PATH atom stored on the X11 root window
+=head2 get_socket_path([ $cache ])
+
+Gets the socket path from the C<I3_SOCKET_PATH> 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 C<$cache>.
+
+  my $i3 = i3(get_socket_path());
+  $i3->command('nop test example')->recv;
+
+To avoid caching:
+
+  my $i3 = i3(get_socket_path(0));
+
+=cut
 sub get_socket_path {
     my ($cache) = @_;
     $cache ||= 1;
@@ -504,9 +781,26 @@ sub get_socket_path {
     return $socketpath;
 }
 
-#
+=head2 launch_with_config($config, [ $args ])
-# launches a new i3 process with the given string as configuration file.
+
-# useful for tests which test specific config file directives.
+Launches a new i3 process with C<$config> as configuration file. Useful for
+tests which test specific config file directives.
+
+  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);
+
+=cut
 sub launch_with_config {
     my ($config, %args) = @_;
 
@@ -557,7 +851,11 @@ sub launch_with_config {
     return $i3_pid;
 }
 
+=head1 AUTHOR
 
+Michael Stapelberg <michael@i3wm.org>
+
+=cut
 
 package i3test::X11;
 use parent 'X11::XCB::Connection';