mozilla

Revision 91894 of Mozmill Element Object

  • Revision slug: Mozmill/Mozmill_Element_Object
  • Revision title: Mozmill Element Object
  • Revision id: 91894
  • Created:
  • Creator: ahal
  • Is current revision? No
  • Comment page created, 4825 words added

Revision Content

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.

MozMillElement Method overview

boolean click(in Elem element, in int left, int top);
boolean doubleClick(in Elem element, in int left, in int top);
boolean keypress(in Elem element, in string keycode, in object modifiers);
boolean mouseDown(in Elem element, in int button, in int left, in int top);
boolean mouseOut(in Elem element, in int button, in int left, in int top);
boolean mouseOver(in Elem element, in int button, in int left, in int top);
boolean mouseUp(in Elem element, in int button, in int left, in int top);
boolean rightClick(in Elem element, in int left, in int top);
boolean type(in Elem element, in string text);
void waitForElement(in Elem element, in int timeout, in int interval);
void waitThenClick(in Elem element, in int timeout, in int interval);

Attributes

Attribute Type Description
menus {{ interface("Node") }} A set of attributes to access the menus and menu items as elements. Click here for information
tabs.activeTab DOMDocument Returns the document that is rendered by the current active tab in the browser
tabs.activeTabIndex int Returns the index number of the currently active tab. It is a browser specific method

Interaction Methods

check()

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

boolean check(
  in Elem element,
  in boolean state
); 
Parameters
element
An element to attempt to check (should be a checkbox or it will fail).
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
controller.check(new elementslib.ID(controller.window.document, 'foo'), true);

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 Elem element,
  in int left,
  in int top
); 
Parameters
element
An element to click on
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
controller.click(new elementslib.ID(controller.window.document, 'foo'));
// Or specify coordinates
controller.click(new elementslib.ID(controller.window.document, 'foo'), 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 Elem element,
  in int left,
  in int top
); 
Parameters
element
An element to click on
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
controller.doubleClick(new elementslib.ID(controller.window.document, 'foo'));
// Or specify coordinates
controller.doubleClick(new elementslib.ID(controller.window.document, 'foo'), 20, 10);

dragDropElemToElem()

Drags the element specified by elementStart to the x,y coordinates of the element specified by elementFinish. Currently only works in content space (i.e. on a web page).

boolean dragDropElemToElem(
  in Elem elementStart,
  in Elem elementFinish
); 
Parameters
elementStart
Element to start dragging
elementFinish
Target element to drag to
Return value

true if the action succeeds, otherwise false.

Example
controller.dragDropElemToElem(new elementslib.ID(controller.window.document, 'foo'),
                              new elementslib.ID(controller.window.document, 'bar'));

keypress()

Fires a keypress 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) and use accelKey instead which will work regardless of which operating system your test is executing on.

boolean keypress(
  in Elem element,
  in string keycode,
  in object modifiers
); 
Parameters
element
An element to target the keypress at
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 key strokes at element foo:
controller.keypress(new elementslib.ID(controller.window.document, 'foo'), 'VK_ESCAPE', {});

// Fire a simple key stroke at element foo using the control/command and shift keys
controller.keypress(new elementslib.ID(controller.window.document, 'foo'), '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 Elem element,
  in int button,
  [in int left],
  [in int top]
); 
Parameters
element
An element to target
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
controller.mouseDown(new elementslib.ID(controller.window.document, 'foo'));

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 Elem element,
  in int button,
  [in int left],
  [in int top]
); 
Parameters
element
An element to target
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
controller.mouseOut(new elementslib.ID(controller.window.document, 'foo'));

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 inititating the mouseOver

boolean mouseOver(
  in Elem element,
  in int button,
  [in int left],
  [in int top]
); 
Parameters
element
An element to target
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
controller.mouseOver(new elementslib.ID(controller.window.document, 'foo'));

mouseUp()

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

boolean mouseUp(
  in Elem element,
  in int button,
  [in int left],
  [in int top]
); 
Parameters
element
An element to target
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
controller.mouseUp(new elementslib.ID(controller.window.document, 'foo'));

radio()

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

boolean radio(
  in Elem element,
); 
Parameters
element
An element to select
Return value

true if the action succeeds, otherwise false.

Example
controller.radio(new elementslib.ID(controller.window.document, 'foo'));

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 Elem element,
  in int left,
  in int top
); 
Parameters
element
An element to click on
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
controller.rightClick(new elementslib.ID(controller.window.document, 'foo'));
// Or specify coordinates
controller.rightClick(new elementslib.ID(controller.window.document, 'foo'), 20, 10);

select()

Handles selecting an option from a menu list or an HTML select element. The "element" corresponds to the list. There are multiple ways to select from such a list, either by "index", "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 Elem element,
  in int index,
  in string label,
  in string value
); 
Parameters
element
An element to click on
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
controller.select(new elementslib.ID(controller.window.document, 'foo'), 2);

// Select using the label of the given element
controller.select(new elementslib.ID(controller.window.document, 'foo'), null, 'bar');

startUserShutdown()

Creates a timeout window during which the browser is allowed to be restarted or shutdown, for example by selecting 'Quit' from the 'File' menu.  If startUserShutdown() is called and the test does not restart or shutdown the browser within the specified timeout, the test will fail.  The browser must also be shutdown within the same test that called startUserShutdown().  Note: This is only available in Mozmill 1.4.2 and later.

Parameters
timeout
The number of milliseconds during which the browser is allowed to be restarted or shutdown.
restart
True if a restart is to be expected, false if a shutdown is to be expected.
Return value

None

Example
controller.startUserShutdown(2000, false); 
controller.click(new elementslib.Elem(controller.menus["file-menu"].menu_FileQuitItem));

type()

Types a string of text at the given element.

boolean type(
  in Elem element,
  in string text
); 
Parameters
element
An element to type at
text
The text to type
Return value

true if the action succeeds, otherwise false.

Example
controller.type(new elementslib.ID(controller.window.document, 'foo'), 'some text to type');

Wait methods

sleep()

