i3 Perl documentation

NAME

i3test - Testcase setup module

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;

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 Test::More, Data::Dumper, AnyEvent::I3, Time::HiRes’s sleep and i3test::Test so that all of them are available to you in your testcase.

See also i3test::Test (https://build.i3wm.org/docs/lib-i3test-test.html) which provides additional test instructions (like ok or is).

EXPORT

wait_for_event($timeout, $callback)

Waits for the next event and calls the given callback for every event to determine if this is the event we are waiting for.

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 };

wait_for_map($window)

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 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);

wait_for_unmap($window)

Wrapper around wait_for_event which waits for UNMAP_NOTIFY. Also calls 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');

open_window([ $args ])

Opens a new window (see X11::XCB::Window), maps it, waits until it got mapped and synchronizes with i3.

The following arguments can be passed:

class

The X11 window class (e.g. WINDOW_CLASS_INPUT_OUTPUT), not to be confused with the WM_CLASS!

rect

An arrayref with 4 members specifying the initial geometry (position and size) of the window, e.g. [ 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.

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.

event_mask

An arrayref containing strings which describe the X11 event mask we use for that window. The default is [ 'structure_notify' ].

name

The window’s _NET_WM_NAME (UTF-8 window title). By default, this is "Window n" with n being replaced by a counter to keep windows apart.

dont_map

Set to a true value to avoid mapping the window (making it visible).

before_map

A coderef which is called before the window is mapped (unless dont_map is true). The freshly created $window is passed as $_ and as the first argument.

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;

To identify the resulting window object in i3 commands, use the id property:

  my $top_window = open_window;
  cmd '[id="' . $top_window->id . '"] kill';

open_floating_window([ $args ])

Thin wrapper around open_window which sets window_type to _NET_WM_WINDOW_TYPE_UTILITY to make the window floating.

The arguments are the same as those of open_window.

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');

get_output_for_workspace()

Returns the name of the output on which this workspace resides

  cmd 'focus output fake-1';
  cmd 'workspace 1';
  is(get_output_for_workspace('1'), 'fake-0', 'Workspace 1 in output fake-0');

get_unused_workspace

Returns a workspace name which has not yet been used. See also fresh_workspace which directly switches to an unused workspace.

  my $ws = get_unused_workspace;
  cmd "workspace $ws";

fresh_workspace([ $args ])

Switches to an unused workspace and returns the name of that workspace.

Optionally switches to the specified output first.

    my $ws = fresh_workspace;

    # Get a fresh workspace on the second output.
    my $ws = fresh_workspace(output => 1);

get_ws($workspace)

Returns the container (from the i3 layout tree) which represents $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");

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 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 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 get_ws instead and access ->{nodes} and ->{floating_nodes} on your own.

get_focused($workspace)

Returns the container ID of the currently focused container on $workspace.

Note that the container ID is not the X11 window ID, so comparing the result of get_focused with a window's ->{id} property does not work.

  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');

get_dock_clients([ $dockarea ])

Returns an array of all dock containers in $dockarea (one of "top" or "bottom"). If $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');

cmd($command)

Sends the specified command to i3 and returns the output.

  my $ws = unused_workspace;
  cmd "workspace $ws";
  cmd 'focus right';

workspace_exists($workspace)

Returns true if $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');

focused_output

Returns the name of the currently focused output.

  is(focused_output, 'fake-0', 'i3 starts on output 0');

focused_ws

Returns the name of the currently focused workspace.

  my $ws = focused_ws;
  is($ws, '1', 'i3 starts on workspace 1');

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 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.

See also https://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 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);

exit_gracefully($pid, [ $socketpath ])

Tries to exit i3 gracefully (with the 'exit' cmd) or kills the PID if that fails.

If $socketpath is not specified, get_socket_path() will be called.

You only need to use this function if you have launched i3 on your own with 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);

exit_forcefully($pid, [ $signal ])

Tries to exit i3 forcefully by sending a signal (defaults to SIGTERM).

You only need to use this function if you want to test signal handling (in which case you must have launched i3 on your own with launch_with_config).

  use i3test i3_autostart => 0;
  my $pid = launch_with_config($config);
  # …
  exit_forcefully($pid);

get_socket_path([ $cache ])

Gets the socket path from the 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 $cache.

  my $i3 = i3(get_socket_path());
  $i3->command('nop test example')->recv;

To avoid caching:

  my $i3 = i3(get_socket_path(0));

launch_with_config($config, [ $args ])

Launches a new i3 process with $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);

get_i3_log

Returns the content of the log file for the current test.

kill_all_windows

Kills all windows to clean up between tests.

events_for($subscribecb, [ $rettype ], [ $eventcbs ])

Helper function which returns an array containing all events of type $rettype which were generated by i3 while $subscribecb was running.

Set $eventcbs to subscribe to multiple event types and/or perform your own event aggregation.

listen_for_binding($cb)

Helper function to evaluate whether sending KeyPress/KeyRelease events via XTEST triggers an i3 key binding or not. Expects key bindings to be configured in the form “bindsym <binding> nop <binding>”, e.g. “bindsym Mod4+Return nop Mod4+Return”.

  is(listen_for_binding(
      sub {
          xtest_key_press(133); # Super_L
          xtest_key_press(36); # Return
          xtest_key_release(36); # Return
          xtest_key_release(133); # Super_L
          xtest_sync_with_i3;
      },
      ),
     'Mod4+Return',
     'triggered the "Mod4+Return" keybinding');

is_net_wm_state_focused

Returns true if the given window has the _NET_WM_STATE_FOCUSED atom.

    ok(is_net_wm_state_focused($window), '_NET_WM_STATE_FOCUSED set');

cmp_tree([ $args ])

Compares the tree layout before and after an operation inside a subtest.

The following arguments can be passed:

layout_before

Required argument. The initial layout to be created. For example, 'H[ V[ a* S[ b c ] d ] e ]' or 'V[a b] T[c d*]'. The layout will be converted to a JSON file which will be passed to i3's append_layout command.

The syntax's rules, assertions and limitations are:

1. Upper case letters H, V, S, T mean horizontal, vertical, stacked and tabbed layout respectively. They must be followed by an opening square bracket and must be closed with a closing square bracket. Each of the non-leaf containers is marked with their corresponding letter followed by a number indicating the position of the container relative to other containers of the same type. For example, 'H[V[xxx] V[xxx] H[xxx]]' will mark the non-leaf containers as H1, V1, V2, H2.
2. Spaces are ignored.
3. Other alphanumeric characters mean a new window which uses the provided character for its class and name. Eg 'H[a b]' will open windows with classes 'a' and 'b' inside a horizontal split. Windows use a single character for their class, eg 'H[xxx]' will open 3 windows with class 'x'.
4. Asterisks after a window mean that the window must be focused after the layout is loaded. Currently, focusing non-leaf containers must be done manually, in the callback (cb) function.

cb

Subroutine to be called after the layout provided by layout_before is created but before the resulting layout (layout_after) is checked.

layout_after

Required argument. The final layout in which the tree is expected to be after the callback is called. Uses the same syntax with layout_before. For non-leaf containers, their layout (horizontal, vertical, stacked, tabbed) is compared with the corresponding letter (H, V, S, T). For leaf containers, their name is compared with the provided alphanumeric.

ws

The workspace in which the layout will be created. Will switch focus to it. If not provided, a new one is created.

msg

Message to prepend to the subtest's name. If not empty, it will be followed by ': '.

dont_kill

By default, all windows are killed before the layout_before layout is loaded. Set to 1 to avoid this.

AUTHOR

Michael Stapelberg <michael@i3wm.org>