Mozilla::Mechanize::GUITester - enhances Mozilla::Mechanize with GUI testing.


  use Mozilla::Mechanize::GUITester;

  # regular Mozilla::Mechanize initialization
  my $mech = Mozilla::Mechanize::GUITester->new(%mechanize_args);

  # convenience wrapper over GetElementById and QueryInterface
  my $elem = $mech->get_html_element_by_id("some_id");

  # click mouse at the element position + (1, 1)
  $mech->x_click($elem, 1, 1);

  # play with the mouse relative to the element position
  $mech->x_mouse_down($elem, 2, 2);
  $mech->x_mouse_move($elem, 4, 4);
  $mech->x_mouse_up($elem, 4, 4);

  # send keystrokes to the application

  # press and release left CTRL button. You can click in the middle.

  # run some javascript code and print its result
  print $mech->run_js('return "js: " + 2');

  # find out element style using its id
  print $mech->get_element_style_by_id('the_elem_id', 'background-color');

  # are there any javascript errors?
  print Dumper($mech->console_messages);

  # find out HTTP response status (works only for HTTP protocol)
  print $mech->status;

  # change some text box by sending keypresses - fires all JS events
  my $input = $mech->get_html_element_by_id("tbox", "Input");
  $mech->x_change_text($input, "Hi");


This module enhances Mozilla::Mechanize with convenience functions allowing testing of DHTML/JavaScript rich pages.

It uses X11::GUITest to emulate mouse clicking, dragging and moving over elements in DOM tree.

It also allows running of arbitrary javascript code in the page context and getting back the results.

MMG_TIMEOUT environment variable can be used to adjust timeout of X events (given in milliseconds).



This constructor delegates to Mozilla::Mechanize::new function. See Mozilla::Mechanize manual for its description.



Returns last response status using Mozilla::ObserverService and nsIHTTPChannel:responseStatus function.

Note that it works only for HTTP requests.


Returns last alert contents intercepted through Mozilla::PromptService.

It is useful for communication from javascript.


Returns arrayref of all console messages (e.g. javascript errors) aggregated so far.

See Mozilla nsIConsoleService documentation for more details.


Returns window id of guitester window.


$mech->x_resize_window($width, $height)

Resizes window to $width, $height. Dies if the screen is too small for it.


Pulls all alerts aggregated so far and resets alerts stash. Useful for JS debugging.


Future confirm JavaScript calls will return $res as a result.


Future prompt JavaScript calls will return $res as a result.


Wraps $js_code with JavaScript function and invokes it. Its result is returned as string and intercepted through alert().

See last_alert accessor above.

$mech->get_element_style($element, $style_attribute)

Uses Mozilla::DOM::ComputedStyle to get property value of $style_attribute for the $element retrieved by GetElementById previously.

$mech->get_element_style_by_id($element_id, $style_attribute)

Convenience function to retrieve style property by $element_id. See $mech-get_element_style>.


Returns current full zoom value


Sets full zoom to $zoom.


This is basically body.innerHTML content as provided by Mozilla::Mechanize. See its documentation for more info.


This is more like "View Source" page content. It leaves html tags intact and also doesn't evaluate javascript's document.write calls.

$mech->get_html_element_by_id($html_id, $elem_type)

Uses GetElementById and QueryInterface to get Mozilla::DOM::HTMLElement. If $elem_type is given queries Mozilla::DOM::HTM$elem_typeElement.

See Mozilla::DOM documentation for more details.

$mech->x_click($element, $x, $y, $times)

Emulates mouse click at ($element.left + $x, $ + $y) coordinates.

Optional $times parameter can be used to specify the number of clicks sent.

$mech->x_mouse_down($element, $x, $y)

Presses left mouse button at ($element.left + $x, $ + $y).

$mech->x_mouse_up($element, $x, $y)

Releases left mouse button at ($element.left + $x, $ + $y).

$mech->x_mouse_move($element, $x, $y)

Moves mouse to ($element.left + $x, $ + $y).


Sends $keystroke to mozilla window. It uses X11::GUITest SendKeys function. Please see its documentation for possible $keystroke values.


Uses X11::GUITest PressKey function. Please see its documentation for possible $key values.


Uses X11::GUITest ReleaseKey function to release previously pressed key. Please see its X11::GUITest documentation for possible $key values.

$mech->x_change_text($input, $value)

Changes value of $input edit box to $value. All JavaScript events are fired. It also works on textarea element.

$mech->x_change_select($input, $option_no)

Chooses option $option_no of $input select. All JavaScript events are fired.

$mech->qi($elem, $interface)

Queries interface Mozilla::DOM::HTML$interfaceElement of $elem.

$mech->qi_ns($elem, $interface)

Queries interface Mozilla::DOM::NSHTML$interfaceElement of $elem.


Boris Sukholitko <>


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.