Causes the test to pause its execution until "timeout" milliseconds have passed. This is the least granular of the wait methods and is NOT encouraged to be used. It is only included here because it is sometimes useful when debugging. You should use other wait methods in your tests in order to ensure your tests are more deterministic.

void sleep(
  in int timeout
); 
Parameters
timeout
Number of milliseconds to pause.
Return value

None

Example
// Sleeps one second
controller.sleep(1000);

waitFor()

Waits until the callback handler returns true. The handler gets called every "interval" milliseconds, and if "timeout" milliseconds have passed without the handler return true, it gives up and causes the test to fail. If you use the defaults, then it will check the return value once every 100ms and will throw an error after 30 seconds have passed.

void waitFor(
  in func callback,
  in string message,
  in int timeout,
  in int interval,
  in object this
); 
Parameters
callback
A callback function or closure which executes code inside the scope of the test and has to return true/false.
message
Message to use for the raised exception when return value isn't true (optional)
timeout
Total time in milliseconds to wait (optional, default: 5000ms)
interval
How often to check if the element has appeared (optional, default: 100)
this
Reference to the outer scope's this object. It's needed when this has to be used inside the callback function.

None

Example
// Accept the default settings
var value = { message: "g" };
controller.waitFor(function () { 
  return value.message === 'foo'; 
}, "This is expected to fail.");

// Wait until the location bar is visible, check every 100ms, and if it isn't true by 1000ms then throw an error.
var locationBar = new elementslib.ID('urlbar');
controller.waitFor(function () { 
  return locationBar.getNode().visibility === true;
}, "Location bar should be visible", 1000, 100);

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 30 seconds pass without the element appearing.

void waitForElement(
  in Elem element,
  in int timeout,
  in int interval
); 
Parameters
element
Element to wait for
timeout
Total time in milliseconds to wait
interval
How often to check if the element has appeared
Return value

None

Example
// Typical usage - accept defaults.  See waitForEval() to see non-default operation
controller.waitForElement(new elementslib.ID(controller.window.document, 'foo'));

waitForEval()

Waits for the JavaScript "expression" to be true. It checks to see if the expression is true once every "interval" milliseconds, and if "timeout" milliseconds have passed without the expression becoming true, it gives up and causes the test to fail. If you use the defaults, then it will check the expression once every 100ms and will throw an error after 30 seconds have passed. The subject parameter which is passed as last argument will be substituted with the "subject" string inside the expression string. This method is deprecated, use the waitFor method instead.

void waitForEval(
  in string expression,
  in int timeout,
  in int interval,
  in object subject
); 
Parameters
expression
Expression to evaluate, optionally containing the word "subject" for substitution
timeout
Total time in milliseconds to wait
interval
How often to check if the element has appeared
subject
Object to substitute for the value of "subject" in the expression
Return value

None

Example
// Accept the default settings
controller.waitForEval('foo==true');

// Wait until the location bar is visible, check every 100ms, and if it isn't true by 1000ms then throw an error.
let locationBar = new elementslib.ID('urlbar')
controller.waitForEval('subject.visibility == true', 1000, 100, locationBar.getNode());

waitForImage()

Waits for the image represented by "element" to appear in the user interface. It checks for the image 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 image every 100ms and will throw an error if 30 seconds pass without the image appearing.

void waitForElement(
  in Elem element,
  in int timeout,
  in int interval
); 
Parameters
element
Element to wait for
timeout
Total time in milliseconds to wait
interval
How often to check if the element has appeared
Return value

None

Example
// Typical usage - accept defaults.  See waitForEval() to see non-default operation
controller.waitForImage(new elementslib.ID(controller.window.document, 'foo'));

waitForPageLoad()

This is a browser specific method. It blocks the test until the current page completes loading.

void waitForPageLoad(
  in DOMDocument document,
  in int timeout,
  in int interval
); 
Parameters
document
Document to wait on, if not specified, uses the current document.
timeout
Total time in milliseconds to wait
interval
How often to check if the element has appeared
Return value

None

Example
// Waits for the current tab to load, timing out after 3 seconds have passed and
// it will check if the page is loaded every 100ms
controller.waitForPageLoad();

// Waits for the current page to load and will timeout once the given number of
// milliseconds have passed. For example, this times out after 1 second:
controller.waitForPageLoad(1000);

// The third version allows you to specify each parameter.  This allows you to specify
// what document is loading, the time that it must load within and how often to check that
// loading is complete.  For example, this waits for the page in tab 3 to load, and will
// check whether that page is loaded every 500ms, and will timeout after 2s have passed.
controller.waitForPageLoad(controller.tabs.getTab(3), 2000, 500);

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.

void waitThenClick(
  in Elem element,
  in int timeout,
  in int interval
); 
Parameters
element
Element to wait for
timeout
Total time in milliseconds to wait
interval
How often to check if the element has appeared
Return value

None

Example
// Typical usage - accept defaults.  See waitForEval() to see non-default operation
controller.waitThenClick(new elementslib.ID(controller.window.document, 'foo'));

Assertion Methods

assert()

Asserts that the callback function returns true.

boolean assert(
  in func callback,
  in string message,
  in object this
 ); 
Parameters
callback
A callback function or closure which evaluates an expression inside the scope of the test and has to return true/false.
message
Message to use for the raised exception when return value isn't true (optional)
this
Reference to the outer scope's this object. It's needed when this has to be used inside the callback function (optional)
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// Run specific javascript that evaluates to a non-zero value
controller.assert(function() {
  return 2 > 1;
});

// Check if an array has the value as element (This will raise an exception with the given message)
var value = 5;
var items = [1, 2, 3, 4];
controller.assert(function() {
  return items.indexOf(value) !== -1; 
}, "The array has '5' as element.");

assertChecked()

Asserts that the passed-in checkbox "element", is checked. It will cause a failure if the checkbox is not checked. Returns true if the box is checked, false if not.

boolean assertChecked(
  in Elem element
); 
Parameters
element
Element to check
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertChecked(new elementslib.ID(controller.window.document, 'foo'));

assertDOMProperty()

If the value parameter is not specified, asserts that the given DOM attribute exists for the given element. If the value parameter is specified, asserts that the given DOM attribute on the given element is the specified value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. Note: This method is only available in Mozmill 1.4.2 and later.

