Mozmill Element Object

This page is currently under development and is only relevant to Mozmill 2.0 and later.

When you manipulate DOM elements with Mozmill, you are actually using a wrapper object that wraps around the DOM element node. This wrapper object contains all the methods that are relevant to the actual DOM node. For example, if you obtain a 'button' element, you can expect to find a 'button.click()' method. If you have a 'menulist' element, you can expect a 'menulist.select()' method. Note that the 'select' method will not be available on, for example, a 'button' element.

The wrapper objects are set up as a hierarchy which can be extended and customized as you see fit (see extending the mozmill element hierarchy). The base element contains all methods and properties that are common across all elements. Element types that have specific functionality sub-class this base class.

For more information on obtaining element references, see finding mozmill elements.

Element Method overview

All sub-classes of elements have these methods:

element getNode();

string getInfo();

boolean exists();

boolean click(int left, int top);

boolean doubleClick(int left, int top);

boolean rightClick(int left, int top);

boolean keypress(string keycode, object modifiers);

boolean mouseDown(int button, int left, int top);

boolean mouseOut(int button, int left, int top);

boolean mouseOver(int button, int left, int top);

boolean mouseUp(int button, int left, int top);

void waitForElement(int timeout, int interval);

void waitThenClick(int timeout, int interval);

CheckBox Method overview

boolean check(boolean state);

RadioButton Method overview

boolean select();

DropList Method overview

boolean select(int index, string label, string value);

TextBox Method overview

boolean sendKeys(string text, object modifiers);

getNode()

Returns the actual wrapped DOM element.

element getNode();

Return value

A DOM element

Example

var wrapper = findElement.ID(controller.document.window, 'elementID');
var element = wrapper.getNode();
controller.window.alert(element.localName); // Alerts the element's tag name

getInfo()

Returns information about the element.

string getInfo();

Return value

A string containing the locatorType and locator of the element

Example

var element = findElement.ID(controller.document.window, 'elementID');
controller.window.alert(element.getInfo()); // Alerts the string "ID: elementID"

exists()

True if the element currently exists in the DOM, false otherwise. This function re-searches the DOM for the element given its locatorType and locator.

boolean exists();

Return value

true if the element exists, otherwise false

Example

var element = findElement.ID(controller.document.window, 'elementID');
// ... do some stuff that may cause element to disappear ...
if (element.exists()) {
  element.click();
}

click()

Fires a normal (left) click at the given element. You can optionally pass in coordinates to the function for where to click. The coordinates are relative to the element's bounding rectangle. With no coordinates specified, it clicks as 0, 0 on that rectangle (top left corner).

boolean click(
  [in int left],
  [in int top]
);

Parameters

left: Left coordinate for click (optional, defaults to 0)
top: Top coordinate for click (optional, defaults to 0)

Return value

true if the action succeeds, otherwise false

Example

var button = findElement.ID(controller.tabs.activeTab, 'buttonID');
button.click();
// Or specify coordinates
button.click(20, 10);

doubleClick()

Fires a normal (left) double click at the given element. You can optionally pass in coordinates to the function for where to click. The coordinates are relative to the element's bounding rectangle. With no coordinates specified, it clicks as 0, 0 on that rectangle (top left corner).

boolean doubleClick(
  [in int left],
  [in int top]
);

Parameters

left: Left coordinate for click (optional, defaults to 0)
top: Top coordinate for click (optional, defaults to 0)

Return value

true if the action succeeds, otherwise false

Example

var element = findElement.ID(controller.tabs.activeTab, 'elementName');
element.doubleClick();
// Or specify coordinates
element.doubleClick(20, 10);

rightClick()

Fires a right click at the given element. You can optionally pass in coordinates to the function for where to click. The coordinates are relative to the element's bounding rectangle. With no coordinates specified, it clicks as 0, 0 on that rectangle (top left corner).

boolean rightClick(
  [in int left],
  [in int top]
);

Parameters

left: Left coordinate for click (optional, defaults to 0)
top: Top coordinate for click (optional, defaults to 0)

Return value

true if the action succeeds, otherwise false

Example

var element = findElement.ID(controller.window.document, 'elementID');
element.rightClick();
// Or specify coordinates
element.rightClick(20, 10);

keypress()

Sends a key event for the given keycode. The modifiers are a JSON object that specifies what key modifiers should be pressed in conjunction with the given key code. The available attribute names for the modifier object are: ctrlKey, altKey, shiftKey, metaKey, and accelKey. Try to avoid the usage of ctrlKey and metaKey if the shortcut is a combination of Ctrl (Windows/Linux) and Cmd (Mac); use accelKey instead which will work regardless of which operating system your test is executing on.

boolean keypress(
  in string keycode,
  [in object modifiers]
);

Parameters

keycode: The key code, either a literal keycode like 'b' or an enum key code like 'VK_ESCAPE'
modifiers: Object of modifiers for this keypress

Return value

true if the action succeeds, otherwise false

Example

// Fire an escape keystroke at an element:
var element = findElement.ID(controller.window.document, 'elementID');
element.keypress('VK_ESCAPE');

// Fire a simple keystroke at an element using the control/command and shift keys
element.keypress('b', {shiftKey: true, accelKey: true});

mouseDown()

Simulates the left button being depressed on the mouse when the mouse is over the given element.

boolean mouseDown(
  in int button,
  [in int left],
  [in int top]
);

Parameters

button: The id of the button to press (0 - left, 1 - middle, 2 - right)
left: The relative horizontal coordinate inside the target element to click
top: The relative vertical coordinate inside the target element to click

