mozilla
Your Search Results

    Mozmill Element Object

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

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

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

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

    Element Method overview

    All sub-classes of elements have these methods:

    element getNode();
    string getInfo();
    boolean exists();
    boolean click(int left, int top);
    boolean doubleClick(int left, int top);
    boolean rightClick(int left, int top);
    boolean keypress(string keycode, object modifiers);
    boolean mouseDown(int button, int left, int top);
    boolean mouseOut(int button, int left, int top);
    boolean mouseOver(int button, int left, int top);
    boolean mouseUp(int button, int left, int top);
    void waitForElement(int timeout, int interval);
    void waitThenClick(int timeout, int interval);

    CheckBox Method overview

    boolean check(boolean state);

    RadioButton Method overview

    boolean select();

    DropList Method overview

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

    TextBox Method overview

    boolean sendKeys(string text, object modifiers);

     

    getNode()

    Returns the actual wrapped DOM element.

    element getNode();
    
    Return value

    A DOM element

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

    getInfo()

    Returns information about the element.

    string getInfo();
    
    Return value

    A string containing the locatorType and locator of the element

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

    exists()

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

    boolean exists();
    
    Return value

    true if the element exists, otherwise false

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

    click()

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

    boolean click(
      [in int left],
      [in int top]
    );
    
    Parameters
    left
    Left coordinate for click (optional, defaults to 0)
    top
    Top coordinate for click (optional, defaults to 0)
    Return value

    true if the action succeeds, otherwise false

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

    doubleClick()

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

    boolean doubleClick(
      [in int left],
      [in int top]
    );
    
    Parameters
    left
    Left coordinate for click (optional, defaults to 0)
    top
    Top coordinate for click (optional, defaults to 0)
    Return value

    true if the action succeeds, otherwise false

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

    rightClick()

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

    boolean rightClick(
      [in int left],
      [in int top]
    ); 
    
    Parameters
    left
    Left coordinate for click (optional, defaults to 0)
    top
    Top coordinate for click (optional, defaults to 0)
    Return value

    true if the action succeeds, otherwise false

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

    keypress()

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

    boolean keypress(
      in string keycode,
      [in object modifiers]
    ); 
    
    Parameters
    keycode
    The key code, either a literal keycode like 'b' or an enum key code like 'VK_ESCAPE'
    modifiers
    Object of modifiers for this keypress
    Return value

    true if the action succeeds, otherwise false

    Example
    // Fire an escape keystroke at an element:
    var element = findElement.ID(controller.window.document, 'elementID');
    element.keypress('VK_ESCAPE');
    
    // Fire a simple keystroke at an element using the control/command and shift keys
    element.keypress('b', {shiftKey: true, accelKey: true});
    

    mouseDown()

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

    boolean mouseDown(
      in int button,
      [in int left],
      [in int top]
    ); 
    
    Parameters
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element to click
    top
    The relative vertical coordinate inside the target element to click
    Return value

    true if the action succeeds, otherwise false

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

    mouseOut()

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

    boolean mouseOut(
      [in int button],
      [in int left],
      [in int top]
    ); 
    
    Parameters
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element
    top
    The relative vertical coordinate inside the target element
    Return value

    true if the action succeeds, otherwise false

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

    mouseOver()

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

    boolean mouseOver(
      [in int button],
      [in int left],
      [in int top]
    ); 
    
    Parameters
    button
    The id of the button to press (0 - left, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element
    top
    The relative vertical coordinate inside the target element
    Return value

    true if the action succeeds, otherwise false

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

    mouseUp()

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

    boolean mouseUp(
      [in int button],
      [in int left],
      [in int top]
    ); 
    
    Parameters
    button
    The id of the button to press (0 - left/default, 1 - middle, 2 - right)
    left
    The relative horizontal coordinate inside the target element
    top
    The relative vertical coordinate inside the target element
    Return value

    true if the action succeeds, otherwise false

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

    waitForElement()

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

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

    None

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

    waitThenClick()

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

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

    None

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

    check()

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

    boolean check(
      in boolean state
    ); 
    
    Parameters
    state
    Pass true to ensure the element is checked, false to ensure it is unchecked. Defaults to false.
    Return value

    true if the action succeeds, otherwise false

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

    select() - radio

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

    boolean select(); 
    
    Return value

    true if the action succeeds, otherwise false

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

    select() - textbox

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

    • index - to use an index, give it a valid index >=0. If you do not wish to use an index, pass 'null' for this field. Using an index of -1 will reset the current selection.
    • label - to use label, supply the label. If you do not wish to use an option name, then pass 'null' in this field.
    • value - to use the value attribute, supply the valid value in this field. If you choose not to supply a value, you can simply leave it off when not including it or pass in 'null'.
    boolean select(
      in int index,
      in string label,
      in string value
    ); 
    
    Parameters
    index
    index of item in drop down list. Use null if you do not wish to specify an index. -1 will reset the selection.
    label
    Label of the option you wish to select, if you do not wish to use it pass null.
    value
    Value of the option you wish to select, if you do not wish to use this field either leave it off or pass null.
    Return value

    true if the action succeeds, otherwise false

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

    sendKeys()

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

    boolean sendKeys(
      in string text,
      [in object modifiers]
    );
    
    Parameters
    text
    The text to type
    modifiers
    Object of modifiers for this keypress.
    Return value

    true if the action succeeds, otherwise false

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

    Document Tags and Contributors

    Contributors to this page: ahal, AndreeaMatei, kscarfone, arai
    Last updated by: kscarfone,