boolean assertDOMProperty(
  in Elem element
  in string attribute,
  [in string value]
); 
Parameters
element
Element to check
attribute
The DOM attribute to check
value
The value that the DOM attribute is expected to contain
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// True if the DOM attribute called 'class' exists
controller.assertDOMProperty(new elementslib.ID(controller.window.document, 'foo'), 'class');
// True if the DOM attribute called 'class' has a value of 'bar'
controller.assertDOMProperty(new elementslib.ID(controller.window.document, 'foo'), 'class', 'bar');

assertImageLoaded()

Asserts that the image refrerenced by "element" is loaded. It will cause a failure if the image is not loaded. Returns true if the image is loaded, false if not.

boolean assertImageLoaded(
  in Elem element
); 
Parameters
element
Element to check
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertImageLoaded(new elementslib.ID(controller.window.document, 'foo'));

assertJS()

Asserts that JavaScript expression evaluates to true or to a non-zero value. You can optionally pass in an object for the "subject" parameter and that object will be substituted for the string "subject" in the expression.

boolean assertJS(
  in string expression,
  in object subject
); 
Parameters
expression
An expression of JavaScript code to evaluate
subject
An object to use in the expression, optional argument.
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// Run specific javascript that evaluates to a non-zero value
controller.assertJS('2 > 1');

// Check if an array has three elements (this one would return false and cause a failure)
var items = ['1', '2', '3', '4'];
controller.assertJS('subject.length == 3', items);

assertJSProperty()

If the value parameter is not specified, asserts that the given Javascript object property exists for the given element. If the value parameter is specified, asserts that the given Javascript object property on the given element is the specified value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. Note: This method is only available in Mozmill 1.4.2 and later.

boolean assertJSProperty(
  in Elem element
  in string attribute,
  [in string value]
); 
Parameters
element
Element to check
attribute
The Javascript object property to check
value
The value that the Javascript object property is expected to contain
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// True if the Javascript object property called 'class' exists
controller.assertJSProperty(new elementslib.ID(controller.window.document, 'foo'), 'class');
// True if the Javascript object property called 'class' has a value of 'bar'
controller.assertJSProperty(new elementslib.ID(controller.window.document, 'foo'), 'class', 'bar');

assertNode()

Asserts that the given element exists. If the element does not exist, this returns false and marks a failure in the test. Note that this tests existence, not visibility. If the element is not visible, but it does exist in the DOM, this will return true.

boolean assertNode(
  in Elem element
); 
Parameters
element
Element to check
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertNode(new elementslib.ID(controller.window.document, 'foo'));

assertNodeNotExist()

Asserts that the given element DOES NOT exist. If the element does not exist, this returns true and if it does exist, it returns false and marks a failure in the test. Note that like assertNode this tests existence, not visibility.

boolean assertNodeNotExist(
  in Elem element
); 
Parameters
element
Element to check
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertNodeNotExist(new elementslib.ID(controller.window.document, 'foo'));

assertNotChecked()

Asserts that the given element is not in a "checked" state. So, if the element is unchecked, this returns true, otherwise false.

boolean assertNotChecked(
  in Elem element
); 
Parameters
element
Element to check
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertNotChecked(new elementslib.ID(controller.window.document, 'foo'));

assertNotDOMProperty()

If the value parameter is not specified, asserts that the given DOM attribute does not exist on the given element. If the value parameter is specified, asserts that the given DOM attribute for the given element is not equal to the given value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. This is very useful for asserting that various controls are not disabled, options are not selected etc. Note: This method is only available in Mozmill 1.4.2 and later.

boolean assertNotDOMProperty(
  in Elem element
  in string attribute
  [in string value]
); 
Parameters
element
Element to check
attribute
The DOM attribute to check
value
The value the DOM attribute is expected to not contain
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// True if there is no DOM attribute called 'disabled'
controller.assertNotDOMProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'disabled');
// True if the DOM attribute called 'name' doesn't have a value of 'bar'
controller.assertNotDOMProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'name', 'bar');

assertNotJSProperty()

If the value parameter is not specified, asserts that the given Javascript object property does not exist for the given element. If the value parameter is specified, asserts that the given Javascript object property for the given element is not equal to the given value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. This is very useful for asserting that various controls are not disabled, options are not selected etc. Note: This method is only available in Mozmill 1.4.2 and later.

boolean assertNotJSProperty(
  in Elem element
  in string attribute
  [in string value]
); 
Parameters
element
Element to check
attribute
The Javascript object property to check
value
The value the Javascript object property is expected to not contain
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// True if there is no Javascript object property called 'disabled'
controller.assertNotJSProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'disabled');
// True if the Javascript object property called 'name' doesn't have a value of 'bar'
controller.assertNotJSProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'name', 'bar');

assertSelected()

Asserts that the given drop-down (or option) element has the given value selected. It uses the specified value of the selected option to verify this, you will have to usually look at the DOM Inspector to determine what this value should be.

boolean assertSelection(
  in Elem element,
  in string value
); 
Parameters
element
Element to check
value
The value of the option you expect to be selected
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertSelected(new elementslib.ID(controller.window.document, 'foo'), 'optionvalue');

assertText()

Asserts that the given element contains a given string of text. This is typically used with textboxes.

boolean assertText(
  in Elem element,
  in string text
); 
Parameters
element
Element to check
text
The text the element should contain
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
// Simple use for text boxes.
controller.assertText(new elementslib.ID(controller.window.document, 'foo'), 'bar');

// If you had a XUL Description field of the form: <description id="mydesc">Some text here</description>
// Then you could use this statement to verify the "Some text here" string:
controller.assertText(new elementslib.ID(controller.window.document, 'mydesc'), 'Some text here');

assertValue()

Asserts that the element contains the given value. This is typically used with input controls, like form elements. A primary use case is to shortcut when looking for the "value" attribute and ascertaining that it contains a certain value. You could of course just use the assertDOMProperty method.

boolean assertValue(
  in Elem element,
  in string value
); 
Parameters
element
Element to check
value
The value of the element that you expect
Return value

