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 (http://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_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.

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

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

AUTHOR

Michael Stapelberg <michael@i3wm.org>