Return value

true if the action succeeds, otherwise false

Example

var element = findElement.ID(controller.window.document, 'elementID');
element.mouseDown(1);  // middle button down

mouseOut()

Simulates the mouse leaving the area over an event without clicking on it. If the element is out of view, the element will be scrolled into view before initiating the mouseOut.

boolean mouseOut(
  [in int button],
  [in int left],
  [in int top]
);

Parameters

button: The id of the button to press (0 - left, 1 - middle, 2 - right)
left: The relative horizontal coordinate inside the target element
top: The relative vertical coordinate inside the target element

Return value

true if the action succeeds, otherwise false

Example

var element = findElement.ID(controller.window.document, 'elementID');
element.mouseOut();

mouseOver()

Simulates the mouse entering the area over an event without clicking on it. If the element is out of view, the element will be scrolled into view before initiating the mouseOver

boolean mouseOver(
  [in int button],
  [in int left],
  [in int top]
);

Parameters

button: The id of the button to press (0 - left, 1 - middle, 2 - right)
left: The relative horizontal coordinate inside the target element
top: The relative vertical coordinate inside the target element

Return value

true if the action succeeds, otherwise false

Example

var element = findElement(controller.window.document, 'elementID');
element.mouseOver();

mouseUp()

Simulates the button being released on the mouse when the mouse is over the given element.

boolean mouseUp(
  [in int button],
  [in int left],
  [in int top]
);

Parameters

button: The id of the button to press (0 - left/default, 1 - middle, 2 - right)
left: The relative horizontal coordinate inside the target element
top: The relative vertical coordinate inside the target element

Return value

true if the action succeeds, otherwise false

Example

var element = findElement.ID(controller.window.document, 'elementID');
element.mouseUp();

waitForElement()

Waits for the "element" to appear in the user interface (for instance, if you wanted to wait for part of a page or dialog to load). It checks for "element" every "interval" milliseconds, and gives up if "timeout" milliseconds have passed without the "element" appearing, causing the test to fail. If you accept the defaults, it will check for the element every 100ms and will throw an error if 5 seconds pass without the element appearing.

void waitForElement(
  [in int timeout],
  [in int interval]
);

Parameters

timeout: Total time in milliseconds to wait
interval: How often to check if the element has appeared

Return value

None

Example

var element = findElement.ID(controller.window.document, 'elementID');
element.waitForElement();

waitThenClick()

Waits for the "element" to appear in the user interface. It checks for "element" every "interval" milliseconds, and gives up if "timeout" milliseconds have passed without the "element" appearing, causing the test to fail. Once "element" appears, a click event is immediately fired at it. This is a simple shortcut API for the common pattern of waiting for an element to appear before firing a click event on it. It is the equivalent of calling 'waitForElement' followed by 'click'. Default timeout is 5s.

void waitThenClick(
  [in int timeout],
  [in int interval]
);

Parameters

timeout: Total time in milliseconds to wait
interval: How often to check if the element has appeared

Return value

None

Example

var element = findElement.ID(controller.window.document, 'elementID');
element.waitThenClick();

check()

Fires a click at the given checkbox element to ensure it is either checked or not.

boolean check(
  in boolean state
);

Parameters

state: Pass true to ensure the element is checked, false to ensure it is unchecked. Defaults to false.

Return value

true if the action succeeds, otherwise false

Example

var checkbox = findElement(controller.window.document, 'checkboxID');
checkbox.check(true);

select() - radio

Selects the given radio button by firing a click at it.

boolean select();

Return value

true if the action succeeds, otherwise false

Example

var radio = findElement(controller.window.document, 'radioID');
radio.select();

select() - textbox

Handles selecting an option from a menupopup or an HTML select element. The "element" corresponds to the list. There are multiple ways to select from such a list, either by "index", by "label", or by the "value" associated with that option.

index - to use an index, give it a valid index >=0. If you do not wish to use an index, pass 'null' for this field. Using an index of -1 will reset the current selection.
label - to use label, supply the label. If you do not wish to use an option name, then pass 'null' in this field.
value - to use the value attribute, supply the valid value in this field. If you choose not to supply a value, you can simply leave it off when not including it or pass in 'null'.

boolean select(
  in int index,
  in string label,
  in string value
);

Parameters

index: index of item in drop down list. Use null if you do not wish to specify an index. -1 will reset the selection.
label: Label of the option you wish to select, if you do not wish to use it pass null.
value: Value of the option you wish to select, if you do not wish to use this field either leave it off or pass null.

Return value

true if the action succeeds, otherwise false

Example

// Select only using the index
var list = findElement(controller.window.document, 'listID');
list.select(2);

// Select using the label
list.select(null, 'listItemLabel');

sendKeys()

Types a string of text at the given element. The modifiers are a JSON object that specifies what key modifiers should be pressed in conjunction with the given key code. The available attribute names for the modifier object are: ctrlKey, altKey, shiftKey, metaKey, and accelKey. Try to avoid the usage of ctrlKey and metaKey if the shortcut is a combination of Ctrl (Windows/Linux) and Cmd (Mac); use accelKey instead which will work regardless of which operating system your test is executing on.

boolean sendKeys(
  in string text,
  [in object modifiers]
);

Parameters

text: The text to type
modifiers: Object of modifiers for this keypress.

Return value

true if the action succeeds, otherwise false

Example

var textbox = findElement.ID(controller.window.document, 'textboxID');
textbox.sendKeys('some text to type');