Boolean - returns true if assertion holds true, returns false if assertion is not true

Example
controller.assertValue(new elementslib.ID(controller.window.document, 'foo'), 'bar');

Browser Specific Methods

open()

Opens a given URI in the browser.

void open(
  in string uri
); 
Parameters
uri
URI to open
Return value

None

Example
controller.open('http://www.mozilla.org');

goBack()

Causes the browser to go back one step into the history for this page.

boolean goBack(); 
Parameters

None

Return value

None

Example
controller.goBack();

goForward()

Causes the browser to go forward one step into the back/forward history for this page.

void goForward(); 
Parameters

None

Return value

None

Example
controller.goForward();

refresh()

Causes the browser to refresh the current page.

void refresh(); 
Parameters

None

Return value

None

Example
controller.refresh();

tabs.getTab()

Gets a reference to the document rendered by the tab corresponding to the given index.

DOMDocument tabs.getTab(); 
Parameters
index
The zero-based index number for the tab in question.
Return value

DOMDocument

Example
let doc = controller.tabs.getTab(0);
let fooelement = doc.getElementById('foo');

tabs.selectTabIndex()

Switches to a tab based on the given zero-based index. This is the equivalent of clicking on the tab in the tab bar with the mouse to "focus" a tab.

void tabs.selectTabIndex(); 
Parameters
index
The zero-based index number for the tab in question.
Return value

None

Example
controller.tabs.selectTabIndex(0);

 

Revision Source

