mozilla

Revision 91895 of Mozmill Element Object

  • Revision slug: Mozmill/Mozmill_Element_Object
  • Revision title: Mozmill Element Object
  • Revision id: 91895
  • Created:
  • Creator: ahal
  • Is current revision? No
  • Comment 4231 words removed

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

Interaction Methods

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

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

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

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

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

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

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>
<br>
<h2>Interaction Methods</h2>
<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="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="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="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="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="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>
Revert to this revision