<p><strong>This page is currently under development and is only relevant to Mozmill 2.0 and later.</strong></p>
<p>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 <em>will not</em> be available on, for example, a 'button' element.</p>
<p>The wrapper objects are set up as a hierarchy which can be extended and customized as you see fit (see <a href="/en/Mozmill/Mozmill_Element_Object/Extending_Element_Hierarchy" title="Extending the Mozmill Element Hierarchy">extending the mozmill element hierarchy</a>) . 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.</p>
<h2>MozMillElement Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>boolean <a href="#click.28.29">click</a>(in Elem element, in int left, int top);</code></td> </tr> <tr> <td><code>boolean <a href="#doubleClick.28.29">doubleClick</a>(in Elem element, in int left, in int top);</code></td> </tr> <tr> <td><code>boolean <a href="#keypress.28.29">keypress</a>(in Elem element, in string keycode, in object modifiers);</code></td> </tr> <tr> <td><code>boolean <a href="#mouseDown.28.29">mouseDown</a>(in Elem element, in int button, in int left, in int top);</code></td> </tr> <tr> <td><code>boolean <a href="#mouseOut.28.29">mouseOut</a>(in Elem element</code><code>, in int button, in int left, in int top</code><code>);</code></td> </tr> <tr> <td><code>boolean <a href="#mouseOver.28.29">mouseOver</a>(in Elem element</code><code>, in int button, in int left, in int top</code><code>);</code></td> </tr> <tr> <td><code>boolean <a href="#mouseUp.28.29">mouseUp</a>(in Elem element</code><code>, in int button, in int left, in int top</code><code>);</code></td> </tr> <tr> <td><code>boolean <a href="#rightClick.28.29">rightClick</a>(in Elem element, in int left, in int top);</code></td> </tr> <tr> <td><code>boolean <a href="#type.28.29">type</a>(in Elem element, in string text);</code></td> </tr> <tr> <td><code>void <a href="#waitForElement.28.29">waitForElement</a>(in Elem element, in int timeout, in int interval);</code></td> </tr> <tr> <td><code>void <a href="#waitThenClick.28.29">waitThenClick</a>(in Elem element, in int timeout, in int interval);</code></td> </tr> </tbody>
</table>
<h2>Attributes</h2>
<table class="standard-table"> <thead> <tr> <th scope="col">Attribute</th> <th scope="col">Type</th> <th scope="col">Description</th> </tr> </thead> <tbody> <tr> <td><code><a href="#menus">menus</a></code></td> <td>{{ interface("Node") }}</td> <td>A set of attributes to access the menus and menu items as elements. Click <a href="#menus">here for information</a></td> </tr> <tr> <td><code>tabs.activeTab</code></td> <td>DOMDocument</td> <td>Returns the document that is rendered by the current active tab in the browser</td> </tr> <tr> <td><code>tabs.activeTabIndex</code></td> <td>int</td> <td>Returns the index number of the currently active tab. It is a browser specific method</td> </tr> </tbody>
</table>
<h2>Interaction Methods</h2>
<h3 name="check.28.29">check()</h3>
<p>Fires a click at the given checkbox element to ensure it is either checked or not.</p>
<pre>boolean check(
  in Elem element,
  in boolean state
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to attempt to check (should be a checkbox or it will fail).</dd> <dt><code>state</code></dt> <dd>Pass true to ensure the element is checked, false to ensure it is unchecked. Defaults to false</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.check(new elementslib.ID(controller.window.document, 'foo'), true);
</pre>
<h3 name="click.28.29">click()</h3>
<p>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).</p>
<pre>boolean click(
  in Elem element,
  in int left,
  in int top
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to click on</dd> <dt><code>left</code></dt> <dd>Left coordinate for click (optional, defaults to 0)</dd> <dt><code>top</code></dt> <dd>Top coordinate for click (optional, defaults to 0)</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.click(new elementslib.ID(controller.window.document, 'foo'));
// Or specify coordinates
controller.click(new elementslib.ID(controller.window.document, 'foo'), 20, 10);
</pre>
<h3 name="doubleClick.28.29">doubleClick()</h3>
<p>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).</p>
<pre>boolean doubleClick(
  in Elem element,
  in int left,
  in int top
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to click on</dd> <dt><code>left</code></dt> <dd>Left coordinate for click (optional, defaults to 0)</dd> <dt><code>top</code></dt> <dd>Top coordinate for click (optional, defaults to 0)</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.doubleClick(new elementslib.ID(controller.window.document, 'foo'));
// Or specify coordinates
controller.doubleClick(new elementslib.ID(controller.window.document, 'foo'), 20, 10);
</pre>
<h3 name="dragDropElemToElem.28.29">dragDropElemToElem()</h3>
<p>Drags the element specified by elementStart to the x,y coordinates of the element specified by elementFinish. Currently only works in content space (i.e. on a web page).</p>
<pre>boolean dragDropElemToElem(
  in Elem elementStart,
  in Elem elementFinish
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>elementStart</code></dt> <dd>Element to start dragging</dd> <dt><code>elementFinish</code></dt> <dd>Target element to drag to</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.dragDropElemToElem(new elementslib.ID(controller.window.document, 'foo'),
                              new elementslib.ID(controller.window.document, 'bar'));
</pre>
<h3 name="keypress.28.29">keypress()</h3>
<p>Fires a keypress 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) and use accelKey instead which will work regardless of which operating system your test is executing on.</p>
<pre>boolean keypress(
  in Elem element,
  in string keycode,
  in object modifiers
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to target the keypress at</dd> <dt><code>keycode</code></dt> <dd>The key code. Either a literal keycode like 'b' or an <a href="/en/XUL_Tutorial/Keyboard_Shortcuts" title="en/XUL_Tutorial/Keyboard_Shortcuts">enum key code</a> like 'VK_ESCAPE'</dd> <dt><code>modifiers</code></dt> <dd>Object of modifiers for this keypress.</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">// Fire an escape key strokes at element foo:
controller.keypress(new elementslib.ID(controller.window.document, 'foo'), 'VK_ESCAPE', {});

// Fire a simple key stroke at element foo using the control/command and shift keys
controller.keypress(new elementslib.ID(controller.window.document, 'foo'), 'b',
                    {shiftKey: true, accelKey: true});
</pre>
<h3 name="mouseDown.28.29">mouseDown()</h3>
<p>Simulates the left button being depressed on the mouse when the mouse is over the given element.</p>
<pre>boolean mouseDown(
  in Elem element,
  in int button,
  [in int left],
  [in int top]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to target</dd> <dt><code>button</code></dt> <dd>The id of the button to press (0 - left, 1 - middle, 2 - right)</dd> <dt><code>left</code></dt> <dd>The relative horizontal coordinate inside the target element to click</dd> <dt><code>top</code></dt> <dd>The relative vertical coordinate inside the target element to click</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.mouseDown(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="mouseOut.28.29">mouseOut()</h3>
<p>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.</p>
<pre>boolean mouseOut(
  in Elem element,
  in int button,
  [in int left],
  [in int top]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to target</dd> <dt><code>button</code></dt> <dd>The id of the button to press (0 - left, 1 - middle, 2 - right)</dd> <dt><code>left</code></dt> <dd>The relative horizontal coordinate inside the target element</dd> <dt><code>top</code></dt> <dd>The relative vertical coordinate inside the target element</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.mouseOut(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="mouseOver.28.29">mouseOver()</h3>
<p>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 inititating the mouseOver</p>
<pre>boolean mouseOver(
  in Elem element,
  in int button,
  [in int left],
  [in int top]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to target</dd> <dt><code>button</code></dt> <dd>The id of the button to press (0 - left, 1 - middle, 2 - right)</dd> <dt><code>left</code></dt> <dd>The relative horizontal coordinate inside the target element</dd> <dt><code>top</code></dt> <dd>The relative vertical coordinate inside the target element</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.mouseOver(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="mouseUp.28.29">mouseUp()</h3>
<p>Simulates the left button being released on the mouse when the mouse is over the given element.</p>
<pre>boolean mouseUp(
  in Elem element,
  in int button,
  [in int left],
  [in int top]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to target</dd> <dt><code>button</code></dt> <dd>The id of the button to press (0 - left, 1 - middle, 2 - right)</dd> <dt><code>left</code></dt> <dd>The relative horizontal coordinate inside the target element</dd> <dt><code>top</code></dt> <dd>The relative vertical coordinate inside the target element</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.mouseUp(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="radio.28.29">radio()</h3>
<p>Selects the given radio button by firing a click at it.</p>
<pre>boolean radio(
  in Elem element,
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to select</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.radio(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="rightClick.28.29">rightClick()</h3>
<p>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).</p>
<pre>boolean rightClick(
  in Elem element,
  in int left,
  in int top
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to click on</dd> <dt><code>left</code></dt> <dd>Left coordinate for click (optional, defaults to 0)</dd> <dt><code>top</code></dt> <dd>Top coordinate for click (optional, defaults to 0)</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.rightClick(new elementslib.ID(controller.window.document, 'foo'));
// Or specify coordinates
controller.rightClick(new elementslib.ID(controller.window.document, 'foo'), 20, 10);
</pre>
<h3 name="select.28.29">select()</h3>
<p>Handles selecting an option from a menu list or an HTML select element. The "element" corresponds to the list. There are multiple ways to select from such a list, either by "index", "label", or by the "value" associated with that option.</p>
<ul> <li>index - to use an index, give it a valid index &gt;=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.</li> <li>label - to use label, supply the label. If you do not wish to use an option name, then pass 'null' in this field.</li> <li>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'.</li>
</ul>
<pre>boolean select(
  in Elem element,
  in int index,
  in string label,
  in string value
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to click on</dd> <dt><code>index</code></dt> <dd>index of item in drop down list. Use <code>null</code> if you do not wish to specify an index. -1 will reset the selection.</dd> <dt><code>label</code></dt> <dd>Label of the option you wish to select, if you do not wish to use it pass <code>null</code></dd> <dt><code>value</code></dt> <dd>Value of the option you wish to select, if you do not wish to use this field either leave it off or pass <code>null</code></dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">// Select only using the index
controller.select(new elementslib.ID(controller.window.document, 'foo'), 2);

// Select using the label of the given element
controller.select(new elementslib.ID(controller.window.document, 'foo'), null, 'bar');
</pre>
<h3 name="startUserShutdown.28.29">startUserShutdown()</h3>
<p>Creates a timeout window during which the browser is allowed to be restarted or shutdown, for example by selecting 'Quit' from the 'File' menu.  If startUserShutdown() is called and the test does not restart or shutdown the browser within the specified timeout, the test will fail.  The browser must also be shutdown within the same test that called startUserShutdown().  <span style="font-weight: bold;">Note: This is only available in Mozmill 1.4.2 and later.</span></p>
<h6>Parameters</h6>
<dl> <dt><code>timeout</code></dt> <dd><code>The number of milliseconds during which the browser is allowed to be restarted or shutdown</code>.</dd> <dt><code>restart</code></dt> <dd><code>True if a restart is to be expected, false if a shutdown is to be expected.</code></dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">controller.startUserShutdown(2000, false); 
controller.click(new elementslib.Elem(controller.menus["file-menu"].menu_FileQuitItem));
</pre>
<h3 name="type.28.29">type()</h3>
<p>Types a string of text at the given element.</p>
<pre>boolean type(
  in Elem element,
  in string text
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>An element to type at</dd> <dt><code>text</code></dt> <dd>The text to type</dd>
</dl>
<h6>Return value</h6>
<p><code>true</code> if the action succeeds, otherwise <code>false</code>.</p>
<h6>Example</h6>
<pre class="deki-transform">controller.type(new elementslib.ID(controller.window.document, 'foo'), 'some text to type');
</pre>
<h2 name="waitmethods">Wait methods</h2>
<h3 name="sleep.28.29">sleep()</h3>
<p>Causes the test to pause its execution until "timeout" milliseconds have passed. This is the least granular of the wait methods and is NOT encouraged to be used. It is only included here because it is sometimes useful when debugging. You should use other wait methods in your tests in order to ensure your tests are more deterministic.</p>
<pre>void sleep(
  in int timeout
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>timeout</code></dt> <dd>Number of milliseconds to pause.</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Sleeps one second
controller.sleep(1000);
</pre>
<h3 name="waitFor.28.29">waitFor()</h3>
<p>Waits until the callback handler returns true. The handler gets called every "interval" milliseconds, and if "timeout" milliseconds have passed without the handler return true, it gives up and causes the test to fail. If you use the defaults, then it will check the return value once every 100ms and will throw an error after 30 seconds have passed.</p>
<pre>void waitFor(
  in func callback,
  in string message,
  in int timeout,
  in int interval,
  in object this
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>callback</code></dt> <dd>A callback function or closure which executes code inside the scope of the test and has to return true/false.</dd> <dt> </dt><dt><code>message</code></dt> <dd>Message to use for the raised exception when return value isn't true (optional)</dd>
</dl>
<dl> <dt><code>timeout</code></dt> <dd>Total time in milliseconds to wait (optional, default: 5000ms)</dd> <dt><code>interval</code></dt> <dd>How often to check if the element has appeared (optional, default: 100)</dd> <dt><code>this</code></dt> <dd>Reference to the outer scope's <em>this</em> object. It's needed when <em>this</em> has to be used inside the callback function.</dd>
</dl>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Accept the default settings
var value = { message: "g" };
controller.waitFor(function () { 
  return value.message === 'foo'; 
}, "This is expected to fail.");

// Wait until the location bar is visible, check every 100ms, and if it isn't true by 1000ms then throw an error.
var locationBar = new elementslib.ID('urlbar');
controller.waitFor(function () { 
  return locationBar.getNode().visibility === true;
}, "Location bar should be visible", 1000, 100);
</pre>
<h3 name="waitForElement.28.29">waitForElement()</h3>
<p>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 30 seconds pass without the element appearing.</p>
<pre>void waitForElement(
  in Elem element,
  in int timeout,
  in int interval
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to wait for</dd> <dt><code>timeout</code></dt> <dd>Total time in milliseconds to wait</dd> <dt><code>interval</code></dt> <dd>How often to check if the element has appeared</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Typical usage - accept defaults.  See waitForEval() to see non-default operation
controller.waitForElement(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="waitForEval.28.29">waitForEval()</h3>
<p>Waits for the JavaScript "expression" to be true. It checks to see if the expression is true once every "interval" milliseconds, and if "timeout" milliseconds have passed without the expression becoming true, it gives up and causes the test to fail. If you use the defaults, then it will check the expression once every 100ms and will throw an error after 30 seconds have passed. The subject parameter which is passed as last argument will be substituted with the "subject" string inside the expression string. This method is deprecated, use the <code>waitFor</code> method instead.</p>
<pre>void waitForEval(
  in string expression,
  in int timeout,
  in int interval,
  in object subject
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>expression</code></dt> <dd>Expression to evaluate, optionally containing the word "subject" for substitution</dd> <dt><code>timeout</code></dt> <dd>Total time in milliseconds to wait</dd> <dt><code>interval</code></dt> <dd>How often to check if the element has appeared</dd> <dt><code>subject</code></dt> <dd>Object to substitute for the value of "subject" in the expression</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Accept the default settings
controller.waitForEval('foo==true');

// Wait until the location bar is visible, check every 100ms, and if it isn't true by 1000ms then throw an error.
let locationBar = new elementslib.ID('urlbar')
controller.waitForEval('subject.visibility == true', 1000, 100, locationBar.getNode());
</pre>
<h3 name="waitForImage.28.29">waitForImage()</h3>
<p>Waits for the image represented by "element" to appear in the user interface. It checks for the image 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 image every 100ms and will throw an error if 30 seconds pass without the image appearing.</p>
<pre>void waitForElement(
  in Elem element,
  in int timeout,
  in int interval
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to wait for</dd> <dt><code>timeout</code></dt> <dd>Total time in milliseconds to wait</dd> <dt><code>interval</code></dt> <dd>How often to check if the element has appeared</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Typical usage - accept defaults.  See waitForEval() to see non-default operation
controller.waitForImage(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="waitForPageLoad.28.29">waitForPageLoad()</h3>
<p>This is a browser specific method. It blocks the test until the current page completes loading.</p>
<pre>void waitForPageLoad(
  in DOMDocument document,
  in int timeout,
  in int interval
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>document</code></dt> <dd>Document to wait on, if not specified, uses the current document.</dd> <dt><code>timeout</code></dt> <dd>Total time in milliseconds to wait</dd> <dt><code>interval</code></dt> <dd>How often to check if the element has appeared</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Waits for the current tab to load, timing out after 3 seconds have passed and
// it will check if the page is loaded every 100ms
controller.waitForPageLoad();

// Waits for the current page to load and will timeout once the given number of
// milliseconds have passed. For example, this times out after 1 second:
controller.waitForPageLoad(1000);

// The third version allows you to specify each parameter.  This allows you to specify
// what document is loading, the time that it must load within and how often to check that
// loading is complete.  For example, this waits for the page in tab 3 to load, and will
// check whether that page is loaded every 500ms, and will timeout after 2s have passed.
controller.waitForPageLoad(controller<span><span>.tabs</span></span>.getTab(3), 2000, 500);
</pre>
<h3 name="waitThenClick.28.29">waitThenClick()</h3>
<p>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.</p>
<pre>void waitThenClick(
  in Elem element,
  in int timeout,
  in int interval
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to wait for</dd> <dt><code>timeout</code></dt> <dd>Total time in milliseconds to wait</dd> <dt><code>interval</code></dt> <dd>How often to check if the element has appeared</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">// Typical usage - accept defaults.  See waitForEval() to see non-default operation
controller.waitThenClick(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h2>Assertion Methods</h2>
<h3 name="assert.28.29">assert()</h3>
<p>Asserts that the callback function returns true.</p>
<pre>boolean assert(
  in func callback,
  in string message,
  in object this
 ); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>callback</code></dt> <dd>A callback function or closure which evaluates an expression inside the scope of the test and has to return true/false.</dd> <dt><code>message</code></dt> <dd>Message to use for the raised exception when return value isn't true (optional)</dd> <dt><code>this</code></dt> <dd>Reference to the outer scope's <em>this</em> object. It's needed when <em>this</em> has to be used inside the callback function (optional)</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// Run specific javascript that evaluates to a non-zero value
controller.assert(function() {
  return 2 &gt; 1;
});

// Check if an array has the value as element (This will raise an exception with the given message)
var value = 5;
var items = [1, 2, 3, 4];
controller.assert(function() {
  return items.indexOf(value) !== -1; 
}, "The array has '5' as element.");
</pre>
<h3 name="assertChecked.28.29">assertChecked()</h3>
<p>Asserts that the passed-in checkbox "element", is checked. It will cause a failure if the checkbox is not checked. Returns true if the box is checked, false if not.</p>
<pre>boolean assertChecked(
  in Elem element
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertChecked(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="assertDOMProperty.28.29">assertDOMProperty()</h3>
<p>If the value parameter is not specified, asserts that the given DOM attribute exists for the given element. If the value parameter is specified, asserts that the given DOM attribute on the given element is the specified value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. <strong>Note: This method is only available in Mozmill 1.4.2 and later.</strong></p>
<pre>boolean assertDOMProperty(
  in Elem element
  in string attribute,
  [in string value]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>attribute</code></dt> <dd>The DOM attribute to check</dd> <dt><code>value</code></dt> <dd>The value that the DOM attribute is expected to contain</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// True if the DOM attribute called 'class' exists
controller.assertDOMProperty(new elementslib.ID(controller.window.document, 'foo'), 'class');
// True if the DOM attribute called 'class' has a value of 'bar'
controller.assertDOMProperty(new elementslib.ID(controller.window.document, 'foo'), 'class', 'bar');
</pre>
<h3 name="assertImageLoaded.28.29">assertImageLoaded()</h3>
<p>Asserts that the image refrerenced by "element" is loaded. It will cause a failure if the image is not loaded. Returns true if the image is loaded, false if not.</p>
<pre>boolean assertImageLoaded(
  in Elem element
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertImageLoaded(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="assertJS.28.29">assertJS()</h3>
<p>Asserts that JavaScript expression evaluates to true or to a non-zero value. You can optionally pass in an object for the "subject" parameter and that object will be substituted for the string "subject" in the expression.</p>
<pre>boolean assertJS(
  in string expression,
  in object subject
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>expression</code></dt> <dd>An expression of JavaScript code to evaluate</dd> <dt><code>subject</code></dt> <dd>An object to use in the expression, optional argument.</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// Run specific javascript that evaluates to a non-zero value
controller.assertJS('2 &gt; 1');

// Check if an array has three elements (this one would return false and cause a failure)
var items = ['1', '2', '3', '4'];
controller.assertJS('subject.length == 3', items);
</pre>
<h3 name="assertJSProperty.28.29">assertJSProperty()</h3>
<p>If the value parameter is not specified, asserts that the given Javascript object property exists for the given element. If the value parameter is specified, asserts that the given Javascript object property on the given element is the specified value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. <strong>Note: This method is only available in Mozmill 1.4.2 and later.</strong></p>
<pre>boolean assertJSProperty(
  in Elem element
  in string attribute,
  [in string value]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>attribute</code></dt> <dd>The Javascript object property to check</dd> <dt><code>value</code></dt> <dd>The value that the Javascript object property is expected to contain</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// True if the Javascript object property called 'class' exists
controller.assertJSProperty(new elementslib.ID(controller.window.document, 'foo'), 'class');
// True if the Javascript object property called 'class' has a value of 'bar'
controller.assertJSProperty(new elementslib.ID(controller.window.document, 'foo'), 'class', 'bar');
</pre>
<h3 name="assertNode.28.29">assertNode()</h3>
<p>Asserts that the given element exists. If the element does not exist, this returns false and marks a failure in the test. Note that this tests existence, not visibility. If the element is not visible, but it does exist in the DOM, this will return true.</p>
<pre>boolean assertNode(
  in Elem element
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertNode(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="assertNodeNotExist.28.29">assertNodeNotExist()</h3>
<p>Asserts that the given element DOES NOT exist. If the element does not exist, this returns true and if it does exist, it returns false and marks a failure in the test. Note that like <code>assertNode</code> this tests existence, not visibility.</p>
<pre>boolean assertNodeNotExist(
  in Elem element
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertNodeNotExist(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="assertNotChecked.28.29">assertNotChecked()</h3>
<p>Asserts that the given element is not in a "checked" state. So, if the element is unchecked, this returns true, otherwise false.</p>
<pre>boolean assertNotChecked(
  in Elem element
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertNotChecked(new elementslib.ID(controller.window.document, 'foo'));
</pre>
<h3 name="assertNotDOMProperty.28.29">assertNotDOMProperty()</h3>
<p>If the value parameter is not specified, asserts that the given DOM attribute does not exist on the given element. If the value parameter is specified, asserts that the given DOM attribute for the given element is not equal to the given value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. This is very useful for asserting that various controls are not disabled, options are not selected etc. <strong>Note: This method is only available in Mozmill 1.4.2 and later.</strong></p>
<pre>boolean assertNotDOMProperty(
  in Elem element
  in string attribute
  [in string value]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>attribute</code></dt> <dd>The DOM attribute to check</dd> <dt><code>value</code></dt> <dd>The value the DOM attribute is expected to not contain</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// True if there is no DOM attribute called 'disabled'
controller.assertNotDOMProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'disabled');
// True if the DOM attribute called 'name' doesn't have a value of 'bar'
controller.assertNotDOMProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'name', 'bar');
</pre>
<h3 name="assertNotJSProperty.28.29">assertNotJSProperty()</h3>
<p>If the value parameter is not specified, asserts that the given Javascript object property does not exist for the given element. If the value parameter is specified, asserts that the given Javascript object property for the given element is not equal to the given value. If the assertion passes, it returns true, otherwise, it returns false and marks a failure in the test. This is very useful for asserting that various controls are not disabled, options are not selected etc. <strong>Note: This method is only available in Mozmill 1.4.2 and later.</strong></p>
<pre>boolean assertNotJSProperty(
  in Elem element
  in string attribute
  [in string value]
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>attribute</code></dt> <dd>The Javascript object property to check</dd> <dt><code>value</code></dt> <dd>The value the Javascript object property is expected to not contain</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// True if there is no Javascript object property called 'disabled'
controller.assertNotJSProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'disabled');
// True if the Javascript object property called 'name' doesn't have a value of 'bar'
controller.assertNotJSProperty(new elementslib.ID(controller.window.document, 'fooControl'), 'name', 'bar');
</pre>
<h3 name="assertSelected.28.29">assertSelected()</h3>
<p>Asserts that the given drop-down (or option) element has the given value selected. It uses the specified value of the selected option to verify this, you will have to usually look at the DOM Inspector to determine what this value should be.</p>
<pre>boolean assertSelection(
  in Elem element,
  in string value
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>value</code></dt> <dd>The value of the option you expect to be selected</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertSelected(new elementslib.ID(controller.window.document, 'foo'), 'optionvalue');
</pre>
<h3 name="assertText.28.29">assertText()</h3>
<p>Asserts that the given element contains a given string of text. This is typically used with textboxes.</p>
<pre>boolean assertText(
  in Elem element,
  in string text
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>text</code></dt> <dd>The text the element should contain</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">// Simple use for text boxes.
controller.assertText(new elementslib.ID(controller.window.document, 'foo'), 'bar');

// If you had a XUL Description field of the form: &lt;description id="mydesc"&gt;Some text here&lt;/description&gt;
// Then you could use this statement to verify the "Some text here" string:
controller.assertText(new elementslib.ID(controller.window.document, 'mydesc'), 'Some text here');
</pre>
<h3 name="assertValue.28.29">assertValue()</h3>
<p>Asserts that the element contains the given value. This is typically used with input controls, like form elements. A primary use case is to shortcut when looking for the "value" attribute and ascertaining that it contains a certain value. You could of course just use the <code>assertDOMProperty</code> method.</p>
<pre>boolean assertValue(
  in Elem element,
  in string value
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>element</code></dt> <dd>Element to check</dd> <dt><code>value</code></dt> <dd>The value of the element that you expect</dd>
</dl>
<h6>Return value</h6>
<p>Boolean - returns true if assertion holds true, returns false if assertion is not true</p>
<h6>Example</h6>
<pre class="deki-transform">controller.assertValue(new elementslib.ID(controller.window.document, 'foo'), 'bar');
</pre>
<h2 name="browserSpecificMethods">Browser Specific Methods</h2>
<h3 name="open.28.29">open()</h3>
<p>Opens a given URI in the browser.</p>
<pre>void open(
  in string uri
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>uri</code></dt> <dd>URI to open</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">controller.open('http://www.mozilla.org');
</pre>
<h3 name="goBack.28.29">goBack()</h3>
<p>Causes the browser to go back one step into the history for this page.</p>
<pre>boolean goBack(); 
</pre>
<h6>Parameters</h6>
<p>None</p>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">controller.goBack();
</pre>
<h3 name="goForward.28.29">goForward()</h3>
<p>Causes the browser to go forward one step into the back/forward history for this page.</p>
<pre>void goForward(); 
</pre>
<h6>Parameters</h6>
<p>None</p>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">controller.goForward();
</pre>
<h3 name="refresh.28.29">refresh()</h3>
<p>Causes the browser to refresh the current page.</p>
<pre>void refresh(); 
</pre>
<h6>Parameters</h6>
<p>None</p>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">controller.refresh();
</pre>
<h3 name="tabs.getTab.28.29">tabs.getTab()</h3>
<p>Gets a reference to the document rendered by the tab corresponding to the given index.</p>
<pre>DOMDocument tabs.getTab(); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>index</code></dt> <dd>The zero-based index number for the tab in question.</dd>
</dl>
<h6>Return value</h6>
<p>DOMDocument</p>
<h6>Example</h6>
<pre class="deki-transform">let doc = controller.tabs.getTab(0);
let fooelement = doc.getElementById('foo');
</pre>
<h3 name="tabs.selectTabIndex.28.29">tabs.selectTabIndex()</h3>
<p>Switches to a tab based on the given zero-based index. This is the equivalent of clicking on the tab in the tab bar with the mouse to "focus" a tab.</p>
<pre>void tabs.selectTabIndex(); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>index</code></dt> <dd>The zero-based index number for the tab in question.</dd>
</dl>
<h6>Return value</h6>
<p>None</p>
<h6>Example</h6>
<pre class="deki-transform">controller.tabs.selectTabIndex(0);
</pre>
<p> </p>
Revert to this revision